Generating a Payment Key

Sections

API explorerChangelogPostman Collection
API explorer
Changelog
Postman Collection

Theme switcher

Getting Started - Egypt

Sign up for registering a new account

A guide to registering a new accept account.

Why do I have to? In order to deal with any of Accept's services, you have to register an account, this tutorial will be your guide to create one.

To create your account, follow these steps

  1. Navigate to Accept's home page

2. After that, you will enter your mobile number on which you will be receiving OTP for first-time verification.

3. As soon as you enter the OTP that you have received on your mobile number, you will get the below screen where you will be adding your name, and email details including your desired Password which you will be using for further logging.

4. Please note that after this screen you will get a login screen where you will be entering your registered mobile number without country code and your password which you have set in the previous screen.

5. As soon as you will log in, you will get the below screen to enter your business details.

After filling in this information, you will get a " Registration successful" message on the screen and you will be routed to your Paymob Dashboard as below :

Great-Now you have successfully made your Merchant portal dashboard 

Now you can go to the Sign-In page and start accepting online payments from your customers, Go check our use case guide and choose your perfect payment scenario!

👍Note!

The status of the created account will be marked as a "Test" account, this will allow you to test all of Accept's services. When you finish your testing phase, please contact your Account Manager or Contact Support team through email  support@paymob.com or you can also raise a ticket through a support widget in your Merchant portal Dashboard to change its status to be "Live".

Was this section helpful?

What made this section unhelpful for you?

Accept Dashboard

A detailed guide to your Accept dashboard

In order to deal with any of Accept's services, you have to create an Accept account.

In your Accept portal, you can find:

  • Profile.
  • Payment Integrations.
  • Orders.
  • Transactions.
  • Checkout Customization.

API Checkout Experience

Welcome to the API Checkout Experience documentation! In this guide, you will learn how to integrate and set up our API to provide a seamless and unified checkout experience. This includes everything you need to get started with setting up the API, generating your keys, and configuring both the Unified Intention API Checkout and Pixel Native Payment experiences.

We'll walk you through the basics of the API, including an overview of how it works, step-by-step instructions on how to get your environment set up, and how to use the various endpoints to facilitate secure and efficient transactions.

E-Commerce Plugins

Mobile SDKs

Subscriptions

Overview

Paymob provides a comprehensive subscription module designed to help merchants efficiently manage their subscriptions on a variety of billing cycles, including weekly, bi-weekly, monthly, quarterly, semi-annual, and annual plans. This module is tailored to meet the specific needs of each merchant, enabling them to create, manage, and control their subscriptions independently through our APIs.

For any guidance or assistance, please reach out to your account manager. Alternatively, you can contact our support team via email at support@paymob.com. When reaching out, please include details regarding your subscription, such as your Subscription ID and Transaction ID, to help us assist you more efficiently.

Integration Requirements

To successfully set up your subscription plan, you will need two integration IDs:

  • Online 3DS Integration ID: This ID will be used for creating subscriptions.
  • Moto Integration ID: Utilize this ID when creating the subscription plan itself.

Ensure you have both integration IDs ready to streamline the setup process.

If you wish to verify the card user details (provide a free trial for X days period) instead of deducting the amount while creating the subscription then you can ask our support team at support@paymob.com to create a 3DS verification integration ID. Noting this amount will be an auto reversal and you need to set the  "use_transaction_amount": false  to avoid any override with the Subscription plan amount

For further assistance or detailed API guidance, please refer to the subsequent sections of this documentation.

Payment Types

Paymob provides a comprehensive range of payment options to suit various business needs, enhancing the flexibility and security of online transactions. The following are the four primary payment types supported by Paymob:

1. 3D Secure (3DS)

3D Secure (3DS) is a security protocol designed to reduce the risk of fraudulent online transactions by adding an additional layer of authentication. When a cardholder makes a purchase online, 3DS prompts the customer to authenticate their identity with the card issuer during the final stage of the checkout process. This step typically involves entering a one-time password (OTP) or biometric verification, depending on the card issuer’s requirements.

2. Auth and Capture

