API explorerDeveloper Portal
Getting Started

Sections

    API explorer
    Developer Portal

    Theme switcher

    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 ".

    To know how to get your secret key, please check the Getting Integration Credentials page.

    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.

    To know how to get your integration ID, please check the Getting Integration Credentials page.

    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

    This is the secret key which you can get 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
    Was this section helpful?

    What made this section unhelpful for you?

    Base URL

    Production:

    Sandbox:

    Language Box

    POST

    /

    Select
    1

    Response

    Was this section helpful?

    What made this section unhelpful for you?

    View as Markdown

    Ask an AI

    Open in ChatGPTOpen in ClaudeOpen in Perplexity

    Code with AI

    Open in Copilot