Biftpaydocs
Dashboard

Payment intents

List payment intents

get/v1/payment_intents

Parameters

limitintegerin query

1 to 100 · default 20

starting_afterstring (uuid)in query

The id of the last item on the previous page.

customerstring (uuid)in query
statuscreated | processing | successful | failed | abandoned | canceledin query
bash
curl https://sandbox.api.biftpay.com/v1/payment_intents \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    A page of payment intentsPaymentIntentList
    Fields
    object"list"required
    dataarray of PaymentIntentrequired
    Fields of data
    idstring (uuid)required
    object"payment_intent"required
    livemodebooleanrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    statuscreated | processing | successful | failed | abandoned | canceledrequired

    created not paid yet; processing the customer started paying (entered a card, or was given an account to transfer into); successful the money arrived; failed the last try failed and the customer may try again; abandoned processing for 30 minutes with no money (the customer may still pay); canceled canceled by the business. Money that arrives late always makes a payment successful.

    referencestring | null
    descriptionstring | null
    customer_emailstring | null
    brandstring (uuid) | null
    customerstring (uuid) | null
    payment_linkstring (uuid) | null
    metadataobjectrequired

    up to 20 keys

    feesobjectrequired

    An estimate (at the card price) until the payment succeeds; then final, at the price for the channel and provider that took it. fee + vat + net = amount.

    Fields of fees
    feeintegerrequired

    Minor units (kobo, cents).

    at least 0

    vatintegerrequired

    Minor units (kobo, cents).

    at least 0

    netintegerrequired

    Minor units (kobo, cents).

    at least 0

    failure_codestring | null
    created_atstring (date-time)required
    updated_atstring (date-time)required
    paid_atstring (date-time) | null

    When the payment became successful.

    canceled_atstring (date-time) | null
    return_urlstring | null

    Where checkout sends the customer after paying.

    client_secretstring

    Only in the response that creates the payment. Give it to the customer's checkout page; it can act on this one payment only.

    has_morebooleanrequired
  • 401
    Missing or invalid API key

Create a payment intent

post/v1/payment_intents

Fees and VAT are calculated from the merchant's pricing and fixed on the intent at creation.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

amountintegerrequired

at least 1

currencyNGN | USDrequired
referencestring

Your own reference; unique per merchant and mode.

up to 100 characters

descriptionstring

up to 500 characters

customer_emailstring (email)
customer_namestring

up to 200 characters

brandstring (uuid)

Attribute the payment to one of your brands.

save_payment_methodboolean

Save the card used at checkout for subscriptions. Needs customer_email.

metadataobject

up to 20 keys

return_urlstring

Where checkout sends the customer after a successful payment, with payment_intent and status added to the query. https only (http is accepted in test mode). Don't treat the redirect as proof of payment: confirm with the webhook or GET /v1/payment_intents/{id}.

up to 2000 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/payment_intents \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "currency": "NGN"
  }'

Responses

  • 201
    CreatedPaymentIntent
    Fields
    idstring (uuid)required
    object"payment_intent"required
    livemodebooleanrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    statuscreated | processing | successful | failed | abandoned | canceledrequired

    created not paid yet; processing the customer started paying (entered a card, or was given an account to transfer into); successful the money arrived; failed the last try failed and the customer may try again; abandoned processing for 30 minutes with no money (the customer may still pay); canceled canceled by the business. Money that arrives late always makes a payment successful.

    referencestring | null
    descriptionstring | null
    customer_emailstring | null
    brandstring (uuid) | null
    customerstring (uuid) | null
    payment_linkstring (uuid) | null
    metadataobjectrequired

    up to 20 keys

    feesobjectrequired

    An estimate (at the card price) until the payment succeeds; then final, at the price for the channel and provider that took it. fee + vat + net = amount.

    Fields of fees
    feeintegerrequired

    Minor units (kobo, cents).

    at least 0

    vatintegerrequired

    Minor units (kobo, cents).

    at least 0

    netintegerrequired

    Minor units (kobo, cents).

    at least 0

    failure_codestring | null
    created_atstring (date-time)required
    updated_atstring (date-time)required
    paid_atstring (date-time) | null

    When the payment became successful.

    canceled_atstring (date-time) | null
    return_urlstring | null

    Where checkout sends the customer after paying.

    client_secretstring

    Only in the response that creates the payment. Give it to the customer's checkout page; it can act on this one payment only.

  • 400
    Invalid request
  • 401
    Missing or invalid API key
  • 409
    The object is in a state that doesn't allow this
  • 422
    Idempotency-Key reused with a different request

