Who is this for - Anyone involved in setting up or managing payments with Paymob, including Merchants, Developers, and Product or technical teams

Outcome - know where to start, what you need, and which path makes the most sense for you

Paymob helps businesses accept online and in-person payments securely and at scale. Whether you’re just getting started with payment links, setting up an online store, or building a custom checkout from scratch, Paymob gives you a few different ways to integrate so you can choose what fits your business and technical setup.

This overview will help you understand what Paymob offers, which payment methods are available, and how to get up and running with the right integration.

Who Is This For?

In our documentation, to help you with navigation visual indicators is used to clarify the intended audience. When you see the People figure, the content applies to all users, including marketers and non-technical roles. When you see a code figure, the content is intended specifically for developers and may include technical or implementation-focused details.

Everyone

Essential information for anyone getting started with Paymob.

Developers

Detailed API documentation, integration guides, and technical specifications. Ideal for those implementing Paymob's payment solutions directly into applications or platforms.

Payment methods available

Paymob supports a range of payment methods commonly used, so your customers can pay the way they prefer:

Cards

Methods included: Visa, Mastercard, Amex, MADA, OmanNet

When to use: Standard online card payments with 3D Secure

Mobile Wallets

Methods included: Vodafone Cash, Orange Cash, e& money, We Pay, … in EgyptStcPay in KSA When to use: Basic banking services are provided by banks and their agents (e.g., mobile network operators).

Quick Payments

Methods included: Apple Pay, Google Pay

When to use: Faster checkout using cards saved on the user’s device or browse

BNPL

Methods included: (Tabby, Tamara) in the UAE and KSA(vaLU, Sympl, Souhoola, Halan, TRU, MOGO, …) in Egypt

When to use: Allow customers to split payments into installments

In-Person Payments

Methods included: Tap to Pay

When to use: Accept contactless payments on supported devices using the Paymob App

Ways to integrate with Paymob

There’s more than one way to integrate Paymob. The right option depends on how technical your setup is and how quickly you want to launch.

Sandbox (Test)

What it's for: Development and testing

When to use it: While building and QA

Production (Live)

What it's for: Real payments When to use it: After go-live approval

Not sure where to start?

Use this quick guide:

• No developers involved? → Start with Payment Links
• Running a Shopify or WooCommerce store? → Use an E-commerce Plugin
• Want a hosted payment page → Go with Hosted Checkout
• Want an embedded payment experience, not redirection → Go with Pixel
• Building a mobile app? → Use the Mobile SDKs

How payments work (at a high level)

No matter which integration you choose, the payment flow stays mostly the same:

You don’t need to handle sensitive card data yourself. Paymob takes care of that.

Test vs. live environments

Paymob gives you two environments to work with:

For all integrations

• A Paymob merchant account
• Access to the Paymob Dashboard
• Completed business verification

Both environments use the same base URL.

For API or SDK integrations

• API Secret Key and Public Key
• Integration ID(s) for your payment methods
• A webhook endpoint
• Success and failure redirect URLs

What you’ll need before you begin

Here’s a quick checklist to help you prepare.

For e-commerce plugins

• Admin access to your platform
• Integration ID(s)
• API key, secret key, and public key

Where to go next

Depending on what you want to do, here’s where to continue:

Need help?

If you get stuck, you’re not on your own:

• Documentation: Use the sidebar to explore all topics
• API reference: Full API details live under Developer Reference
• Postman collection: Try the APIs quickly using Postman
• Support: support@paymob.com
• Community: Join the Paymob Developer Community

Who is this for - Developers, product managers, and business owners who are preparing to launch Paymob in production

Outcome - Confirm that your integration is complete, tested, and ready for a smooth go-live

Overview

Within this section, we will help outline the end-to-end onboarding and go-live journey for integrating with our platform. It shows the required business, technical, and risk steps from account setup and documentation through testing, approvals, and credential issuance. Each stage must be completed in sequence to ensure a secure, compliant, and smooth transition to production.

Account Creation

The merchant account is created, granting access to the dashboard and test environment.

Paperwork Validation

Business and legal documents are reviewed to verify the merchant’s information and compliance.

Contract Finalization

Commercial terms are confirmed and the contract is signed by both parties.

Risk Approvals

The merchant is assessed by the risk team based on business model and transaction activity.

Integration Cycle

The merchant integrates the payment solution using APIs, SDKs, or plugins in the test environment.

Test & Validation

Test transactions are completed to ensure correct payment flow and system behavior.

Technical Approval

The integration is reviewed to confirm it meets technical and security requirements.

Live Credentials

Production credentials are issued to enable live transactions.

Going Live

The merchant starts accepting real customer payments.

Who is this for - Everyone

Outcome - Build the integration plan using this interaction wizard

Overview

The Onboarding Wizard is an interactive tool designed to help you build a clear and tailored integration plan based on your business needs and technical setup. Through a series of simple choices, such as your platform, preferred checkout experience, and required features, the wizard maps out the recommended Paymob integration path for your use case

Who is this for - Everyone

Outcome - Full and quick guide for the Paymob dashboard.

Overview

Our Dashboard allows you to monitor and analyze all payment activities from a single, centralized platform. You will have access to detailed payment histories, transaction insights, and comprehensive analytics to support leading informed business decisions.

Through the video below, we will guide you from the first steps of Signing Up until your full Account Creation.

Sign-up

Account Configuration

Manage and control your account’s core settings directly from the Settings tab, including:

Business Branding

• Update your business name, account type, sector, and industry
• Add and manage social media links
• Upload and manage your business logo

Contact Information

• Edit company name
• Manage phone numbers
• Update email addresses

Account Information

