TagPayTagPay

API Reference

Charges

A Charge is the result of attempting to collect money from a customer using a card, bank transfer, or USSD. The TagPay API exposes endpoints to initialize a charge, verify its status, and look up details.

Create a charge

POST/v1/checkout/sessions

Initializes a charge by creating a checkout session. The response includes a hosted payment URL the customer can be redirected to, plus a session key you can use to poll status or correlate with a webhook.

Amounts are in kobo — the smallest unit of NGN. NGN 5,000.00 is 500000.

Body parameters

amountintegerrequired

Amount in kobo. Minimum 100 (NGN 1.00).

referencestringrequired

Your unique reference for this charge. Used to verify and dedupe.

currencystringoptional

Three-letter ISO currency code. Defaults to NGN.

Allowed: 'NGN'

customer_emailstringoptional

Customer email — pre-filled on the hosted page and attached to the resulting transaction.

customer_namestringoptional

Customer name — pre-filled on the hosted page.

payment_methodsarray<'card' | 'bank_transfer' | 'ussd'>optional

Payment methods to enable on the hosted page. Defaults to all methods enabled on the merchant account.

callback_urlstringoptional

Where to redirect the customer after a successful payment. Defaults to the URL configured in dashboard settings.

cancel_urlstringoptional

Where to redirect the customer if they abandon the checkout.

expires_in_minutesintegeroptional

How long this session is valid. Between 5 and 1440 (24 hours). Defaults to 30 minutes.

metadataobjectoptional

Arbitrary key/value pairs (max 20 keys, values up to 500 chars).

Response

201
session_keystring

TagPay-assigned session key (prefixed `cs_`). Use it to poll status or correlate webhooks.

payment_urlstring

Hosted page URL to redirect the customer to.

referencestring

The reference you supplied. Use this with the verify endpoint after payment.

amountinteger

Amount in kobo.

statusenum<'open' | 'completed' | 'expired' | 'cancelled'>

Session status. Always `open` at creation.

expires_atstring

ISO-8601 timestamp after which this session can no longer be paid.

Errors

INVALID_AMOUNT400Amount must be a positive integer in kobo.
VALIDATION_ERROR400One or more body fields failed validation.
UNAUTHORIZED401API key missing or invalid.

Verify a charge

GET/v1/transactions/verify/:reference

Always trust this endpoint over the redirect query string — the redirect can be tampered with by a malicious customer. Verify before fulfilling an order.

Path parameters

referencestringrequired

The reference returned when the charge was created.

Response

200
referencestring

The merchant-supplied reference.

statusenum<'pending' | 'success' | 'failed'>

Final status. Treat anything other than `success` as unpaid.

amountinteger

Amount in kobo.

payment_methodstring

How the customer paid: `card`, `bank_transfer`, or `ussd`.

paid_atstring | null

ISO-8601 timestamp of successful payment, or null.

customerobject

Customer details supplied at charge creation.

emailstring

Customer email.

metadataobject | null

Whatever was supplied at creation.

Errors

NOT_FOUND404No transaction with that reference.