The Auth and Capture payment method is a two-step process where the transaction is initially authorized, but the funds are not immediately captured. First, the payment gateway authorizes the transaction by confirming that the customer has sufficient funds available, but the actual transaction amount will be captured later. If the transaction is not captured within 07 days, it will be automatically voided.

3. Card Verification

Card Verification Function is a functionality provided by the Network to authenticate a card transaction without actually deducting the transaction amount from the customer’s card.

4. Pay with Saved Card Token

The Pay with Saved Card Token method allows customers to store their card details securely for future transactions. Once a customer has completed a transaction, the payment system stores a unique token that represents their payment method. In subsequent transactions, customers can opt to pay using this saved token without having to re-enter their card details, simplifying the checkout process.

Was this section helpful?

What made this section unhelpful for you?

3D Secure (3DS)

3D Secure (3DS), also known as payer authentication, is a security system that helps protect online credit and debit card transactions. It adds an extra layer of security to reduce the risk of fraud, keeping both merchants and customers safe from unauthorized payments. Merchants can set up 3D Secure by using a 3DS integration ID in the payment request, making the process smoother while ensuring strong protection. The Intention API lets you create a payment request by providing all the necessary information. Make sure to include all the required details to start the payment request correctly. For more information about the Unified API Intention Experience, please check this section.

Important points:

  1. You can create your integration ID from the Payments Integration tab in the Merchant Portal Dashboard. Please note that any integration ID you create from your dashboard will be set to "Test" status by default. For any configuration changes to a Test Integration ID or if you wish to switch it to "LIVE," please contact your Account Manager or reach out to the Support team via email at support@paymob.com. Alternatively, you can raise a ticket through the support widget in your Merchant Portal Dashboard.
  2. This feature works in both live and test environments.
Was this section helpful?

What made this section unhelpful for you?

Auth and Capture

An Auth/Capture transaction has two separate steps:

Authorization Transaction: In this step, you hold (or "authorize") a certain amount on your customer's card. Make sure to include the Auth and Capture integration ID in the intention request to authorize the payment. The Intention API helps you create a payment request by providing all the necessary information. Make sure to include all steps and details correctly to successfully start the payment request. For more information on the Unified API Intention Experience, please check this section.

Important points:

  1. You can create your integration ID from the Payments Integration tab in the Merchant Portal Dashboard. Please note that any integration ID you create from your dashboard will be set to "Test" status by default. For any configuration changes to a Test Integration ID or if you wish to switch it to "LIVE," please contact your Account Manager or reach out to the Support team via email at support@paymob.com. Alternatively, you can raise a ticket through the support widget in your Merchant Portal Dashboard.
  2. This feature works in both live and test environments.

Capture Transaction: In this step, you capture the authorized amount, or a smaller amount if needed. If the transaction is not captured within 14 days, it will be automatically canceled.

Was this section helpful?

What made this section unhelpful for you?

Card Verification

Card Verification Function is a functionality that the Network provides to authenticate a card transaction without deducting the transaction amount from the customer’s card. This will mainly be used by merchants who want to tokenize customer card information. The transaction flow will be exactly the same as it is for a normal 3DS Card Transaction. A transaction using the card verification function cannot be refunded or voided. However, once the transaction is completed, Paymob will automatically mark it to be voided in the system."

Important points:

  1. The merchant should request a card verification Integration ID from their account manager. This integration ID can be used for any API payment.
  2. This feature works in both live and test environments.
  3. If the customer doesn’t want to charge any amount on their card, they should set the transaction amount to "false" when creating the subscription plan."
Was this section helpful?

What made this section unhelpful for you?

Pay With Saved Card Token

Paymob facilitates seamless payments by allowing users to transact with saved card tokens, which enable transactions using previously stored cards. There are two primary methods for utilizing these saved tokens for payments:

Pay with Saved Card Token (Normal Moto Integration Flow)

