Advance an intent action to the next step

PATCH

/intent-actions/{id}

Submits the data required to progress a pending intent action to the next processing step. Call this endpoint when a payment action is waiting for additional input — either authorize (to supply payment instrument details such as card PIN or billing address) or validate (to submit an OTP). The action must be in pending status and its action_current_step must match the expected step for the supplied action value. On success the action is re-dispatched to the payment provider, and if the provider deems it successful the parent payment intent is automatically finalized.

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 ********************

Path Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

The intent action was successfully advanced. The response reflects the updated action state after the provider re-dispatch. If the provider marks the action successful, the parent intent is also finalized and its status is updated accordingly.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Authorize with card PINAuthorize with billing address (AVS)Authorize with 3DS device fingerprintValidate with OTP

curl --location --request PATCH '/intent-actions/01J3KQZM0000000000000000AC' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "action": "authorize",
    "payment_instrument": {
        "card_pin": "1234"
    }
}'

Response Example

200 - Action completed — intent finalized

{
    "message": "Intent action updated successfully",
    "status": "success",
    "data": {
        "id": "01J3KQZM0000000000000000AC",
        "action": "authorize",
        "payment_type": "card",
        "amount": 5000,
        "charged_amount": 5150,
        "source_amount": 5000,
        "source_currency": "NGN",
        "exchange_rate": 1,
        "currency": "NGN",
        "applicable_fee": 150,
        "status": "successful",
        "client_reference": "order_ref_7892",
        "payment_instrument": {
            "id": "01J3KQZM0000000000000000DE",
            "card": {
                "issuer_name": "First Bank of Nigeria",
                "masked_pan": "411111xxxxxx1111",
                "iin_v1": "411111",
                "iin_v2": "41111100",
                "last_four": "1111",
                "expiry_month": "09",
                "expiry_year": "2027",
                "type": "visa",
                "billing_address": null
            }
        },
        "created": 1722873600000,
        "updated": 1722873720000,
        "intent": {
            "id": "01J3KQZM0000000000000000AB",
            "account_id": "01J3KQZM0000000000000000AA",
            "entity_id": "01J3KQZM00000000000000000E",
            "amount": 5000,
            "currency": "NGN",
            "status": "successful",
            "client_reference": "order_7892",
            "description": "Payment for Order #7892",
            "created": 1722873600000,
            "updated": 1722873720000,
            "counterparty": {
                "id": "01J3KQZM0000000000000000CF",
                "email": "customer@example.com",
                "first_name": "John",
                "last_name": "Doe",
                "phonenumber": "+2348012345678"
            }
        }
    }
}

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

Create an intent action

Retrieve the authentication session for a pending redirect action