Getting Started

Create Intention

Outcome - Create an Intention that will be used to complete a payment, either via APIs or through one of our UI options.

Authorization

Add your “secret key“ in the authorization header preceded by the word "Token ".

Key values in the response

You'll receive a response, which is an object that represents an intention and includes all the intention details.

Important parameters: Order ID: Paymob order ID, which will be received in the transaction callback and can be used to correlate the transaction to the order on your system.
Intention ID: Paymob intention ID can be used to do the same as the Order ID.
Client Secret: A unique, intention-specific token used to redirect the customer to Paymob’s Unified Checkout or to render Paymob’s Pixel component.

Common Errors

Using a wrong or not well-configured integration ID

Status Code: 404 Not Found

JSON

 {
    "detail": "Integration ID/Name does not exist in our system . You can find the list of Integration ID’/Names from Merchant Dashboard under Developers → Payment Integrations Tab"
}

Solution: Make sure to use an integration ID that has the following criteria:

1 - Has the same status as the used secret key (Test/Live)

2 - Valid ID related to your account and for online integration.

3 - Well-configured integration ID. You can contact support@paymob.com to help with checking the integration ID configurations.

Missing item name or amount

Status Code: 400 Bad Request

JSON

 {
    "items": {
        "name": [
            "This field is required."
        ]
    }
}

JSON

 {
    "items": {
        "amount": [
            "This field is required."
        ]
    }
}

Solution: Make sure to include the name and amount fields in each object within the items array.

Missing phone number in the billing data object

Status Code: 400 Bad Request

JSON

 {
    "billing_data": {
        "phone_number": [
            "This field is required."
        ]
    }
}

Solution: Make sure to enter a phone number.

Header Parameters

Authorizationstring

You can get your secret key from your Dashboard

Content-Typestring

Body Parameters

amountnumber Required

The total transaction amount, expressed in cents.

currencystring Required

The currency in which the transaction is processed. This must match the currency of the selected Integration ID.

payment_methodsarray Required

The Integration ID(s) used to process the payment. Values can be provided as integers (e.g., 1256) or as names enclosed in quotes (e.g., "card"). The status (Live/Test) of the provided ID(s) should match the status of the secret key used for authentication.

Show child attributes

itemsarray

Show child attributes

billing_dataobject

Show child attributes

extrasobject

A set of additional custom parameters provided by the merchant. These values are returned in callbacks under the payment key claims object.

Show child attributes

special_referencestring

A unique reference associated with the transaction or order, returned in the transaction callback under merchant_order_id.

expirationnumber

notification_urlstring

A callback URL that receives a POST request with full transaction details after the transaction succeeds or fails. Supported only with card Integration IDs. This endpoint

redirection_urlstring

A URL to which the customer is redirected after the transaction completes, with transaction details included as query parameters. Supported only with card and wallet payment methods. > ⚠️ Important Notes

The endpoint used in the notification URL will receive the transaction callback (transaction details) and the card token (for pay with saved card features)

Response

201

Object

Payment Intention created successfully

Response Attributes

payment_keysarray

Show child attributes

intention_order_idnumber

idstring

intention_detailobject

Show child attributes

client_secretstring

payment_methodsarray

Show child attributes

special_referencestring

extrasobject

Show child attributes

confirmedboolean

statusstring

createdstring

card_detailstring

card_tokensarray

objectstring

Production:

Sandbox:

Sections

Create Intention

Authorization

Key values in the response

Common Errors

Header Parameters

Body Parameters

Response

Response Attributes

What made this section helpful for you?

What made this section unhelpful for you?

Language Box

Response

What made this section helpful for you?

What made this section unhelpful for you?

Sections

Create Intention

Authorization

Key values in the response

Common Errors

Header Parameters

Body ParametersExpand all

ResponseExpand all

Response Attributes

What made this section helpful for you?

What made this section unhelpful for you?

Language Box

Response

What made this section helpful for you?

What made this section unhelpful for you?

Ask an AI

Code with AI

Body Parameters

Response