Pay with Saved Card Token (3DS Integration Flow ( Unified Checkout)

Was this section helpful?

What made this section unhelpful for you?

Pay With Saved Card Token-Normal Moto Integration Flow

To initiate Moto Transactions, you first need to obtain the “save card token” in the Generating a Saved card token section as well as the “payment Key” in the Generating a Payment Key section which you will use in the below request to perform recurring payments.

Step 1: Please send a POST request to the URL below after adding the saved card token in "identifier" and the Payment Key in "payment_token" as in the below screenshot.

URL: https://accept.paymob.com/api/acceptance/payments/pay

Method: POST

Source: Merchant's server

Recipient: Accept's server

Request:

Response:

Was this section helpful?

What made this section unhelpful for you?

POST

/api/acceptance/payments/pay

Select
1 2 3 4 5 6 7 8 curl --location 'https://accept.paymob.com/api/acceptance/payments/pay' \ --data '{ "source": { "identifier": "d20d94xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxf1a9da9", "subtype": "TOKEN" }, "payment_token": "ZXlKMGVYQWlULjRi2T2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx..." }'

Response

{
  "id": 576820,
  "pending": "false",
  "amount_cents": 2000,
  "success": "true",
  "is_auth": "false",
  "is_capture": "false",
  "is_standalone_payment": "true",
  "is_voided": "false",
  "is_refunded": "false",
  "is_3d_secure": "false",
  "integration_id": 50428,
  "profile_id": 106,
  "has_parent_transaction": "false",
  "order": 693561,
  "created_at": "2024-10-03T10:29:28.187774+04:00",
  "currency": "EGP",
  "terminal_id": "",
  "merchant_commission": null,
  "installment": "",
  "discount_details": [],
  "is_void": "false",
  "is_refund": "false",
  "error_occured": "false",
  "refunded_amount_cents": null,
  "captured_amount": null,
  "merchant_staff_tag": "",
  "updated_at": "2024-10-03T10:29:30.272868+04:00",
  "is_settled": "false",
  "bill_balanced": "false",
  "is_bill": "false",
  "owner": 211,
  "parent_transaction": "",
  "merchant_order_id": "phexxxxxxxxxxxx11",
  "data.message": "Approved",
  "source_data.type": "card",
  "source_data.pan": "2346",
  "source_data.sub_type": "MasterCard",
  "acq_response_code": "00",
  "txn_response_code": "APPROVED",
  "hmac": "eabc46cb9eb8c69615342a341a6146e39dcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7c0ed267073",
  "merchant_txn_ref": "576820",
  "use_redirection": true,
  "redirection_url": "https://www.google.com/?id=576820&pending=false&amount_cents=2000&success=true&is_auth=false&is_capture=false&is_standalone_payment=true&is_voided=false&is_refunded=false&is_3d_secure=false&integration_id=50428&profile_id=106&has_parent_transaction=false&order=693561&created_at=2024-10-03T10%3A29%3A28.187774%2B04%3A00¤cy=AED&merchant_commission=0&discount_details=%5B%5D&is_void=false&is_refund=false&error_occured=false&refunded_amount_cents=0&captured_amount=0&updated_at=2024-10-03T10%3A29%3A30.272868%2B04%3A00&is_settled=false&bill_balanced=false&is_bill=false&owner=211&merchant_order_id=phe4sjw11q-11212-211&data.message=Approved&source_data.type=card&source_data.pan=2346&source_data.sub_type=MasterCard&acq_response_code=00&txn_response_code=APPROVED&hmac=eabc46cb9eb8c69615342a341a6146e39dc5f784525f5218e4d80952da2eff0ed6ddccd3975e4edd8478186809e60cfbed7093e426fd70d8d69107c0ed267073",
  "merchant_response": "ok",
  "bypass_step_six": true
}
Was this section helpful?

What made this section unhelpful for you?

Pay With Saved Card Token- 3DS Integration Flow through Unified Checkout.

You can make a payment using a saved card token by providing the 3DS integration ID and the saved card token in the intention request.

Step 1: You can add a "secret key" in the authorization box in the header section. For the secret key please refer to this section.

You've received your Saved card token in the Generating a Saved card token section.

Step 2: Please send a POST request to the URL below after adding the saved card token in the "card_tokens" parameter and use the 3DS Integration ID in the intention request as shown in the below screenshot.

URL: https://accept.paymob.com/v1/intention/

Method: POST

Source: Merchant's server

Recipient: Accept's server

Request:

Response:

Step 3: Once you are done with the Intention you need to call below url in the browser's window to access the checkout page as shown below. https://accept.paymob.com/unifiedcheckout/?publicKey=<add your public key here>&clientSecret=<add your client secret key here>

Obtaining Your Keys

To access your Public Key and Client Secret Key, please follow these instructions:

  1. Public Key: You can retrieve your Public Key from your Dashboard. For detailed steps, refer to the section on accessing your Public Key.
  2. Client Secret Key: Your Client Secret Key will be included in the response from the Intention API, as demonstrated in the example below.

Step 4 After calling the above url in the browser's window, the user navigates to the checkout page, and the saved card will be displayed as shown below. The user will simply need to enter the CVV number associated with the saved card to complete the transaction,

Step 5: The approval message will be displayed on the screen if the transaction is successful.

Was this section helpful?

What made this section unhelpful for you?

POST

/v1/intention

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 curl --location 'https://accept.paymob.com/v1/intention' \ --data-raw '{ "amount": 2000, "currency": "EGP", "payment_methods": [ 158 ], "card_tokens": [ "3860b033229de1ae77xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ], "items": [ { "name": "Item name", "amount": 2000, "description": "Item description", "quantity": 1 } ], "billing_data": { "apartment": "dumy", "first_name": "ala", "last_name": "zain", "street": "dumy", "building": "dumy", "phone_number": "xxxxxxxxx", "city": "dumy", "country": "dumy", "email": "ali@gmail.com", "floor": "dumy", "state": "dumy" }, "extras": { "ee": 22 }, "special_reference": "phe4sxxxxxxxxxxxxxxxxxxxxxxx-211", "notification_url": "https://webhook.site/dabe4968-5b60-4ac4-aea1-76308e115d2e", "redirection_url": "https://www.google.com/" }'

Response

{
  "payment_keys": [
    {
      "integration": 158,
      "key": "ZXlKaGJHY2lPaUpxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxXJmQ3hucnlXYWc=",
      "gateway_type": "MIGS",
      "iframe_id": null
    }
  ],
  "id": "pi_test_fc4da6b7baxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx55c56",
  "intention_detail": {
    "amount": 2000,
    "items": [
      {
        "name": "Item name",
        "amount": 2000,
        "description": "Item description",
        "quantity": 1,
        "image": null
      }
    ],
    "currency": "EGP",
    "billing_data": {
      "apartment": "dumy",
      "floor": "dumy",
      "first_name": "ala",
      "last_name": "zain",
      "street": "dumy",
      "building": "dumy",
      "phone_number": "+9234xxxxxxxxx",
      "shipping_method": "",
      "city": "dumy",
      "country": "dumy",
      "state": "dumy",
      "email": "ali@gmail.com",
      "postal_code": ""
    }
  },
  "client_secret": "egp_csk_test_b973xxxxxxxxxxxxxx",
  "payment_methods": [
    {
      "integration_id": 158,
      "alias": null,
      "name": null,
      "method_type": "online",
      "currency": "EGP",
      "live": false,
      "use_cvc_with_moto": false
    }
  ],
  "special_reference": "phe4sjxxxxxxxxxxxxxxx43-211",
  "extras": {
    "creation_extras": {
      "ee": 22
    },
    "confirmation_extras": null
  },
  "confirmed": false,
  "status": "intended",
  "created": "2024-10-03T18:20:26.018603+04:00",
  "card_detail": null,
  "card_tokens": [
    {
      "masked_pan": "xxxx-xxxx-xxxx-2346",
      "card_subtype": "MasterCard",
      "token": "3860b033229de1axxxxxxxxxxxxxxxxxx76121880",
      "card_expired": false
    }
  ],
  "object": "paymentintention"
}
Was this section helpful?

What made this section unhelpful for you?

Generating a Saved Card Token

To generate a customer's card token, you must first complete a successful 3DS transaction. This can be accomplished using the Intention API. Upon successful completion of the transaction, the card token will be received in the webhook response, as illustrated in the image below.

Webhook Response: Token

You will receive the token response only if the user selects the "Save Card" option on the checkout page as shown in the below image.

Was this section helpful?

What made this section unhelpful for you?

Generating a Payment Key

To generate a payment key, use the Intention API as described in the Intention documentation. When making your request, include the Moto Integration ID in the "Payment Methods" section of the request parameters.

Upon successful execution, you will receive a payment "Key" in the response under "Payment_Keys." This key will be required for the subsequent API call, "Pay with Saved Card Token (Normal Moto Integration Flow).

Request:

In the request body, you need to include the Moto Integration ID in the payment_methods parameter, as highlighted in the image below.

Response:

In the response body, you will receive the payment key. This key must be used in the "Pay with Saved Card Token" API.

Was this section helpful?

What made this section unhelpful for you?

Payment Links

Payment Actions

This section contains the following topics:

  1. Refund Transaction through the Dashboard.
  2. Refund Transaction through API.
  3. Void Transaction through the Dashboard.
  4. Void Transaction through API.
  5. Auth/Capture Transaction through the Dashboard.
  6. Auth/Capture Transaction through API.

Payment Methods

Paymob provides a wide range of payment methods in Egypt, enabling businesses to offer seamless and secure transactions for their customers. Whether through cards, digital wallets, or installment plans, Paymob ensures a smooth payment experience tailored to diverse customer needs. Below is a list of supported payment methods:

  • Card Payments
  • Digital Wallets
  • Apple Pay
  • ValU
  • Bank Installments
  • Souhoola V3
  • Aman V3
  • Forsa
  • Premium
  • Contact
  • HALAN
  • SYMPL
  • Kiosk
  • InstaPay (Coming Soon)

This extensive payment network allows businesses to expand their customer reach and simplify transactions through flexible and accessible solutions.

Test Credentials

Here are the test credentials for the online card payment method:

Mastercard:

Card

Mastercard

Card number

5123456789012346

Cardholder Name

Test Account

Expiry Month

12

Expiry Year

25

CVV

123

Wallet Test Credentials :

Here are the test credentials for Wallets;

Wallet Number

01010101010

MPin Code

123456

OTP

123456

MasterCard For Simulation:

Card

Mastercard

Card number

5123450000000008

Cardholder Name

TEST CARD

Expiry Month

01

Expiry Year

39

CVV

123

VISA Card for Simulation:

Card

VISA

Card number

4111111111111111

Cardholder Name

Test Account

Expiry Month

12

Expiry Year

25

CVV

123

You will simulate both successful and all failed cases outlined below using the VISA card credentials provided above.

Successful Response:

Failed Response:

Was this section helpful?

What made this section unhelpful for you?

Transaction Inquiry API

Retrieve A Transaction allows you to obtain the details and status of a transaction-whether it is successful or failed, using one of the following methods:

  1. Retrieve Transaction with Order ID Use the Order ID to access transaction details.
  2. Retrieve Transaction with Transaction ID Use the Transaction ID to obtain the relevant transaction information.
  3. Retrieve Transaction with Merchant Order ID(Special Reference Number) Access transaction details using the Merchant Order ID (Special Reference Number).

Manage Callback

Welcome to the Manage Callback documentation! In this section, we'll guide you through the different types of transaction callbacks that are essential for handling payment processing and ensuring a seamless integration with your system. Specifically, we'll cover transaction processed callbacks, transaction response callbacks, and how to calculate HMAC for processed callbacks, redirection callbacks, and saved card token objects.

You will learn how to configure and manage these callbacks, understand their role in transaction flow, and ensure that your system securely processes and responds to different events during payment transactions. Whether you're dealing with successful payments, handling failures, or managing tokenized card data, this guide will provide you with the necessary tools and knowledge to handle callbacks efficiently and securely.

Let's dive into understanding each callback type and how to calculate and implement HMAC to ensure the integrity and security of your transactions.

Error Codes

You can find the Risk error codes and other Acquirer response code descriptions in this section to know more about your declines, and detailed reasons.

Bills Portal API

Payouts

Table Of Contents

Frequently Asked Questions (FAQs)

The Frequently Asked Questions (FAQ) section is a comprehensive resource designed to address common inquiries about our services and features. Here, you will find detailed answers to questions regarding payment methods, transaction processes, technical requirements, and security measures. Whether you're a new user seeking guidance or an experienced merchant looking for specific information, this section aims to provide clarity and support. For any additional questions not covered here, please feel free to reach out to our customer support team at support@paymob.com.