Sign up for registering a new account

A guide to registering a new accept account.

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!

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.

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.

Introduction to RESTful APIs and HTTP Methods in Paymob

RESTful Functionality: A RESTful web application exposes its resources along with information about them. It empowers clients to perform actions on these resources, such as creating new ones (e.g., a user profile) or modifying existing ones (e.g., updating a transaction).

HTTP Methods: HTTP methods, or verbs, denote actions performed on resources. Paymob's APIs support various HTTP methods:

• GET: Retrieve a representation of a specific resource. Example: Fetching all received payments.
• POST: Submit data to create a new resource or trigger a state change. Example: Generating a payment link.
• PUT: Replace all representations of a target resource with the provided payload. Example: Modifying customer details.
• DELETE: Remove a specified resource. Example: Deleting an invoice.
• PATCH: Apply partial modifications to a resource. Example: Updating an order with specific changes.

Parameters: Parameters allow customization of API requests and responses. Paymob's APIs support four types of parameters:

• Path Parameters: Integral parts of the endpoint URL, identifying specific resources.
• Query Parameters: Appended to the endpoint URL to filter or paginate results.
• Request Parameters: Included in the request body, transmitting data to the API server.
• Response Parameters: Represent data returned by the server in response to a request.

HTTPS Status Codes: HTTP status codes communicate the outcome of client requests. Paymob employs HTTPS status codes categorized into three classes:

• Success (200): Successful response
• Client Error (400): Error on the transactions.
• Server Error (500): Internal server error.

Introduction

Paymob Pixel's JS SDK empowers merchants to create and customize their checkout experience using pre-built UI components that integrate seamlessly into their website. This allows customers to complete payments directly on the merchant's store without being redirected to Paymob's Hosted Checkout.

Features:

• Native Payment Experience for Websites and Stores.
• Fully Customizable UI Components.
• Enhanced Conversion Rates.
• Secure Payment Processing.
• Support for Quick Payment Options such as Apple Pay.

Pre-Requisites

Mandatory:

• Ensure you have a Paymob account.
• Integrate the Intention API as described in the documentation for the Create Intention Payment API.

Optional:

• Integrate the Update Intention Payment API.

Version

Please get the latest Pixel package from this link.

Supported Payment Methods

Pixel supports only Card Payments and Apple Pay in Egypt.

How does Pixel Work?

1. Use the Create Intention Payment API to create a payment order.
2. Pass the client_secret from the Create Intention API response into the clientSecret parameter of the Pixel JS and load the Pixel JS. This will load the Pixel Checkout on the website.
3. If the order amount or billing details change, call the Update Intention Payment API with the updated order amount, billing data, or both.
4. Trigger the updateIntentionData event to ensure the updated order details are reflected in the checkout, without needing to reload the Pixel JS.

To Begin Using the Checkout Pixel JS SDK

1. Include the following script tag in your HTML file:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/styles.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.css">
<script src="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.js" type="module"></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/styles.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.css">
<script src="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.js" type="module"></script> 

Definition of Parameters

1. publicKey: It can be accessed from the Merchant’s Dashboard → Settings → Account Info. Click on view to access it.

 
onload = (event) => {
  new Pixel({
    publicKey: 'egy_pk_test_XXXXXXXXXXXXXXXXXXXX'
  });
};

2. clientSecret: Once you fire Intention API, you will receive client_secret in the API Response, which will be used in the Pixel SDK. Client Secret is unique for each order and expires in an hour.

 
onload = (event) => {
  new Pixel({
    clientSecret: 'egy_csk_test_XXXXXXXXXXXXXXXXXXXX'
  });
};

3. paymentMethods: Pass card for Card Payments, google-pay for Google Pay, and apple-pay for Apple Pay.

 
onload = (event) => {
  new Pixel({
    paymentMethods: ['card', 'google-pay', 'apple-pay'],
  });
};

4. elementId: ID of the HTML element where the checkout pixel will be embedded.

 
onload = (event) => {
  new Pixel({
    elementId: 'paymob-elements',
  });
};

5. disablePay: If you don’t want to use Paymob’s Pay Button for Card Payment:

Step 1: pass disablepay as TRUE.