Retrieve a payment intent

get/v1/payment_intents/{id}

Parameters

idstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/payment_intents/{id} \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    The payment intentPaymentIntent
    Fields
    idstring (uuid)required
    object"payment_intent"required
    livemodebooleanrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    statuscreated | processing | successful | failed | abandoned | canceledrequired

    created not paid yet; processing the customer started paying (entered a card, or was given an account to transfer into); successful the money arrived; failed the last try failed and the customer may try again; abandoned processing for 30 minutes with no money (the customer may still pay); canceled canceled by the business. Money that arrives late always makes a payment successful.

    referencestring | null
    descriptionstring | null
    customer_emailstring | null
    brandstring (uuid) | null
    customerstring (uuid) | null
    payment_linkstring (uuid) | null
    metadataobjectrequired

    up to 20 keys

    feesobjectrequired

    An estimate (at the card price) until the payment succeeds; then final, at the price for the channel and provider that took it. fee + vat + net = amount.

    Fields of fees
    feeintegerrequired

    Minor units (kobo, cents).

    at least 0

    vatintegerrequired

    Minor units (kobo, cents).

    at least 0

    netintegerrequired

    Minor units (kobo, cents).

    at least 0

    failure_codestring | null
    created_atstring (date-time)required
    updated_atstring (date-time)required
    paid_atstring (date-time) | null

    When the payment became successful.

    canceled_atstring (date-time) | null
    return_urlstring | null

    Where checkout sends the customer after paying.

    client_secretstring

    Only in the response that creates the payment. Give it to the customer's checkout page; it can act on this one payment only.

  • 401
    Missing or invalid API key
  • 404
    Not found, or not visible to this key

Cancel a payment intent

post/v1/payment_intents/{id}/cancel

Only an unpaid intent (status created, failed or abandoned) can be canceled.

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/payment_intents/{id}/cancel \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The canceled payment intentPaymentIntent
    Fields
    idstring (uuid)required
    object"payment_intent"required
    livemodebooleanrequired
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    statuscreated | processing | successful | failed | abandoned | canceledrequired

    created not paid yet; processing the customer started paying (entered a card, or was given an account to transfer into); successful the money arrived; failed the last try failed and the customer may try again; abandoned processing for 30 minutes with no money (the customer may still pay); canceled canceled by the business. Money that arrives late always makes a payment successful.

    referencestring | null
    descriptionstring | null
    customer_emailstring | null
    brandstring (uuid) | null
    customerstring (uuid) | null
    payment_linkstring (uuid) | null
    metadataobjectrequired

    up to 20 keys

    feesobjectrequired

    An estimate (at the card price) until the payment succeeds; then final, at the price for the channel and provider that took it. fee + vat + net = amount.

    Fields of fees
    feeintegerrequired

    Minor units (kobo, cents).

    at least 0

    vatintegerrequired

    Minor units (kobo, cents).

    at least 0

    netintegerrequired

    Minor units (kobo, cents).

    at least 0

    failure_codestring | null
    created_atstring (date-time)required
    updated_atstring (date-time)required
    paid_atstring (date-time) | null

    When the payment became successful.

    canceled_atstring (date-time) | null
    return_urlstring | null

    Where checkout sends the customer after paying.

    client_secretstring

    Only in the response that creates the payment. Give it to the customer's checkout page; it can act on this one payment only.

  • 404
    Not found, or not visible to this key
  • 409
    The object is in a state that doesn't allow this

Every try behind a payment, in order

get/v1/payment_intents/{id}/charge_attempts

Each card or transfer try, in order: for example a declined card followed by one that worked.

Parameters

idstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/payment_intents/{id}/charge_attempts \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    Attemptsobject
    Fields
    object"list"required
    dataarray of ChargeAttemptrequired
    Fields of data
    idstring (uuid)required
    object"charge_attempt"required
    channelcard | bank_transfer | virtual_accountrequired
    statuspending | succeeded | failed | unknown | canceledrequired
    failure_codestring | null
    has_moreboolean
  • 404
    Not found, or not visible to this key