Create a payment page

POST

/payment-pages

Creates a hosted payment page that customers can visit to make a payment without you building a custom checkout UI. Creating a page also creates a backing payment intent (visible as payment_intent_id on the response) that tracks the money movement, and a stats record that tracks how many payments have been made against the page.

If slug is omitted, a unique, URL-safe slug is generated automatically from name. If you supply your own slug, it must not already be in use by another page.

amount is required unless configuration.amount_settings.is_dynamic_amount is true, in which case the customer chooses (or is constrained by configuration.amount_settings.min/max) how much to pay and amount may be omitted.

client_reference must be unique per entity — reusing one that already exists on another payment page for the same entity fails with a 400.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

The payment page was created successfully.

Bodyapplication/json

🟠400

🟠401

🟠404

🔴500

Request Example

Shell

JavaScript

Java

Swift

cURL

Minimal fixed-amount pageFully configured dynamic-amount page

curl --location '/payment-pages' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "account_id": "01HXYZ1234567890ABCDEFGHIJ",
    "currency": "NGN",
    "amount": 500000,
    "name": "Product Launch Donations",
    "client_reference": "campaign_launch_2026"
}'

Response Example

201 - Success

{
    "message": "Payment page created successfully",
    "status": "success",
    "data": {
        "id": "01HPAGE9876543210ZYXWVUTSR",
        "entity_id": "01HABC9999888877776666ZZZZZ",
        "account_id": "01HXYZ1234567890ABCDEFGHIJ",
        "currency": "NGN",
        "amount": 500000,
        "name": "Product Launch Donations",
        "title": null,
        "display_image": null,
        "cover_image": null,
        "slug": "product-launch-donations",
        "status": "draft",
        "payment_intent_id": "01HXYZ9876543210ZYXWVUTSRQ",
        "client_reference": "campaign_launch_2026",
        "client_meta": null,
        "expires_at": null,
        "qr_image_data": null,
        "configuration": {
            "is_single_use": false,
            "max_payments_allowed": null,
            "amount_settings": {
                "is_dynamic_amount": false,
                "min": null,
                "max": null
            },
            "thank_you_note": null,
            "additional_fields": []
        },
        "stats": {
            "total_payments": 0,
            "max_allowed_total_payments": null
        },
        "created": 1754393520000,
        "updated": 1754393520000
    }
}

Modified at 2026-09-15 11:41:25

Withdraw a maker-checker action

List payment pages