Step 2: Define the button in the script. Once the user clicks on the Button on your website, we will trigger the Pay functionality from our side. The Button ID could be anything but the event should be payFromOutside.

 
const event = new Event('payFromOutside');

Step 3: Add the Logic for Event Listener in the script shown below.

If you pass disablePay as false or if the parameter is not passed in the script, the "Pay" Button would be shown for Card Payment. The user will click on Pay Button for Payment Processing.

 
// Step 1: 
onload = (event) => {
  new Pixel({
    disablePay: false/true
  });
};

// Step 2: 
<button id="payFromOutsideButton">Pay From Outside Button</button>

// Step 3: 
const button = document.getElementById('payFromOutsideButton');
button?.addEventListener('click', function () {
  // Calling pay request
  const event = new Event('payFromOutside');
  window.dispatchEvent(event);
});

6. updateIntentionData: When a merchant triggers the Create Intention Payment API with an initial order amount and loads the Pixel SDK on the checkout page, the order amount or billing data may change due to reasons such as shipping charges, discount promo codes, or user updates to billing information. Whenever you update the intention via API, you must also update the intention data within the SDK. Merchants can address this scenario by following these steps:

1. Call the Update Intention Payment API with the revised order amount, updated billing data, or both.
2. Trigger the function below as shown below. There's no need to reload the Pixel SDK on Checkout, as the order data will be automatically updated, given the function returns a valid response.

 
await Pixel.updateIntentionData();

You can also store the response of the function.

const response = await Pixel.updateIntentionData();

7. showSaveCard: If this parameter is set to true, users will have the option to save their card details for future payment processing. Upon the user's consent to save the card, a token will be included in the Webhook Response sent to the Merchant. When the same token is provided in the Order API, the saved card details will be displayed to the user, allowing them to use the saved card for payment processing.

If this parameter is set to false or if this parameter is not used in the script, users will not be shown the option to save card details with Paymob.

 
onload = (event) => {
  new Pixel({
    showSaveCard: false/true
  });
};

8. forceSaveCard: If this parameter is set to true, the user's card details will be saved automatically without requiring their consent.

If this parameter is set to false or if this parameter is not used in the script, the card details will not be saved automatically.

 
onload = (event) => {
  new Pixel({
    forceSaveCard: false/true
  });
};

9. beforePaymentComplete: Merchants can implement their own custom logic or functions before the payment is processed by Paymob.

1. For card payments, whether the user enters their card details and clicks the "Pay" button or the merchant triggers the payment using their own button, the merchant can define a function to instruct Paymob to either proceed with processing the payment or halt it.
2. For Apple Pay, when the user clicks on the Apple Pay Button, the logic of beforePaymentComplete will be triggered.

The above functionality will be applicable for Card and Apple Pay.

If the Function returns true or it does not return any value, Payment will be processed by Paymob after 5 seconds in this case.

 
onload = (event) => 
{
  new Pixel({
              beforePaymentComplete: async (paymentMethod) => 
               {
                        console.log(paymentMethod);
                        console.log('Before payment start');
                        console.log('We are waiting for 5 seconds');
                        await new Promise(res => setTimeout(() => res(''),5000))
                        console.log('Before payment end');
                        return true
              },    
           });
};

If the function returns false, the payment will NOT be processed by Paymob after waiting for 5 seconds.

 
onload = (event) => 
{
  new Pixel({
              beforePaymentComplete: async (paymentMethod) => 
               {
                        console.log(paymentMethod);
                        console.log('Before payment start');
                        console.log('We are waiting for 5 seconds');
                        await new Promise(res => setTimeout(() => res(''),5000))
                        console.log('Before payment end');
                        return false
              },    
           });
};

10. afterPaymentComplete: This functionality will only be applicable for Apple Pay. After payment is processed by Paymob, Paymob will send the API response highlighting the status of the transaction, and the merchant can write custom logic to handle the post-payment scenario.

 
onload = (event) => {
  new Pixel({
    afterPaymentComplete: async (response) => {
      console.log('After Bannas payment');
      console.log(response);
    }
  });
};

