Checkout API

Generate a secure, hosted checkout link for your customers. With a single API call, Uverus creates a dynamic payment page supporting Cards, Bank Transfers, and USSD.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer sk_test_...` (test) or `Bearer sk_live_...` (live) — see Authentication

Generate Checkout Link

Create a new checkout session.

POST /api/v1/payments/checkout

Request Body

Field	Type	Required	Description
`email`	`string`	Yes	Customer's email address
`amount`	`integer`	Yes	Amount in kobo/lowest denomination (e.g., `500000` = ₦5,000)
`currency`	`string`	No	Currency code (defaults to `NGN`)
`reference`	`string`	No	Unique transaction reference. Auto-generated if omitted.
`callback_url`	`string`	No	URL to redirect the customer to after payment completion
`metadata`	`object`	No	Custom data object to pass along with the transaction
`channels`	`array`	No	Allowed payment methods, e.g. `["card", "bank_transfer", "ussd"]`
`split_code`	`string`	No	Optional code for split payments
`bearer`	`string`	No	Who bears the transaction fees: `"account"` or `"subaccount"`
`label`	`string`	No	A custom label or description for the payment
`vatPercent`	`number`	No	VAT percentage to apply to this transaction, overriding your account default

Example Request

curl -X POST "https://api.uveruspayments.com/api/v1/payments/checkout" \
     -H "Authorization: Bearer sk_test_..." \
     -H "Content-Type: application/json" \
     -d '{
       "email": "customer@example.com",
       "amount": 500000,
       "currency": "NGN",
       "reference": "TXN_123456789",
       "callback_url": "https://yourapp.com/payment/callback",
       "label": "Premium Subscription"
     }'

Example Response

{
  "success": true,
  "message": "Checkout link generated successfully",
  "data": {
    "checkoutUrl": "https://checkout.uveruspayments.com/checkout/TXN_123456789",
    "reference": "TXN_123456789",
    "accessCode": "uuid-string-here"
  }
}

Redirect your customer to checkoutUrl to complete payment securely.

Verify Payment Status

Check the current status of a checkout session — useful after your customer returns from checkout, or on a schedule if you're not using webhooks.

GET /api/v1/payments/verify/{reference}

Note

This only reflects the provider's status once your customer has actually attempted a charge (selected a channel and submitted payment details). A freshly-created, untouched session stays pending.

Example Request

curl -X GET "https://api.uveruspayments.com/api/v1/payments/verify/TXN_123456789" \
     -H "Authorization: Bearer sk_test_..."

Example Response

{
  "reference": "TXN_123456789",
  "amount": 500000,
  "currency": "NGN",
  "status": "completed",
  "mode": "test",
  "customerEmail": "customer@example.com",
  "completedAt": "2026-08-27T10:15:00.000Z"
}

status is one of pending, processing, completed, or failed. See the Webhooks guide for getting notified the moment a payment settles, instead of polling this endpoint.

Checkout API

On this page