• Access integration credentials (Secret Key, Public Key, API Key, HMAC Secret)
• View account mode and status (Live / Test)

Notifications & Reports

• Enable or disable selected notification settings
• Control reporting and alert preferences

Checkout Customization

From the Merchant Dashboard, you can fully personalize the checkout experience to align with your brand and business needs.

Branding Customization

• Add your business logo and details
• Customize brand colors
• Select fonts that match your brand identity
• Choose button styles (Rounded or Rectangular)

Payment Experience

• Choose how payment methods are displayed (Tabs or List)
• Enable or disable specific payment methods
• Show or hide billing address fields
• Display purchased item details
• Enable the “Save Card” option
• Activate Split Payments and control the number of cards allowed
• Display Terms & Conditions link
• Enable or disable payment retries

Post-Payment Experience

• Show a custom thank-you message
• Customize the post-payment redirection flow

Payment Integrations

Manage all payment integrations from the Payment Integrations tab:

• Retrieve integration credentials based on selected mode (Live / Test)
• Add test integrations for payment methods:
  • Cards (MIGS)
  • Wallets
  • Kiosk payments
• Update callback URLs for each integration

Transactions Management

From the Transactions tab, you can monitor and manage all transaction activities:

• Filter transactions using:
  • Date range
  • Transaction ID
  • Order ID
  • Merchant Order ID
  • Transaction status
• Access full transaction details, including:
  • Transaction and order details
  • Shipping and billing information
  • Installment details (if applicable)
• Perform supported actions based on transaction status:
  • Refund
  • Void
  • Capture

Orders Management

Use the Orders tab to track and manage all orders efficiently:

• View orders by selected mode (Live / Test)
• Filter orders using:
  • Date range
  • Order ID
  • Merchant Order ID

Who is this for - Product managers and developers who need a high-level overview to plan the payment feature for their app or website

Outcome - Understand the overall payment flow and the available integration options

Overview

The figure below is a high-level view of the payments architecture, from user touchpoints to transaction execution, designed to guide decisions across wallets, cards, installments, and post-payment actions. This will help you map what you’re building, how you’re integrating, and which payment methods and flows you support.

Phase 1: Define Your Product & Integration Method

Start by defining what you are building and how you will connect to us.

Phase 2: Choose Your Payment Options

Select the payment methods and types that match your needs.

Phase 3: The Payment Actions you can take

Determine what payment actions you’ll perform.

1. What are the payment actions you'll perform?

Please check the Managing Payment Actions section to know more about the available payment actions and how to do each one through the Paymob dashboard or APIs.

If you are still confused regarding the path you'll follow to implement your needed payment experience, please send an email to support@paymob.com, and we'll be glad to help you get the best payment experience for your business.

Who is this for - Product managers and Merchants (non-technical) who want to start accepting online payments without any coding or development

Outcome - Start accepting online payments using Payment Links even without a website or development team.

Overview

Payment Links (fastest start)

Ideal when you don't have a website. Share via WhatsApp, social media, or any communication tool.

Good for: Event tickets, reservations, small businesses, electronic invoices

Option A: Payment Links (fastest start)

Payment links are ideal when you don’t have a website. You can share them via WhatsApp, social media, or any communication tool, and your customer pays on a hosted checkout page.

Common use cases

• Event tickets and reservations
• Small businesses selling without a website or POS
• Adding a payment link to an electronic invoice

Security and compliance

With hosted checkout, your customers complete payment on a payment page handled by the payment provider, which helps keep sensitive card data off your website.

Go live checklist

• Confirm your business profile is complete and approved (documents).
• Make sure the payment methods you want are enabled on your account.
• Run a full test: link creation → payment → confirmation → refund/void (if applicable).
• Train your team on what “paid” looks like in the dashboard (so orders don’t get missed).

Who is this for - Product managers and developers who need a high-level overview of how to integrate through APIs and our available checkout experiences

Outcome - Understand the overall API payment flow, the available checkout options, and how payment results are securely communicated back to your system

When should you use APIs?

Use Paymob APIs if you are:

• Building a custom website without a CMS or ready-made plugin
• Using a platform that allows calling third-party APIs but has no direct Paymob integration
• Building a mobile app and choosing to use a web-based checkout in a WebView instead of a native SDK

APIs give you flexibility while still relying on Paymob’s secure payment infrastructure.

Integration flow

Integrate Paymob payments into your existing e-commerce platform without writing code

When should you use Plugins? Use Paymob Plugins if you are: * Running an online store on a supported e-commerce platform * Looking for a no-code or low-code integration solution * Want to be up and running quickly without custom development

Plugins

Shopify

Wordpress

OpenCart

Magento

Odoo

WHMCS

Cs-Cart

PrestaShop

Joomia

ZenCart

OsCommerce

Laravel-Bagisto

Drupal

Who is this for - Product managers and developers who need a high-level overview of how to integrate through Mobile SDKs

Outcome - Understand the overall Mobile flow, the available checkout options, and how payment results are securely communicated back to your system

When should you use Mobile SDKs?

Use Paymob Mobile SDKs if you are building a native mobile application and want a checkout experience that feels fully integrated with your app.

Mobile SDKs are recommended when you want a native UI experience without using WebViews

Integration flow

Who is this for: Product managers, business owners, and stakeholders who need a high-level overview of Paymob’s supported payment methods and features

Outcome: Identify the supported payment methods and features, and decide which ones best fit your business needs

Paymob enables businesses to accept and manage digital payments through a wide range of payment methods and Core features.

Payment Methods

Paymob supports multiple payment methods to serve different customer preferences and markets, including:

• Card payments for online credit and debit card transactions
• Mobile wallets for fast, wallet-based payments
• Bank installments & BNPLs for spreading payments over time
• Kiosk payments for cash-based transactions