11. onPaymentCancel: This function applies exclusively to Apple Pay. Merchants can implement their own custom logic to handle scenarios where a user cancels the Apple Pay payment by closing the Apple Pay SDK.

 
onload = (event) => {
  new Pixel({
    onPaymentCancel: () => {
      console.log('Payment has been canceled');
    }
  });
};

12. cardValidationChanged: This function will exclusively handle Card Payments. Initially, the value of isValid will be set to false. The function will be triggered whenever there is a change in the card validation state.

When the user enters valid card information that meets the Paymob Card Validation Rules, the isValid value will update to true. However, if the user modifies the card information and it no longer complies with the validation rules, the isValid value will revert to false.

 
onload = (event) => {
  new Pixel({
    cardValidationChanged: (isValid) => {
      console.log("Is valid?", isValid);
    },
  });
};

13. customStyle: To customize the appearance of the checkout pixel, merchants can provide a customStyle object as part of the Checkout Pixel configuration. If the customStyle object is not used, default settings will be applicable.

 
onload = (event) => {
  new Pixel({
    customStyle: {
      Font_Family: 'Gotham',
      Font_Size_Label: '16',
      Font_Size_Input_Fields: '16',
      Font_Size_Payment_Button: '14',
      Font_Weight_Label: 400,
      Font_Weight_Input_Fields: 200,
      Font_Weight_Payment_Button: 600,
      Color_Container: '#FFF',
      Color_Border_Input_Fields: '#D0D5DD',
      Color_Border_Payment_Button: '#A1B8FF',
      Radius_Border: '8',
      Color_Disabled: '#A1B8FF',
      Color_Error: '#CC1142',
      Color_Primary: '#144DFF',
      Color_Input_Fields: '#FFF',
      Text_Color_For_Label: '#000',
      Text_Color_For_Payment_Button: '#FFF',
      Text_Color_For_Input_Fields: '#000',
      Color_For_Text_Placeholder: '#667085',
      Width_of_Container: '100%',
      Vertical_Padding: '40',
      Vertical_Spacing_between_components: '18',
      Container_Padding: '0'
    }
  });
};

Sample Screenshot for Pixel

Sample Script

 

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Pixel</title>
<base href="/">
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/styles.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.css">
</head>
<style>
    .content {
      display: flex;
      flex-direction: column;
      gap: 1rem;
      justify-content: center;
      align-items: center;
      margin-top: 2rem;
    }
    #paymob-elements {
      width: 30%;
    }
    #payFromOutsideButton {
      padding: 0.5rem;
      background-color: blue;
      color: white;
      border-radius: 0.2rem;
    }
</style>
</head>
<body>
<position>
<div class="header" style="padding: 1rem; background-color: rgb(233, 255, 207);">
      Company Paymob
</div>
<div class="wrapper">
<div class="content">
<div id="paymob-elements"></div>
 <button id="payFromOutsideButton">Pay From Outside Button</button>
</div>
</div>
<div class="footer">
</div>
<script src="https://cdn.jsdelivr.net/npm/paymob-pixel@latest/main.js" type="module"></script>
<script src="https://unpkg.com/paymob-pixel/main.js" type="module"></script>
<script>
    // Merchant Pay button logic
      const button = document.getElementById('payFromOutsideButton');
      button?.addEventListener
	  ('click', function () 
	  {
        // Calling pay request
        const event = new Event('payFromOutside');
        window.dispatchEvent(event);
      });
        onload = (event) => {
          new Pixel({
            publicKey: 'egy_pk_live_XXXX',
            clientSecret: 'egy_csk_live_XXXX',
            paymentMethods: [ 'card','google-pay','apple-pay'],
            elementId: 'paymob-elements',
            disablePay: false,
            showSaveCard :true,
			forceSaveCard : true,
            beforePaymentComplete: async (paymentMethod) => 
			{
			            console.log(paymentMethod);
                        console.log('Before payment start');
                        console.log('We are waiting for 5 seconds');
                        await new Promise(res => setTimeout(() => res(''),5000))
                        console.log('Before payment end');
                        return true
            },
            afterPaymentComplete: async (response) =>
              {
               console.log('After Bannas payment');
               console.log(response)
              },
			 onPaymentCancel: () => 
			  {
                console.log('Payment has been canceled');
              },
			  cardValidationChanged: (isValid) => {
			  console.log("Is valid ? ", isValid)
              },              
               customStyle: {
                 Font_Family: 'Gotham',
                 Font_Size_Label: '16',
                 Font_Size_Input_Fields: '16',
                 Font_Size_Payment_Button: '14',
                 Font_Weight_Label: 400,
                 Font_Weight_Input_Fields: 200,
                 Font_Weight_Payment_Button: 600,
                 Color_Container: '#FFF',
                 Color_Border_Input_Fields: '#D0D5DD',
                 Color_Border_Payment_Button: '#A1B8FF',
                 Radius_Border: '8',
                 Color_Disabled: '#A1B8FF',
                 Color_Error: '#CC1142',
                 Color_Primary: '#144DFF',
                 Color_Input_Fields: '#FFF',
                 Text_Color_For_Label: '#000',
                 Text_Color_For_Payment_Button: '#FFF',
                 Text_Color_For_Input_Fields: '#000',
                 Color_For_Text_Placeholder: '#667085',
                 Width_of_Container: '100%',
                 Vertical_Padding: '40',
                 Vertical_Spacing_between_components: '18',
                 Container_Padding: '0'
            }, 
          });
        };
