TagPayTagPay

API Reference

Checkout Sessions

A Checkout Session is a short-lived, hosted payment page you mint server-side and redirect customers to. The customer picks a payment method, pays, and TagPay handles the rest — you poll the session for status or listen for the corresponding `charge.success` webhook.

Create a checkout session

POST/v1/checkout/sessions

Returns a session_key and a payment_url you redirect the customer to. The session inherits the mode (test/live) of the secret key used to create it. Sessions expire after expires_in_minutes (default 30) — once expired they cannot accept payment.

Body parameters

amountintegerrequired

Amount to charge, in kobo. NGN 5,000 = 500000. Must be at least the platform minimum.

referencestringrequired

Your unique reference for this payment. Echoed back on every related webhook. Max 100 characters.

currencystringoptional

ISO 4217 currency code. Defaults to NGN.

customer_emailstringoptional

Email to pre-fill on the checkout page.

customer_namestringoptional

Customer name to pre-fill on the checkout page.

callback_urlstringoptional

URL the customer is redirected to after a successful payment.

cancel_urlstringoptional

URL the customer is redirected to if they cancel.

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

Methods the customer may choose on the hosted page. Defaults to every method enabled on your account. Requested methods that aren't enabled for your account are silently dropped; the request fails only if nothing is left.

expires_in_minutesintegeroptional

Override the default session lifetime. Must be between 5 and 1440. Defaults to the platform default (30 minutes).

metadataobjectoptional

Arbitrary key/value pairs echoed back on the session and the underlying transaction.

Response

201
session_keystring

Session identifier, prefixed with `cs_`. Use this to poll status or build the payment URL.

payment_urlstring

Hosted checkout URL to redirect the customer to.

sessionobject

The created session object.

idstring

Internal session ID (UUID).

merchant_idstring

Merchant the session belongs to.

session_keystring

Session identifier, prefixed with `cs_`.

amountinteger

Amount in kobo.

currencystring

Currency code.

referencestring

Merchant reference.

customer_emailstring | null

Pre-filled customer email.

customer_namestring | null

Pre-filled customer name.

callback_urlstring | null

Post-payment redirect URL.

cancel_urlstring | null

Cancellation redirect URL.

payment_methodsarray<string>

Resolved payment methods after intersecting with what your account allows.

is_testboolean

`true` when the session was minted with a test secret key.

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

Lifecycle state. `open` for a freshly-minted session.

expires_atstring

ISO-8601 expiry timestamp.

completed_atstring | null

ISO-8601 timestamp the session completed, or `null`.

transaction_idstring | null

Linked transaction ID, populated once the customer picks a method.

metadataobject | null

Echoed metadata.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 timestamp of last mutation.

Errors

BAD_REQUEST400Amount is below the platform minimum, no requested payment methods are enabled for this merchant, or another field failed validation.
UNAUTHORIZED401API key missing or invalid.

Retrieve a checkout session

GET/v1/checkout/sessions/:session_key

Returns the session row as currently stored — including status and the linked transaction_id once a payment method has been chosen. Use this to poll for completion if you cannot rely on the charge.success webhook.

Path parameters

session_keystringrequired

Session key returned at creation, prefixed with cs_.

Response

200
idstring

Internal session ID (UUID).

merchant_idstring

Merchant the session belongs to.

session_keystring

Session identifier.

amountinteger

Amount in kobo.

currencystring

Currency code.

referencestring

Merchant reference.

customer_emailstring | null

Pre-filled customer email.

customer_namestring | null

Pre-filled customer name.

callback_urlstring | null

Post-payment redirect URL.

cancel_urlstring | null

Cancellation redirect URL.

payment_methodsarray<string>

Allowed payment methods for this session.

is_testboolean

`true` for test-mode sessions.

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

Lifecycle state. `open` = still accepting payment. `completed` = paid. `expired` = TTL elapsed. `cancelled` = explicitly cancelled.

expires_atstring

ISO-8601 expiry timestamp.

completed_atstring | null

ISO-8601 completion timestamp.

transaction_idstring | null

Linked transaction ID, populated once the customer picks a method.

metadataobject | null

Echoed metadata.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-mutation timestamp.

Errors

NOT_FOUND404No session with that key on this merchant account.