Each payment method has its own availability, flow, and requirements, which are covered in detail on its respective page.

Core Features

Paymob also provides features that help optimize payment operations and customer experience, such as:

• Pay With Saved cards for faster repeat payments through checkout
• Authorization and capture for flexible fund settlement
• Subscriptions Module for recurring payments
• Split Features for splitting the amount through multiple parties (Split Amount), or using up to 3 cards to fulfill the same payment (Split Payment)

Further details about each feature can be found in the dedicated feature pages.

Who is this for: Product managers, business owners, and stakeholders who need a high-level overview of Paymob’s supported payment methods and their use cases.

Outcome: Identify the supported payment methods and decide which ones best fit your business needs

Overview

Paymob supports a wide range of payment methods to help businesses accept payments across different customer preferences and markets. Each payment method serves a specific use case and may vary in terms of availability, customer experience, and supported features.

Supported Payment Method Types

Who is this for: Product managers, business owners, and stakeholders who want a high-level overview of Paymob’s core capabilities, without diving into technical implementation details

Outcome: Understand the key payment management and value-added features offered by Paymob, and identify which features are most relevant to your business mode

Paymob provides a set of core payment features that help merchants manage transactions, enhance customer experience, and optimize business operations. Each feature addresses specific business needs, from controlling funds to enabling flexible payments and generating insights.

Core Features Overview

Subscription Module

Automate recurring payments by charging customers periodically based on predefined subscription plans.

Pay With Saved Cards

Allows returning customers to pay quickly without re-entering card details, streamlining checkout and increasing repeat purchases.

Authorization & Capture (Auth/Cap)

A two-step payment flow that lets merchants reserve funds first and collect them later, offering control over settlement timing and flexibility in transaction amounts.

Split Features

Split a single payment across multiple parties (Split Amount) or allow customers to use up to three cards to complete the same payment (Split Payment).

Convenience Fee

Merchants can add additional charges to cover transaction processing costs or service fees, clearly presented to customers at checkout.

Transaction Inquiry & Reports

Provides insights into payments through detailed reports and Transaction Inquiry APIs, helping merchants track performance and reconcile accounts.

Who is this for - Product managers, business owners, and stakeholders who want a clear understanding of how to manage payments

Outcome - Understand the different types of payment management actions and when to use each one

Paymob gives you flexible control over how payments are handled throughout their lifecycle. This section focuses on the actions available to manage transactions once they exist, allowing you to cancel, reverse, or finalize payments based on your business needs.

Available Actions

The following actions help you manage different payment scenarios. Each action is covered in detail in its own dedicated page.

• Refund Used when you need to return funds to a customer.
• Void Used when you need to cancel a transaction, mostly available on the same business day.
• Capture Used when you need to collect funds from a previously authorized transaction.

Outcome: Understand what Paymob's Payment Intention is, and its APIs

Detention

Intention: The initial component of any payment that contains key details such as the payment amount, customer information, currency, and the available payment methods.

When will it be used?

It will be used each time you need to create a payment. It will be used with:

• Normal redirection integration on a website
• Embedded experience (Pixel) on a website
• Integrating with our SDKs
• Create subscription
• Auth/Cap payment model
• Pay with saved cards

Available actions

Create Intention

You can create an intention by using the Create Intention API, passing the amount that should be paid, customer info, and other information.

Update Intention

You can update an already existing intention by using the Update Intention API, passing the amount that should be paid, customer info, and other information.

Outcome: Understand the checkout experiences supported by Paymob, and know when to use Unified Checkout vs. Pixel.

Paymob offers two flexible checkout experiences to help you accept payments online. Each experience supports different merchant needs and integration preferences, while both rely on Paymob’s Intention API as the initial step.

Checkout Options

Unified Checkout

Unified Checkout is Paymob’s redirect-based payment experience. When a customer is ready to pay, you redirect them to Paymob’s hosted checkout page, where they enter their payment details and complete the transaction.

The flow generally involves creating a payment intention, then directing the customer’s browser to the hosted checkout using the generated client secret

Pixel

Pixel is Paymob’s JavaScript SDK that enables an embedded checkout experience directly on your site or application. Instead of redirecting the customer to a separate page, Pixel allows you to integrate payment elements inside your own UI.

Pixel is ideal for:

• Seamless, branded checkout experiences
• Embedded Card, Apple Pay, and Google Pay
• Businesses that want checkout UI inside their website without redirection

Pixel accepts configuration (such as payment methods and an HTML container ID) and uses the client secret from the previously created intention to render the payment UI in place.

How They Work

Both checkout experiences share the same initial requirement:

1. Create an intention Use the intention API to specify the payment amount, currency, and available methods. This returns a client secret that is unique to that payment attempt.
2. Render checkout
3. Unified Checkout: Redirect the customer to a hosted payment page using the client secret.
4. Pixel: Embed the payment UI inside your site using the SDK and client secret.

Choosing Between Unified Checkout and Pixel

Outcome: Integrate Paymob's pre-built UI (Pixel) in the merchant's checkout.

Pre-Requisites

• Integrate the Intention API as described in the documentation for the Create Payment Intention API.
• Include the following script and stylesheets 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> 

Usage

Create a new Pixel instance

 
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('Before payment start');
       return true
   },   
 
   afterPaymentComplete: async (response) =>
 {
       console.log('After Bannas payment');
   },
   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>

Properties

The full list of properties is as follows:

Events

We have one event that will be used if you want to trigger the payment from a custom Pay button, not Pixel's Pay button:

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

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

Functions

The full list of functions is as follows:

