Skip to main content
GET
Get a bill payment

Error codes

Authorizations

Authorization
string
header
required

A secret API key, sent as Authorization: Bearer sk_test_… in sandbox or Bearer sk_live_… in live.

Path Parameters

paymentId
string
required

Bill payment ULID. A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

Response

Successful response.

id
string
required

A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

externalReference
string
required
paymentReference
string
required

Sakawave’s own reference for the payment.

providerTransactionId
string | null
required
status
enum<string>
required

confirmed is the success state, not completed.

Available options:
submitted,
pending,
confirmed,
failed
subCategory
string
required

What kind of bill this was: airtime, data, utility, cable_tv, betting, and so on.

amount
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

charge
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

commission
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

totalDebit
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

currency
enum<string>
required

Bill payments are NGN only.

Available options:
NGN
group
object
required
biller
object
required
package
object
required
customerReferenceLast4
string | null
required

The last four characters of the meter, account, or phone number paid.

customerName
string
required
customerAddress
string | null
required
vendStatus
string | null
required

The biller’s own delivery status, upper-cased.

providerStatusCode
string | null
required
tokenData
object | null
required

The credential the biller issued, where there is one — a prepaid electricity token, for instance. Shape varies by biller.

failureReason
string | null
required
createdAt
string<date-time>
required
Example:

"2026-08-14T09:00:00.000Z"

updatedAt
string<date-time>
required
Example:

"2026-08-14T09:00:00.000Z"