Biftpaydocs
Dashboard

Refunds

List refunds

get/v1/refunds

Parameters

limitintegerin query

1 to 100 · default 20

payment_intentstring (uuid)in query
bash
curl https://sandbox.api.biftpay.com/v1/refunds \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    Refunds, newest firstobject
    Fields
    object"list"required
    dataarray of Refundrequired
    Fields of data
    idstring (uuid)required
    object"refund"required
    livemodebooleanrequired
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonstring | null
    statuspending | succeeded | failedrequired
    failure_codestring | null
    created_atstring (date-time)required
    succeeded_atstring (date-time) | null
    failed_atstring (date-time) | null
    has_morebooleanrequired

Refund a successful payment, in full or in part

post/v1/refunds

Sent back through the provider that charged the customer. The amount is held from the merchant's balance (pending if not yet released, else available) into refund_in_flight, then settled when the provider confirms or returned if it fails. Processing fees aren't returned. Omit amount to refund what's left.

A payment with an open dispute can't be refunded (409 payment_disputed): the chargeback already returns the money, so answer the dispute instead. What a lost dispute returned counts towards the amount already refunded.

In test mode, amounts ending in 13 kobo are rejected and ending in 17 stay pending.

Parameters

Idempotency-Keystringin headerrequired

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

up to 255 characters

Body

payment_intentstring (uuid)required
amountinteger

Defaults to the full remaining amount.

at least 1

reasonrequested_by_customer | duplicate | fraudulent
bash
curl -X POST https://sandbox.api.biftpay.com/v1/refunds \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": "…"
  }'

Responses

  • 201
    CreatedRefund
    Fields
    idstring (uuid)required
    object"refund"required
    livemodebooleanrequired
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonstring | null
    statuspending | succeeded | failedrequired
    failure_codestring | null
    created_atstring (date-time)required
    succeeded_atstring (date-time) | null
    failed_atstring (date-time) | null
  • 400
    Invalid request
  • 404
    Not found, or not visible to this key
  • 409
    The object is in a state that doesn't allow this

Retrieve a refund

get/v1/refunds/{id}

Parameters

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

Responses

  • 200
    The refundRefund
    Fields
    idstring (uuid)required
    object"refund"required
    livemodebooleanrequired
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonstring | null
    statuspending | succeeded | failedrequired
    failure_codestring | null
    created_atstring (date-time)required
    succeeded_atstring (date-time) | null
    failed_atstring (date-time) | null
  • 404
    Not found, or not visible to this key