Payments

A payment intent tracks one payment from the moment you ask for it until the money arrives. Create one per order, send the customer to checkout, and follow its status.

Statuses#

Status	Meaning
`created`	Not paid yet. The customer hasn't started.
`processing`	The customer started paying: they entered a card, or were given an account to transfer into.
`successful`	The money arrived. Fulfil the order.
`failed`	The last try failed. The customer can try again on the same page.
`abandoned`	Still `processing` after 30 minutes with no money. The customer can still pay.
`canceled`	You canceled it.

text

created → processing → successful
                     ↘ failed → (customer tries again) → processing
                     ↘ abandoned (after 30 minutes) → successful if money arrives late
created / failed / abandoned → canceled

Late money always wins. If a transfer lands after a payment was marked abandoned or failed, it becomes successful and you get a payment_intent.successful webhook. Don't treat abandoned as final.

Each change sends a webhook: payment_intent.successful, payment_intent.failed, payment_intent.abandoned or payment_intent.canceled.

Creating a payment#

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" }'

Field
`amount`	Required. Integer in the smallest unit: kobo for `NGN`, cents for `USD`.
`currency`	Required. `NGN` or `USD` (dollar payments need dollar collections turned on, and are card only).
`reference`	Your own order reference. Unique per account and mode, so it also stops double charges.
`description`	Shown to the customer at checkout.
`customer_email`, `customer_name`	Pre-fill checkout and link the payment to a customer.
`brand`	Which of your brands it's for (its name and logo show at checkout).
`save_payment_method`	Save the card for subscriptions. Needs `customer_email`.
`metadata`	Up to 20 keys of your own (string values up to 500 characters), returned on the payment and in webhooks.
`return_url`	Your page to send the customer back to after they pay. See Sending the customer back.

The response includes fees (the fee, VAT and what you'll receive). It's an estimate until the payment succeeds, then final for the way the customer actually paid.

Checkout#

Send the customer to:

text

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

Checkout offers card and bank transfer. For a transfer, the customer gets an account number for this payment; when the money lands, the payment becomes successful.

Sending the customer back#

Pass return_url when you create the payment, and checkout sends the customer there once the payment is successful (after a few seconds, or straight away if they tap the button). Biftpay adds the payment's id and status to the address:

text

https://shop.example.com/orders/1042/complete?payment_intent=5b0c3f6e-...&status=successful

Before paying, the customer can also choose Cancel and return, which sends them to the same address with the current status (for example created or failed). The payment isn't canceled: they can come back and pay.

return_url must start with https:// (http:// is accepted in test mode, for local development).
Don't treat the redirect as proof of payment. Anyone can type that address. On your return page, fetch GET /v1/payment_intents/{id} (or rely on the payment_intent.successful webhook) before fulfilling the order.
Customers paying by transfer may close the page before the money lands, so they might never come back. The webhook still arrives.

If you'd rather not build an order flow at all, use payment links: a page you share that creates a payment each time someone pays.

Canceling#

POST /v1/payment_intents/{id}/cancel stops an unpaid payment: one that is created, failed or abandoned. A payment that is processing can't be canceled, because money may be on its way. Once successful, use a refund instead.

Other ways to collect#

Virtual accounts: a permanent account number for one customer. Every transfer into it becomes a successful payment. See Virtual accounts.
Subscriptions: charge a saved card every week, month or year. See Subscriptions.
Invoices: Biftpay emails the customer a checkout link and marks the invoice paid. See Invoices.