</script>
<script src="https://pay.google.com/gp/p/js/pay.js"></script>
</body>
</html>

The Split Payment feature typically refers to functionality in payment systems that allows merchants to split the payment cost between the merchant and their sub-accounts.

Implementing a split payment feature involves handling complex transactions and ensuring security and accuracy in the distribution of funds. It requires robust backend systems and interfaces for users to specify how they want to split the payment.

How it Works

• The customer pays a 100 EGP charge.
• Paymob collects a 3 EGP fee (3% fees) and adds the remaining 97 EGP to the platform account’s pending balance.
• The gateway transfers 67 EGP to the restaurant’s main-connected account (including tips and fees) and 30 EGP (converted amount) to the sub-connected account.

How to Enable the Split Payment Feature

Follow these steps to start using the Split Payment feature:

1. Create an Account – Sign up for a Paymob account.
2. Set Up Payment Methods – Coordinate with your Account Manager to configure the required payment methods under the ‘Integration ID’ tab in your account.
3. Initiate a Payment Request – Use the Intention API to request payment for the total purchase amount, ensuring that all required fields are included.

Note: If the payment is made on behalf of a sub-entity, you must provide the sub-entity’s ID in the ‘Split MID’ field of the Intention API request. The request format is as follows:

 
“split_amounts”: [{"mid": "B" (Child MID), "amount_cents": "X"}] 

Requesting a Split Payment for a Single Sub-Entity

If your platform processes transactions for a single sub-entity at a time and you charge a commission for facilitating payments, include the following details in the Intention API request:

• MID of the main entity and the sub-entity.
• The amount allocated to the sub-entity.
• Platform commission deducted for the service.

Checking Transaction Breakdown/Transaction Inquiry:

To review transaction details, including applied commissions and fees:

1. Generate an AUTH token (valid for 60 minutes).
2. Use the Order ID, Transaction ID, or Merchant Order ID to perform a transaction inquiry.

This will provide a breakdown of the payment, showing how the amounts were split.

Refund/Void Transaction

If you need to refund or (void) a transaction, please refer to this link

Split Transaction on the Dashboard

Please log in to the Paymob dashboard and navigate to the Transactions tab to review split transactions. Select the relevant transaction and check the Converted Amount, VAT, and Fees under the main account.

Additionally, we provide visibility privileges for sub-merchants as follows:

• The Parent Transaction ID will be displayed under Other References.

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.

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.

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

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.

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.

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.

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

Mastercard:

Wallet Test Credentials :

Here are the test credentials for Wallets;

MasterCard For Simulation:

VISA Card for Simulation:

Successful Response:

Failed Response:

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

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.

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.

Table Of Contents

• Definitions and Acronyms
• Generate and Refresh Token API Endpoint
• Instant Cashin API Endpoint
• Cancel Aman Transaction API Endpoint
• Bulk Transaction Inquiry API Endpoint
• User Budget Inquiry API Endpoint
• CallBack Url
• Response Codes

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.