Create checkout session

Create a hosted checkout session from your backend. Pasteaza returns a checkout URL that you can redirect your customer to. You can also pass the returned reference to the Pasteaza browser SDK to open checkout in a modal.

Payment methods can be configured from your Pasteaza dashboard. You can choose the exact methods you want to offer on checkout, and Bank Transfer is enabled by default.

Endpoint

POST /v1/checkout/sessions

Headers

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Request body

Field	Type	Required	Description
`amount`	integer	Yes	Amount to collect in kobo. Must be divisible by 100.
`currency`	string	No	Currency code. Only `NGN` is supported in Phase 1.
`description`	string	Yes	Product, service, invoice, or order description shown on checkout.
`customer.name`	string	No	Customer display name.
`customer.email`	string	No	Customer email address.
`customer.phone`	string	No	Customer phone number.
`redirectUrl`	string	No	URL to send the customer to after successful payment.
`metadata`	object	No	Your custom metadata, such as order IDs.
`expiresAt`	string	No	ISO date string. Defaults to 30 minutes from creation.

Example request

curl https://api.oyapasteaza.com/v1/checkout/sessions \
  -X POST \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "description": "Premium subscription",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "redirectUrl": "https://merchant.com/success",
    "metadata": {
      "orderId": "ORD_123"
    }
  }'

Successful response

{
  "status": true,
  "message": "Checkout session created successfully",
  "data": {
    "reference": "ch_Fb8z7rX8r9w2",
    "checkoutUrl": "https://checkout.oyapasteaza.com/ch_Fb8z7rX8r9w2",
    "expiresAt": "2026-07-22T12:30:00.000Z"
  }
}

Integration flow

Create session

Create the checkout session from your backend using your secret key.

Redirect customer

Redirect your customer to the checkoutUrl returned by Pasteaza, or pass the reference to PasteAZA.checkout.

Customer pays

The hosted page displays enabled payment methods. In Phase 1, Bank Transfer generates a dedicated virtual account.

Receive webhook

Pasteaza confirms payment, credits your primary Pasteaza wallet, and sends checkout.payment.success.

Error responses

{
  "status": false,
  "message": "amount must be a positive integer in kobo and divisible by 100.",
  "code": "validation_failed"
}

Common errors include invalid API key, unsupported currency, invalid redirect URL, expired session, and disabled payment method.

Getting Started

Collections

Disbursements

Create checkout session

Endpoint

Headers

Request body

Example request

Successful response

Integration flow

Error responses

​Endpoint

​Headers

​Request body

​Example request

​Successful response

​Integration flow

​Error responses

Endpoint

Headers

Request body

Example request

Successful response

Integration flow

Error responses