Create a payment intent

POST

/payment-intents

Creates a new payment intent representing a customer's intent to pay a specific amount in a given currency. You may optionally include a first intent action inline (via intent_action) to kick off the payment flow immediately — for example, authorizing a card or logging an offline payment — without needing a separate intent-action request.

When intent_action is provided and the action type is authorize, the service dispatches to the payment provider in the same call. If the provider requires additional authentication details (e.g. card PIN, 3DS device info), the response will contain a client_next_action object on intent_action describing the required fields.

If the inline action completes successfully in this same call and its amount fully satisfies the intent, the intent status will already read paid instead of pending.

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

Payment intent created successfully. If an intent_action was provided, the action result is embedded in intent_action on the response. When the action requires additional details from the customer (e.g. PIN or 3DS data), intent_action.client_next_action will describe what to collect and submit next.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

curl --location '/payment-intents' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id": "01HXYZ1234567890ABCDEFGHIJ",
    "currency": "NGN",
    "amount": 50000,
    "client_reference": "order_88abc123",
    "description": "Subscription renewal – Pro Plan",
    "counterparty": {
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "phonenumber": "+2348012345678"
    },
    "intent_action": {
        "action": "authorize",
        "payment_type": "card",
        "payment_instrument": {
            "card_session_token": "cvt_4f9a2b1c3d8e7f6a"
        },
        "return_url": "https://checkout.example.com/callback",
        "return_url_type": "redirect"
    }
}'

Response Example

201 - Success

{
    "message": "Payment intent created successfully",
    "status": "success",
    "data": {
        "id": "01HXYZ9876543210ZYXWVUTSRQ",
        "account_id": "01HXYZ1234567890ABCDEFGHIJ",
        "entity_id": "01HABC9999888877776666ZZZZZ",
        "amount": 50000,
        "currency": "NGN",
        "status": "pending",
        "client_reference": "order_88abc123",
        "description": "Subscription renewal – Pro Plan",
        "created": 1754393520000,
        "updated": 1754393520000,
        "counterparty": {
            "id": "01HCPT0000111122223333AAAA",
            "email": "jane.doe@example.com",
            "first_name": "Jane",
            "last_name": "Doe",
            "phonenumber": "+2348012345678"
        },
        "intent_action": {
            "id": "01HACT1111222233334444BBBBB",
            "action": "authorize",
            "payment_type": "card",
            "amount": 50000,
            "charged_amount": 51000,
            "source_amount": 50000,
            "source_currency": "NGN",
            "exchange_rate": 1,
            "currency": "NGN",
            "applicable_fee": 1000,
            "status": "pending",
            "auth_model": "pin",
            "action_current_step": "request_authmodel_details",
            "client_reference": "order_88abc123",
            "return_url": "https://checkout.example.com/callback",
            "return_url_type": "redirect",
            "created": 1754393520000,
            "updated": 1754393520000,
            "payment_instrument": {
                "id": "01HINS5555666677778888CCCCC",
                "card": {
                    "issuer_name": "First Bank of Nigeria",
                    "masked_pan": "458382xxxxxx1234",
                    "iin_v1": "458382",
                    "iin_v2": "45838200",
                    "last_four": "1234",
                    "expiry_month": "09",
                    "expiry_year": "27",
                    "type": "VISA",
                    "billing_address": null
                }
            },
            "client_next_action": {
                "type": "required_details",
                "required_details": {
                    "instruction_text": "Additional authentication details are required to process this payment. Please provide the following information.",
                    "fields": [
                        {
                            "name": "card_pin",
                            "label": "Card PIN",
                            "type": "pin"
                        }
                    ]
                }
            }
        }
    }
}

Modified at 2026-09-30 00:29:30

Look up the status of an intent action

Cancel a payment intent