Full sample

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Pixel Experience</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">
  <style>
    .content {
      display: flex;
      flex-direction: column;
      gap: 1rem;
      justify-content: center;
      align-items: center;
      margin-top: 2rem;
    }
    #paymob-elements {
      width: 50%;
    }

    #payFromOutsideButton {
      padding: 0.5rem;
      background-color: blue;
      color: white;
      border-radius: 0.2rem;
    }
  </style>
</head>
<body>
  <div class="header" style="padding: 1rem; background-color: rgb(233, 255, 207);">
    Hello in my website
  </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>
    // Configuration

    const BASE_URL= {
      "EGY": "https://accept.paymob.com/",
      "OMN": "https://oman.paymob.com/",
      "KSA": "https://ksa.paymob.com/",
      "UAE": "https://uae.paymob.com/"
    }

    const CONFIG = {
      PUBLIC_KEY: 'egy_pk_test_yVnwxxxxxxxxxxxxxxxxxxxxxxx',
      SECRET_KEY: 'egy_sk_test_3f1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      CLIENT_SECRET: 'egy_csk_test_cad1xxxxxxxxxxxxxxxxxxxxx',
      INTENTION_API_URL: BASE_URL.EGY + 'v1/intention/'
    };
    console.log(CONFIG.INTENTION_API_URL)

    // Merchant button logic
    const button = document.getElementById('payFromOutsideButton');
    button?.addEventListener('click', async function() {


      console.log('Updating payment intention...');

      const myHeaders = new Headers();
      myHeaders.append("Authorization", `Token ${CONFIG.SECRET_KEY}`);
      myHeaders.append("Content-Type", "application/json");

      const raw = JSON.stringify({
        "accept_order_id": 446579232,
        "amount": 3000,
        "items": [
          {
            "name": "Item name",
            "amount": 2000,
            "description": "Item description",
            "quantity": 1
          },
          {
            "name": "Item name",
            "amount": 1000,
            "description": "Item description",
            "quantity": 1
          }
        ],
        "billing_data": {
          "apartment": "dumy",
          "first_name": "test",
          "last_name": "update",
          "street": "dumy",
          "building": "dumy",
          "phone_number": "01010101010",
          "city": "dumy",
          "country": "dumy",
          "email": "test@email.com",
          "floor": "dumy",
          "state": "dumy"
        },
        "extras": {
          "ee": 22
        },
        "notification_url": "https://webhook.site/e4081416-3343-4c06-878b-sds55dfd37",
        "redirection_url": "https://google.com/"
      });

      const requestOptions = {
        method: "PUT",
        headers: myHeaders,
        body: raw,
        redirect: "follow"
      };

      try {
        console.log(CONFIG.CLIENT_SECRET);
        console.log(CONFIG.INTENTION_API_URL+CONFIG.CLIENT_SECRET)
        const response = await fetch(`${CONFIG.INTENTION_API_URL}${CONFIG.CLIENT_SECRET}`, requestOptions);
        console.log(response);
      } catch (error) {
        console.error('Error updating intention:', error);
      }

      console.log('Updating Pixel');
      const update_pixel_response = await Pixel.updateIntentionData();
      console.log('Pixel Updated', update_pixel_response);


      // Calling pay request
      const event = new Event('payFromOutside');
      window.dispatchEvent(event);
    });

    onload = (event) => {
      button.style = "display: none;"
      let pixel_instance = new Pixel({
        publicKey: CONFIG.PUBLIC_KEY,
        clientSecret: CONFIG.CLIENT_SECRET,
        paymentMethods: ['card', 'google-pay', 'apple-pay'],
        elementId: 'paymob-elements',
        disablePay: true,
        showSaveCard: false,
        forceSaveCard: true,

        beforePaymentComplete: async () => {
          console.log('Before payment start');          
          console.log('Waiting for 5 seconds...');
          await new Promise(res => setTimeout(() => res(''), 5000));
          console.log('Before payment end');
        },

        afterPaymentComplete: async (response) => {
          console.log('After payment logic');
          console.log(response);
          await new Promise(res => setTimeout(() => res(''), 5000));
        },

        onPaymentCancel: () => {
          console.log('Payment has been canceled');
        },

        cardValidationChanged: (isValid) => {
          if (isValid === true) {
            button.style = "display: block;"
            console.log("valid");
          } else {
            button.style = "display: none;"
            console.log("not valid");
          }
        },

        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>
</body>
</html> 

Supported Mobile SDKs

IOS SDK

Android SDK

Flutter Bridge

React Native SDK

How does it work?

Mobile SDKs use the same backend flow as other Paymob checkout experiences. Before starting a payment in the mobile app, your system must create a payment intention and obtain a client secret, which will be used to initialize the SDK.

Outcome: Integrate Paymob's native iOS SDK

Installation

You can install the iOS SDK in one of two ways. Choose only one method.

Option 1: Cocoa installation

PaymobSDK is available through CocoaPods.

Step 1: Add Pod Dependency

Simply add the following line to your Podfile:

 
pod 'Paymob'

Step 2: Install Pods

Run pod install command in the terminal

Step 3: Open Workspace

Open your project using the.xcworkspace file

Step 4: Change the embedding option to "Embed & Sign"

In the general settings of your project, under libraries and frameworks, change the library from "Do not embed" to "Embed and Sign"

Manual Installation

Step 1: Download the SDK

Download the SDK from the provided link and extract it on your local machine.

Step 2: Add the SDK files to your project

Copy the extracted SDK files and place them inside your project’s folder structure.

Step 3: Add the SDK to Xcode

Open your project in Xcode, then drag and drop the PaymobSDK.xcframework into General → Frameworks, Libraries, and Embedded Content.

Step 4: Embed and sign the SDK

In Frameworks, Libraries, and Embedded Content, change the SDK option from Do Not Embed to Embed & Sign.

Usage

Step 1: Import the framework

 
import PaymobSDK

Step 2: Add the delegate to the class, and add the protocol stubs

 
class ViewController: UIViewController, PaymobSDKDelegate {

It should look like this.

 
extension ViewController: PaymobSDKDelegate{
    func transactionRejected() {
        print("Transaction Rejected")
        
    }
    
    func transactionAccepted(transactionDetails: [String : Any]) {
        print("Transaction Successfull: \(transactionDetails)")
    }
    
    func transactionPending() {
        print("Transaction Pending")
    }
}

Step 3: Create a constant

 
let paymob = PaymobSDK()

Step 4: Pass self to delegate

 
paymob.delegate = self

Step 5: Create the variables

 
// Replace this string with your payment key
let client_secret = "" //Put Client Secret Here
let public_key = "" // Put Public Key Here

Client Secret

A unique, intention-specific token used to redirect the customer to Paymob’s Unified Checkout or to render Paymob’s Pixel component.

Public Key

If you’re using saved cards, pass the saved token as a string in the card_tokens array when calling the intention creation request

Step 6: Customize the UI of the SDK

You can customize the UI of the SDK, such as

 
// the extra UI Customization parameters are

//sets the title to be the image you want
appIcon

//sets the title to be the name you want
appName

//changes the color of the buttons throughout the SDK, the default is black
buttonBackgroundColor

//changes the color of the buttons Texts throughout the SDK, the default is white
buttonTextColor

//set save card checkbox initial value
saveCardDefault

//set whether or not should show save card checkbox
showSaveCard

//used like this
let paymob = PaymobSDK()

paymob.paymobSDKCustomization.appIcon = UIImage()
paymob.paymobSDKCustomization.appName = ""
paymob.paymobSDKCustomization.buttonBackgroundColor = UIColor.black
paymob.paymobSDKCustomization.buttonTextColor = UIColor.white
paymob.paymobSDKCustomization.showSaveCard = true
paymob.paymobSDKCustomization.saveCardDefault = false

try paymob.presentPayVC(VC: self, PublicKey: public_key, ClientSecret: client_secret)
paymob.paymobSDKCustomization.saveCardDefault = false

Step 7: Run the SDK

 
do{
    try paymob.presentPayVC(VC: self, PublicKey: public_key, ClientSecret: client_secret)
} catch let error {

}

Outcome: Integrate Paymob's native Android SDK

Manual installation

Step 1: Download SDK files (.jar/.aar)

Download the SDK from this link and unzip the “Sdk package” folder.

Step 2: Locate the SDK files in app/libs/ folder

Copy the SDK folder into the libs directory of your Android project.

Step 3: Add the repository to settings.gradle.kts

Add required local Repositories as follows:

 
repositories {
    maven {
        url = rootProject.projectDir.toURI().resolve("libs")     }
    maven {
        url = uri("https://jitpack.io")
    }
 }

Step 4: Add a dependency in app/build.gradle.kts

 
implementation("com.paymob.sdk:Paymob-SDK:{{latest version}}")//Please change this version number to match the version number of the downloaded sdk

Step 5: Enable data binding in app/build.gradle.kts

Add your data-binding feature in BaseAppModuleExtensions as follows:

 
android {
    buildFeatures { dataBinding = true } }

Step 6: Sync gradle project

Usage imports

 
import com.paymob.paymob_sdk.PaymobSdk
import com.paymob.paymob_sdk.domain.model.CreditCard
import com.paymob.paymob_sdk.domain.model.SavedCard
import com.paymob.paymob_sdk.ui.PaymobSdkListener

Implement Paymob Sdk listener interface

 
class MainActivity : AppCompatActivity(), PaymobSdkListener { override fun onCreate(savedInstanceState: Bundle?) {…}
override fun onSuccess() {
//If the Payment is successful }
override fun onFailure() {
//If The Payment is declined }
override fun onPending() {
//If The Payment is pending }
}

Create a PaymobSdk instance

You can create the PaymobSdk instance using PaymobSdk.Builder()

 
val paymobsdk = PaymobSdk.Builder(
context = this@MainActivity,
clientSecret = “CLIENT_SECRET”,//Place Client Secret here
publicKey = “PUBLIC_KEY”,//Place Public Key here
paymobSdkListener = this
)
.build()

Client Secret

A unique, intention-specific token used to redirect the customer to Paymob’s Unified Checkout or to render Paymob’s Pixel component.

Public Key

To pass the saved token to the SDK, you should pass the token as a string to the card_tokens array while calling the intention creation request

You can set the SDK buttons' color and buttons' text color using this builder object, for example:

 
val paymobsdk = PaymobSdk.Builder(
context = this@MainActivity,
clientSecret = “CLIENT_SECRET”,//Place Client Secret here
publicKey = “PUBLIC_KEY”,//Place Public Key here
paymobSdkListener = this,
)
.setButtonBackgroundColor(Color.BLACK)//changes the color of button backgrounds throughout the SDK, and set by default to black
.setButtonTextColor(Color.WHITE)//changes the color of button texts throughout the SDK, and set by default to white
.showSaveCard(showSaveCard ?: true) //changes the ability for the sdk to save the card info or no
.saveCardByDefault(saveCardDefault ?: false) //changes the ability for the sdk if the save card checkbox is checked ot not
.build()

Finally: Run the SDK

You can start the SDK by calling

 
sdk.start()

Outcome: Integrate Paymob's native SDKs using a Flutter bridge

The Flutter SDK works as a bridge that connects your Flutter app to the native iOS and Android Paymob SDKs.

Dart section

Import dependency

• Redirect into your Dart file.
• Import the following dependency.

 
import 'package:flutter/services.dart';

Add the code that will call the SDK

Add the following code to the same file.

This is the function that you will call in your Dart file when you need to call the SDK.

You need to pass the public and client secret keys to this function. These two parameters are required. The other parameters are optional.

 
    static const methodChannel = MethodChannel('paymob_sdk_flutter');
  // Method to call native PaymobSDKs
  Future<void> _payWithPaymob(
      String pk,
      String csk,
      { String? appName,
        Color? buttonBackgroundColor,
        Color? buttonTextColor,
        bool? saveCardDefault,
        bool? showSaveCard} ) async {
    try {
      final String result = await methodChannel.invokeMethod('payWithPaymob', {
        "publicKey": pk,
        "clientSecret": csk,
        "appName": appName,
        "buttonBackgroundColor": buttonBackgroundColor?.value,
        "buttonTextColor": buttonTextColor?.value,
        "saveCardDefault": saveCardDefault,
        "showSaveCard": showSaveCard
      });
      print('Native result: $result');
      switch (result) {
        case 'Successfull':
          print('Transaction Successfull');
          // Do something for accepted
          break;
        case 'Rejected':
          print('Transaction Rejected');
          // Do something for rejected
          break;
        case 'Pending':
          print('Transaction Pending');
          // Do something for pending
          break;
        default:
          print('Unknown response');
      // Handle unknown response
      }
    } on PlatformException catch (e) {
      print("Failed to call native SDK: '${e.message}'.");
    }
  }

Client Secret

A unique, intention-specific token used to redirect the customer to Paymob’s Unified Checkout or to render Paymob’s Pixel component.

Public Key

To pass the saved token to the SDK, you should pass the token as a string to the card_tokens array while calling the intention creation request

Optional parameters

The following are optional Parameters that are used to customize the SDK

 
// the extra UI Customization parameters are
//sets the header to be the name you want
appName
//changes the color of the buttons throughout the SDK, the default is black
buttonBackgroundColor
//changes the color of the buttons Texts throughout the SDK, the default is white
buttonTextColor
//set save card checkbox initial value
saveCardDefault
//set whether or not should show save card checkbox
showSaveCard

IOS section

Download the SDK

You can download the SDK from this link and extract it on the local machine.

Locate SDK files in the project directory

Physically place the SDK files in your project folder structure

Add SDK to frameworks, libraries, and embedded content

Drag and drop the PaymobSDK.xcframework folder into Frameworks, Libraries, and Embedded Content under the General Settings of Xcode.

Change the embedding option to "Embed & Sign"

In the general settings of your project, under Frameworks, Libraries, and Embedded Content, change the library from "Do not embed" to "Embed and Sign"

Import the framework

In your AppDelegate file. Add the following import

 
import PaymobSDK

Create a global variable

 
    var SDKResult: FlutterResult?

Code to handle receiving a call from Dart

Add the following code to handle receiving a call from the Dart file

 
        let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
        let nativeChannel = FlutterMethodChannel(name: "paymob_sdk_flutter",
                                                 binaryMessenger: controller.binaryMessenger)
        
        
        nativeChannel.setMethodCallHandler { (call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in
            if call.method == "payWithPaymob",
               let args = call.arguments as? [String: Any]{
                self.SDKResult = result
                
                self.callNativeSDK(arguments: args, VC: controller)
            } else {
                result(FlutterMethodNotImplemented)
            }
        }

Code to handle calling the native PaymobSDK

 
// Function to call native PaymobSDK
      private func callNativeSDK(arguments: [String: Any], VC: FlutterViewController) {
          
          // Initialize Paymob SDK
          let paymob = PaymobSDK()
          paymob.delegate = self
          
          //customize the SDK
          if let appName = arguments["appName"] as? String{
              paymob.paymobSDKCustomization.appName = appName
          }
          if let buttonBackgroundColor = arguments["buttonBackgroundColor"] as? NSNumber{
              
              let colorInt = buttonBackgroundColor.intValue
              let alpha = CGFloat((colorInt >> 24) & 0xFF) / 255.0
              let red = CGFloat((colorInt >> 16) & 0xFF) / 255.0
              let green = CGFloat((colorInt >> 8) & 0xFF) / 255.0
              let blue = CGFloat(colorInt & 0xFF) / 255.0
              
              let color = UIColor(red: red, green: green, blue: blue, alpha: alpha)
              
              paymob.paymobSDKCustomization.buttonBackgroundColor = color
          }
          if let buttonTextColor = arguments["buttonTextColor"] as? NSNumber{
              
              let colorInt = buttonTextColor.intValue
              let alpha = CGFloat((colorInt >> 24) & 0xFF) / 255.0
              let red = CGFloat((colorInt >> 16) & 0xFF) / 255.0
              let green = CGFloat((colorInt >> 8) & 0xFF) / 255.0
              let blue = CGFloat(colorInt & 0xFF) / 255.0
              
              let color = UIColor(red: red, green: green, blue: blue, alpha: alpha)
              
              paymob.paymobSDKCustomization.buttonTextColor = color
          }
          if let saveCardDefault = arguments["saveCardDefault"] as? Bool{
              paymob.paymobSDKCustomization.saveCardDefault = saveCardDefault
          }
          if let showSaveCard = arguments["showSaveCard"] as? Bool{
              paymob.paymobSDKCustomization.showSaveCard = showSaveCard
          }
          
                
          
          // Call Paymob SDK with publicKey and clientSecret
          if let publicKey = arguments["publicKey"] as? String,
             let clientSecret = arguments["clientSecret"] as? String{
              do{
                  try paymob.presentPayVC(VC: VC, PublicKey: publicKey, ClientSecret: clientSecret)
              } catch let error {
                  print(error.localizedDescription)
              }
              return
          }
      }

Code to handle the result of the SDK

Add the following at the bottom to handle the result of the SDK

 
extension AppDelegate: PaymobSDKDelegate {
    public func transactionAccepted(transactionDetails: [String: Any]) {
        self.SDKResult?(["status": "Successfull", "details": transactionDetails])
    }
    
    public func transactionRejected(message : String) {
        self.SDKResult?("Rejected")
    }
    
    public func transactionPending() {
        self.SDKResult?("Pending")
    }
}

Android Section

Download SDK files (.jar/.aar)

Download the SDK from this link and unzip the “Sdk package” folder.

Locate the SDK files in app/libs/ the folder

Redirect into the Android directory.

Then, create a new directory there called 'libs' and place the Android SDK there

Add repository

Inside the root Android directory, open the build.gradle, Then, add the code below inside

 
allprojects {
    repositories {
        ...
        maven {
            url = rootProject.projectDir.toURI().resolve("libs")
        }
        maven {
            url = uri("https://jitpack.io")
        }
    }
}

should look like this.

Then open the settings.gradle, Then add the following code

 
pluginManagement {
    repositories {
        ...
        maven {
            url = rootProject.projectDir.toURI().resolve("libs")
        }
        maven {
            url = uri("https://jitpack.io")
        }

should look like this

Add dependency and enable databinding

Inside the app directory, open the build.gradle file and add the following

 
dependencies {
   implementation("com.paymob.sdk:Paymob-SDK:{{latest version}}")//Please change this version number to match the version number of the downloaded sdk
}
android {
    ...
    buildFeatures { dataBinding = true }
}

should look like this

Code to handle receiving a call from Dart, calling the native SDK, and handling the result of the SDK

Then, in the MainActivity, add the following:

 
import android.graphics.Color
import android.util.Log
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel
import io.flutter.plugin.common.MethodChannel.MethodCallHandler
import io.flutter.plugin.common.MethodChannel.Result
import io.flutter.embedding.android.FlutterActivity
import android.os.Bundle
import android.widget.Toast
import com.paymob.paymob_sdk.PaymobSdk
import com.paymob.paymob_sdk.domain.model.CreditCard
import com.paymob.paymob_sdk.domain.model.SavedCard
import com.paymob.paymob_sdk.ui.PaymobSdkListener
class MainActivity: FlutterActivity(), MethodCallHandler, PaymobSdkListener {
    private val CHANNEL = "paymob_sdk_flutter"
    private var SDKResult: MethodChannel.Result? = null
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        flutterEngine?.dartExecutor?.binaryMessenger?.let {
            MethodChannel(it, CHANNEL).setMethodCallHandler { call, result ->
                if (call.method == "payWithPaymob") {
                    SDKResult = result
                    callNativeSDK(call)
                } else {
                    result.notImplemented()
                }
            }
        }
    }
    // Function to call native PaymobSDK
    private fun callNativeSDK(call: MethodCall) {
        val arguments = call.arguments as? Map<String, Any>
        val publicKey = call.argument<String>("publicKey")
        val clientSecret = call.argument<String>("clientSecret")
        var buttonBackgroundColor: Int? = null
        var buttonTextColor: Int? = null
        val appName = call.argument<String>("appName")
        val buttonBackgroundColorData = call.argument<Number>("buttonBackgroundColor")?.toInt() ?: 0
        val buttonTextColorData = call.argument<Number>("buttonTextColor")?.toInt() ?: 0
        val saveCardDefault = call.argument<Boolean>("saveCardDefault") ?: false
        val showSaveCard = call.argument<Boolean>("showSaveCard") ?: true
        
        if (buttonTextColorData != null){
            buttonTextColor = Color.argb(
                (buttonTextColorData shr 24) and 0xFF,  // Alpha
                (buttonTextColorData shr 16) and 0xFF,  // Red
                (buttonTextColorData shr 8) and 0xFF,   // Green
                buttonTextColorData and 0xFF            // Blue
            )
        }
        Log.d("color", buttonTextColor.toString())
        if (buttonBackgroundColorData != null){
            buttonBackgroundColor = Color.argb(
                (buttonBackgroundColorData shr 24) and 0xFF,  // Alpha
                (buttonBackgroundColorData shr 16) and 0xFF,  // Red
                (buttonBackgroundColorData shr 8) and 0xFF,   // Green
                buttonBackgroundColorData and 0xFF            // Blue
            )
        }
        val paymobsdk = PaymobSdk.Builder(
            context = this@MainActivity,
            clientSecret = clientSecret.toString(),
            publicKey = publicKey.toString(),
            paymobSdkListener = this,
        ).setButtonBackgroundColor(buttonBackgroundColor ?: Color.BLACK)
            .setButtonTextColor(buttonTextColor ?: Color.WHITE)
            .setAppName(appName)
            .showSaveCard(showSaveCard ?: true)
            .saveCardByDefault(saveCardDefault ?: false)

        .build()
        paymobsdk.start()
        return
    }
    //PaymobSDK Return Values
    override fun onSuccess() {
        //If The Payment is Accepted
        SDKResult?.success("Successfull")
    }
    override fun onFailure() {
        //If The Payment is declined
        SDKResult?.success("Rejected")
    }
    override fun onPending() {
        //If The Payment is pending
        SDKResult?.success("Pending")
    }
     override fun onMethodCall(call: MethodCall, result: Result) {
    }
}

Outcome: Integrate Paymob's React Native SDK

Installation Steps for React Native SDK

To get started with the paymob-reactnative package, follow these steps:

• Open your terminal, navigate to your React Native project directory, and install the paymob-reactnative package using yarn:

yarn add paymob-reactnative@https://github.com/PaymobAccept/paymob-reactnative-sdk.git

iOS

Install CocoaPods for iOS

If you’re building for iOS, you’ll need CocoaPods to link the native SDK correctly.

From your project root, run:

cd ios
pod install 
cd .. 

This step ensures that the necessary native modules are linked correctly in your iOS project.

Android

Add the dependency repository

AAdd the following snippet to your project-level build.gradlefile.

 
allprojects {
    repositories {
        maven {
            url = rootProject.projectDir.toURI().resolve("../node_modules/paymob-reactnative/android/libs")
        }
        maven {
            url = uri("https://jitpack.io")
        }
    }
}

Enable data binding

Add the following snippet to your app-level build.gradlefile.

 
android {
    buildFeatures { dataBinding = true }
}

Using Paymob

To begin using the Paymob SDK in your react native application, start by importing the module in your component:

 
import Paymob, { PaymentResult, CreditCardType } from 'paymob-reactnative';

Customize the SDK

You can adjust the SDK’s look and behavior to match your app’s branding before showing the payment screen.

 
Paymob.setAppIcon(base64Image); // Set your merchant logo using a base64 encoded image
Paymob.setAppName('Paymob SDK'); // Customize merchant app name displayed in the Paymob interface
Paymob.setButtonTextColor('#FFFFFF'); // Set the text color of buttons in the SDK
Paymob.setButtonBackgroundColor('#000000'); // Set the background color of buttons in the SDK
Paymob.setShowSaveCard(true); // Enable the option for users to save their cards
Paymob.setSaveCardDefault(true); // Set saved card option as default for transactions

These options help keep the payment experience consistent with your app’s design.

Listen for payment results

To handle payment results effectively, you can add a listener that will respond to different transaction statuses. This is crucial for providing feedback to users about their payment transactions:

 
Paymob.setSdkListener((status: PaymentResult) => {
  switch (status) {
    case PaymentResult.SUCCESS:
      // Handle successful payment
      break;
    case PaymentResult.FAIL:
      // Handle failed payment
      break;
    case PaymentResult.PENDING:
      // Handle pending payment status
      break;
  }
});

This listener will allow you to implement logic based on the result of the payment process, enhancing the user experience.

Invoking the SDK

After configuring the SDK, you can invoke the Paymob payment interface with the following code:

 
const savedBankCards = [
  {
    maskedPan: '1234', // The masked card number displayed to the user
    savedCardToken: 'CARD_TOKEN', // The token representing the saved card
    creditCard: CreditCardType.MASTERCARD, // The type of the credit card (e.g., Mastercard)
  },
];

Paymob.presentPayVC('CLIENT_SECRET', 'PUBLIC_KEY', savedBankCards);

Note: The savedBankCards parameter is optional. If you do not have saved bank cards to provide, you can simply call the presentPayVC method without it.

This function call opens the Paymob payment interface, allowing users to complete their transactions securely. Make sure to replace 'CLIENT_SECRET' and 'PUBLIC_KEY' with your actual credentials.

Here’s the updated explanation with a revised first sentence and the inclusion of the repository cloning step:

Example App

To explore the SDK or test its features, you can clone the repository and run the example app by following these steps:

1. Clone the RepositoryClone the repository to your local machine.

yarn

2. Run the Example App

You can run the example app for both iOS and Android platforms:

• To run the app on iOS, use the following command:

yarn example ios

• To run the app on Android, use this command:

yarn example android

By following these steps, you can explore the functionality of the SDK in the example app.

Outcome: Understand the different types of Paymob callbacks, their purposes, and HMAC calculation.

Definition

Transaction callbacks are mechanisms used by Paymob to notify your system about payment-related events and transaction statuses. They ensure your platform stays in sync with what happens during and after a customer completes a payment.

When does Paymob send the transaction callback?

Paymob sends the transaction callback only if the transaction succeeds or is declined

Types of Transaction Callbacks

Paymob provides two types of transaction callbacks to keep both your system and your customers informed about payment results:

Transaction Processed Callback

Used to notify your backend system about transaction events and status changes, allowing you to update orders, trigger business logic, and keep your records in sync.

Transaction Response Callback

Used to redirect the customer back to your platform after payment, so you can display the payment result and guide the next user action.

Each callback serves a different purpose and is designed to support both system-level handling and customer-facing communication. Detailed technical implementation for each callback is covered in the following sub-page.

Who is this for: Technical product managers and developers who need to understand how they can authenticate Paymob callbacks.

Outcome: Understand the HMAC calculation mechanism.

What is HMAC Authentication?

HMAC (Hash-based Message Authentication Code) is a widely used cryptographic technique designed to ensure both the integrity and authenticity of a message. It combines a cryptographic hash function (such as SHA-512) with a secret key and a string of data to produce a unique signature, known as an HMAC. This signature serves as a guarantee that the message has not been altered during transmission and confirms the identity of the sender.

Whenever you receive a callback from Accept, even if it's (Processed, Response, or Card token), it includes an HMAC query parameter. You should calculate the HMAC using the received data and compare it with the provided value to verify the callback’s authenticity.

Calculation steps guidelines

At a high level, HMAC authentication works as follows:

• Paymob sends transaction data along with an HMAC value.
• You recreate this HMAC using the received data and your hmac secret key.
• You compare your generated HMAC with the one received.
• If both values match, the callback is verified and trusted.

This mechanism ensures that your system only processes valid callbacks sent by Paymob.