Quickstart

Take your first test payment in a few minutes: create a payment, send your customer to Biftpay's checkout, and hear back when the money arrives.

1. Get your test key#

In the dashboard, open Developers → API keys and create a key. Test keys start with bp_test_; they only ever touch test data, so you can't move real money by mistake.

Keep secret keys on your server. Never put them in a mobile app, a browser or a public repository.

Every request sends the key as a bearer token:

bash

curl https://sandbox.api.biftpay.com/v1/balance \
  -H "Authorization: Bearer bp_test_..."

2. Create a payment#

A payment intent is one payment you expect from a customer. Amounts are whole numbers in the smallest unit: 1000000 kobo is ₦10,000.

bash

curl https://sandbox.api.biftpay.com/v1/payment_intents \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "currency": "NGN",
    "reference": "order-1042",
    "customer_email": "ada@example.com",
    "return_url": "https://shop.example.com/orders/1042/complete"
  }'

The response is the payment, with status: "created" and a client_secret:

json

{
  "id": "5b0c3f6e-1d2a-4c55-9f0e-7a1b2c3d4e5f",
  "object": "payment_intent",
  "amount": 1000000,
  "currency": "NGN",
  "status": "created",
  "reference": "order-1042",
  "client_secret": "5b0c3f6e-1d2a-4c55-9f0e-7a1b2c3d4e5f_secret_..."
}

client_secret is only returned here. It lets a checkout page act on this one payment and nothing else, so it's safe to hand to your customer.

3. Send your customer to checkout#

Redirect the customer to Biftpay's hosted checkout:

text

https://sandbox.checkout.biftpay.com/checkout/{id}?cs={client_secret}

They can pay by card or by bank transfer to an account number shown on the page. Card details go straight to Biftpay; they never touch your servers. Once paid, checkout sends them back to your return_url with ?payment_intent={id}&status=successful added.

4. Hear when it's paid#

Add a webhook endpoint (Developers → Webhooks, or the API) and Biftpay will POST a payment_intent.successful event to it when the money arrives. Check the signature, then fulfil the order. See Webhooks.

Webhooks are the source of truth: a customer can close the page before it reloads, or pay by transfer minutes later. If you want to double-check, fetch the payment:

bash

curl https://sandbox.api.biftpay.com/v1/payment_intents/{id} \
  -H "Authorization: Bearer bp_test_..."

Next#

Testing: test cards and helpers that move a payment along without waiting.
Payments: every status a payment goes through.
Going live: what's needed before your live key works.