Create an intent action

POST

/intent-actions

Attaches a new payment action to an existing payment intent that is still in a pending state. An intent action represents a single attempt to collect payment — for example, authorizing a card or logging an offline settlement.

The action is dispatched to the configured payment provider in the same request when action is authorize. If the card's auth model requires additional details (e.g. PIN, billing address, or 3DS device metadata), the response will include a client_next_action object on the root payload describing exactly what to collect from the customer next. You then submit those details via the Patch Intent Action endpoint.

If the action completes successfully within this call (e.g. a card that requires no further steps), the resolved status will be successful rather than pending.

The entity_id is derived from the authenticated token and must match the entity that owns the referenced payment intent — mismatches result in a 404.

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 intent action was created successfully. The root payload is the normalized action object. Check status to determine whether the action completed immediately (successful) or requires further steps (pending). If client_next_action is present, collect the listed fields from the customer and submit them via the Patch Intent Action endpoint.

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🟠409

🟠422

Request Example

Shell

JavaScript

Java

Swift

curl --location '/intent-actions' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "payment_intent_id": "01HXYZ1234567890ABCDEFGHIJ",
    "client_reference": "order_88abc123_action1",
    "action": "authorize",
    "payment_type": "card",
    "amount": 50000,
    "currency": "NGN",
    "return_url": "https://checkout.example.com/callback",
    "return_url_type": "redirect",
    "payment_instrument": {
        "card_session_token": "cvt_4f9a2b1c3d8e7f6a",
        "card_pin": "1234",
        "bank_account": {
            "account_number": "0123456789",
            "issuer_code": "057"
        },
        "billing_address": {
            "line1": "12 Marina Street",
            "line2": "Flat 3B",
            "code": "100001",
            "code_type": "postal",
            "city": "Lagos",
            "state": "Lagos",
            "country": "Nigeria"
        },
        "client_web_meta": {
            "device_info": {
                "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
                "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                "enabled_languages": [
                    "en-US",
                    "en",
                    "fr"
                ],
                "language": "en-US",
                "screen": {
                    "color_depth": "24",
                    "height": "900",
                    "width": "1440"
                },
                "timezone_offset": "-60"
            }
        }
    }
}'

Response Example

201 - Action pending — PIN required

{
    "message": "Intent action created successfully",
    "status": "success",
    "data": {
        "id": "01JACTION567890ABCDEFGHIJ",
        "action": "authorize",
        "payment_type": "card",
        "amount": 50000,
        "charged_amount": 50700,
        "source_amount": 50000,
        "source_currency": "NGN",
        "exchange_rate": 1,
        "currency": "NGN",
        "applicable_fee": 700,
        "status": "pending",
        "auth_model": "pin",
        "action_current_step": "request_authmodel_details",
        "client_reference": "order_88abc123_action1",
        "payment_instrument": {
            "id": "01JINSTR7890ABCDEFGHIJKLMN",
            "card": {
                "issuer_name": "Access Bank",
                "masked_pan": "412345xxxxxx9012",
                "iin_v1": "412345",
                "last_four": "9012",
                "expiry_month": "08",
                "expiry_year": "2028",
                "type": "visa"
            }
        },
        "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": [
                    "card_pin"
                ]
            }
        },
        "created": 1754482320000,
        "updated": 1754482320000,
        "intent": {
            "id": "01HXYZ1234567890ABCDEFGHIJ",
            "account_id": "01HACCOUNT890ABCDEFGHIJKLM",
            "entity_id": "01HENTITY567890ABCDEFGHIJK",
            "amount": 50000,
            "currency": "NGN",
            "status": "pending",
            "client_reference": "order_88abc123",
            "created": 1754482200000,
            "updated": 1754482320000,
            "counterparty": {
                "id": "01HCPTY5678901ABCDEFGHIJKL",
                "email": "jane.doe@example.com",
                "first_name": "Jane",
                "last_name": "Doe"
            }
        }
    }
}

Modified at 2026-08-06 07:42:15

Retrieve a payment intent

Advance an intent action to the next step