Skip to content
Nablr for BusinessNablr for Business

payment.failed

POST

The checkout closed after the customer’s last attempt failed. data is the payment. A checkout that expires with nothing paid and no failed attempt sends payment.abandoned instead.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Nablr-Signature
required
string

t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the endpoint secret>. After a secret roll with an overlap there is one v1= per secret; accept the request if any matches.

Example
t=1727788800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Nablr-Event-Id
required
string

The event id, the same as id in the body. Use it to ignore repeats.

Example
evt_01M3XXB7W2K9QF3N8D4H6J1T5R

Request Body

Section titled “Request Body”
Media typeapplication/json
object
id
required

The event id. The same event always has the same id, however often it is sent.

string
Example
evt_01M3XXB7W2K9QF3N8D4H6J1T5R
type
required

payment.refunded is reserved: it is accepted in events (so an endpoint that already lists it keeps working) but it is not part of “every event” and is not sent until refunds are available.

string
Allowed values: payment.succeeded payment.failed payment.abandoned payment.refunded payment_link.paid settlement.paid
created_at
required
string format: date-time
mode
required
string
Allowed values: test live
data
required

The object, as it was when the event happened.

object
type
required
Allowed value: payment.failed
data
required

channel is the method that paid: null until the payment succeeds, never the method of an attempt that failed.

fee, charged_amount and net are exact once the payment has succeeded: the price of the method that paid. Before that they are a quote, and nothing has been charged: the price of the method the customer last chose, or, before they choose, the highest across the methods offered (what the customer pays at most).

object
id
required
string
Example
pay_01M3XX8PCBFA5VZ3PQZQ0S78BP
object
required
string
Allowed value: payment
reference
required
string
Example
order_1042
status
required

pending: waiting for the customer. processing: the payment network has the payment and has not confirmed it. succeeded: paid. failed: the checkout closed after the last attempt failed. abandoned: the checkout closed with nothing tried. refunded and partially_refunded are reserved for refunds, which are not yet available.

string
Allowed values: pending processing succeeded failed abandoned refunded partially_refunded
mode
required
string
Allowed values: test live
amount
required

The amount you asked for, in kobo.

integer format: int64
Example
500000
currency
required
string
Allowed values: NGN
fee
required

Our fee, in kobo. Each method’s price is fixed when the payment is created; once succeeded this is the paying method’s fee, before that a quote (see above).

integer format: int64
Example
7500
fee_bearer
required

merchant: the fee comes out of amount. customer: the fee is added to what the customer pays.

string
Allowed values: merchant customer
charged_amount
required

What the customer pays, in kobo. amount, plus fee when the customer bears it. A quote until the payment succeeds.

integer format: int64
Example
500000
net
required

What you receive, in kobo. A quote until the payment succeeds.

integer format: int64
Example
492500
channel
required
One of:

A payment method. nablr is Pay with Nablr.

string
Allowed values: card bank_transfer ussd nablr
channels
required

The methods the checkout offers.

Array<string>
Allowed values: card bank_transfer ussd nablr
customer
required
object
id
required
string | null
Example
cus_01M3XX8ERVFY9A1FAQ2EGHYZWT
email
required
string
Example
ada@example.com
name
required
string | null
Example
Ada Obi
phone
required
string | null
metadata
required

What you sent. {} if you sent nothing.

object
key
additional properties
any
description
required
string | null
callback_url
required
string | null
payment_link_id
required

The payment link this payment came through, if any.

string | null
failure_reason
required

Why the last attempt failed, in words you can show the customer. null once succeeded.

string | null
Example
Your bank declined the card: insufficient funds.
authorization
required
One of:

How the payment was made, safe to show. Only the fields that apply are present.

object
brand

Card brand: visa, mastercard or verve.

string
Example
visa
last4
string
Example
4081
exp_month
integer
Example
12
exp_year
integer
Example
2030
bank
string
Example
Nablr Test Bank
nablr_handle
string
Example
ada
paid_at
required
string | null format: date-time
expires_at
required

When the checkout closes.

string format: date-time
settlement
required

The settlement (stl_…) that paid this out, once settled.

string | null
created_at
required
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

Any 2xx marks the delivery delivered.