Paymob

Getting Started

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/a70d615e-025d-49b6-9e96-46c35062befe-696ce029f28038f7d24990ca.svg"}'>
  <title>Who is this for</title>
  <description><p>Anyone involved in setting up or managing payments with Paymob, including</p>
<strong class="slate-bold">Merchants, Developers</strong>
<p>, and</p>
<strong class="slate-bold">Product or technical teams</strong>
<strong class="slate-bold">Outcome:</strong>
<p>know where to start, what you need, and which path makes the most sense for you</p></description>
</Card>

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.

### **Payment methods available**

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

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/80dd3618-64f7-4fc7-953f-5df953647bac-696ce029f28038f7d24990ca.png"}'>
  <title>Cards</title>
  <description><Image url="https://d14vbsg24p2jga.cloudfront.net/80dd3618-64f7-4fc7-953f-5df953647bac-696ce029f28038f7d24990ca.png" alt="" caption="" attributes='{"isFitToPage":false,"style":{"isFitToPage":false,"style":{},"width":"329px","height":"206px","aspectRatio":"329 / 206"},"width":"329px","height":"206px"}'/>

<p>Methods included: Visa, Mastercard, Amex, MADA, OmanNet</p>
<p>When to use: Standard online card payments with 3D Secure</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/1ce0165d-f5ec-4915-b8a0-a7b80fec4615-696ce029f28038f7d24990ca.png"}'>
  <title>Mobile Wallets</title>
  <description><Image url="https://d14vbsg24p2jga.cloudfront.net/1ce0165d-f5ec-4915-b8a0-a7b80fec4615-696ce029f28038f7d24990ca.png" alt="" caption="" attributes='{"isFitToPage":false,"style":{"isFitToPage":false,"style":{},"width":"318px","height":"199px","aspectRatio":"318 / 199"},"width":"318px","height":"199px"}'/>

<strong class="slate-bold">Methods included:</strong>
<p>Vodafone Cash, Orange Cash, e& money, We Pay, … in EgyptStcPay in KSA</p>
<strong class="slate-bold">When to use:</strong>
<p>Basic banking services are provided by banks and their agents (e.g., mobile network operators).</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/cf460047-a7a3-4f03-9cd8-3dba304944e0-696ce029f28038f7d24990ca.png"}'>
  <title>Quick Payments</title>
  <description><Image url="https://d14vbsg24p2jga.cloudfront.net/cf460047-a7a3-4f03-9cd8-3dba304944e0-696ce029f28038f7d24990ca.png" alt="" caption="" attributes='{"isFitToPage":false,"style":{"isFitToPage":false,"style":{},"width":"329px","height":"206px","aspectRatio":"329 / 206"},"width":"329px","height":"206px"}'/>

<p>Methods included: Apple Pay, Google Pay When to use: Faster checkout using cards saved on the user’s device or browser</p></description>
</Card>
</CardGroup><CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/e1ac240a-ee7b-414f-9907-f018e197cbdd-696ce029f28038f7d24990ca.png"}'>
  <title>BNPL</title>
  <description><Image url="https://d14vbsg24p2jga.cloudfront.net/e1ac240a-ee7b-414f-9907-f018e197cbdd-696ce029f28038f7d24990ca.png" alt="" caption="" attributes='{"isFitToPage":false,"style":{"isFitToPage":false,"style":{},"width":"371px","height":"232px","aspectRatio":"371 / 232"},"width":"371px","height":"232px"}'/>

<p>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</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/efa1d142-0b3e-437d-9946-7a585cf11510-696ce029f28038f7d24990ca.png"}'>
  <title>In-Person Payments</title>
  <description><Image url="https://d14vbsg24p2jga.cloudfront.net/efa1d142-0b3e-437d-9946-7a585cf11510-696ce029f28038f7d24990ca.png" alt="" caption="" attributes='{"isFitToPage":false,"style":{"isFitToPage":false,"style":{},"width":"355px","height":"222px","aspectRatio":"355 / 222"},"width":"355px","height":"222px"}'/>

<p>Methods included: Tap to Pay When to use: Accept contactless payments on supported devices using the Paymob App</p></description>
</Card>
</CardGroup>

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Not all payment methods are enabled by default. Availability depends on your merchant account setup. Reach out to your Paymob account manager if you need specific methods enabled.</p>
</Callout>

### **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.

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"bad9f7a8-2b6d-4474-861b-6df2cc6940f3","title":"Integration option"},{"id":"dc00c10c-12ca-47f6-9980-99b3204bc8f0","title":"Best For"},{"id":"90e5e9ce-ade4-4242-bf09-f42a29233fb7","title":"Time to launch (Estimated)"},{"id":"ec21e6a7-e0c1-49b1-b4be-20d7e203d0df","title":"Technical level"}]'>
  <table-row>
    <table-cell>Payment links</table-cell>
    <table-cell>Freelancers, invoicing, social selling</table-cell>
    <table-cell>Minutes</table-cell>
    <table-cell>None</table-cell>
  </table-row>
  <table-row>
    <table-cell>E-commerce plugins</table-cell>
    <table-cell>Shopify, WooCommerce, Magento</table-cell>
    <table-cell>Hours</table-cell>
    <table-cell>Low</table-cell>
  </table-row>
  <table-row>
    <table-cell>Hosted checkout</table-cell>
    <table-cell>PCI-compliant payment redirection</table-cell>
    <table-cell>Days</table-cell>
    <table-cell>Medium</table-cell>
  </table-row>
  <table-row>
    <table-cell>Pixel (Embedded)</table-cell>
    <table-cell>Embedded checkout experience</table-cell>
    <table-cell>Days–Weeks</table-cell>
    <table-cell>High</table-cell>
  </table-row>
  <table-row>
    <table-cell>Mobile SDKs</table-cell>
    <table-cell>iOS, Android, Flutter, React Native</table-cell>
    <table-cell>Days–Weeks</table-cell>
    <table-cell>High</table-cell>
  </table-row>
</Table>

### **Not sure where to start?**

Use this quick guide:

*   **No developers involved?** → Start with [**Payment Links**](696ce041097f75d4e3f6925c/696ce041097f75d4e3f6925e)
    
*   **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**
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can always switch or expand later as your business grows.</p>
</Callout>

### **How payments work (at a high level)**

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

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title=""><p>A customer starts a payment on your website or app</p></Step>
<Step stepNumber="2" title=""><p>Payment details are collected through a hosted or embedded checkout</p></Step>
<Step stepNumber="3" title=""><p>Paymob processes the payment and handles authentication</p></Step>
<Step stepNumber="4" title=""><p>Your system gets the result through a webhook</p></Step>
<Step stepNumber="5" title=""><p>The customer sees a success or failure confirmation</p></Step>
</Steps>

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:

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/295c4b84-8763-46a4-998b-5a8005513f88-696ce029f28038f7d24990ca.svg"}'>
  <title>Sandbox (Test)</title>
  <description><p>What it's for: Development and testing</p>
<p>When to use it: While building and QA</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/83245c06-0208-4ac1-aa2c-b15a4a7eb9de-696ce029f28038f7d24990ca.svg"}'>
  <title>Production (Live)</title>
  <description><p>What it's for: Real payments When to use it: After go-live approval</p></description>
</Card>
</CardGroup>

Both environments use the same base URL.

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"}}'>
  <title></title>
  <description><p>Egypt:</p>
<p>https://accept.paymob.com/</p>
<p>Oman:</p>
<p>https://oman.paymob.com/</p>
<p>Saudi Arabia:</p>
<p>https://ksa.paymob.com/</p>
<p>United Arab Emirates:</p>
<p>https://uae.paymob.com/</p></description>
</Card><Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Always use test credentials while developing.</p>
</Callout>

### **What you’ll need before you begin**

Here’s a quick checklist to help you prepare.

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/d7db9f8a-bea1-46d0-a87b-c288443cecba-696ce029f28038f7d24990ca.svg"}'>
  <title>For all integrations</title>
  <description><ul class="slate-ul "><li class="slate-li "><div style="position:relative">A Paymob merchant account</div></li><li class="slate-li "><div style="position:relative">Access to the Paymob Dashboard</div></li><li class="slate-li "><div style="position:relative">Completed business verification</div></li></ul></description>
</Card><Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/a9025639-85e3-4244-a586-ef1f1ff7ca72-696ce029f28038f7d24990ca.svg"}'>
  <title>For API or SDK integrations</title>
  <description><ul class="slate-ul "><li class="slate-li "><div style="position:relative">API Secret Key and Public Key</div></li><li class="slate-li "><div style="position:relative">Integration ID(s) for your payment methods</div></li><li class="slate-li "><div style="position:relative">A webhook endpoint</div></li><li class="slate-li "><div style="position:relative">Success and failure redirect URLs</div></li></ul></description>
</Card><Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/79c4573a-cb3d-403d-9426-62569cbc24b8-696ce029f28038f7d24990ca.svg"}'>
  <title>For e-commerce plugins</title>
  <description><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Admin access to your platform</div></li><li class="slate-li "><div style="position:relative">Integration ID(s)</div></li><li class="slate-li "><div style="position:relative">API key, secret key, and public key</div></li></ul></description>
</Card>

### **Where to go next**

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

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"1a5a664f-2a09-43ad-9e92-c997b6d41784","title":"Title"},{"id":"e0381397-5dc5-4d11-84f8-1ede73c61bb8","title":"Description"}]'>
  <table-row>
    <table-cell>Your goal</table-cell>
    <table-cell>Start here</table-cell>
  </table-row>
  <table-row>
    <table-cell>Accept your first payment quickly</table-cell>
    <table-cell>Quick start guide</table-cell>
  </table-row>
  <table-row>
    <table-cell>Set up API credentials</table-cell>
    <table-cell>API keys setup</table-cell>
  </table-row>
  <table-row>
    <table-cell>Test your integration</table-cell>
    <table-cell>Test environment & credentials</table-cell>
  </table-row>
  <table-row>
    <table-cell>Prepare for production</table-cell>
    <table-cell>Integration checklist</table-cell>
  </table-row>
  <table-row>
    <table-cell>Get guided setup</table-cell>
    <table-cell>Onboarding wizard</table-cell>
  </table-row>
</Table>

**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](https://mailto:support@paymob.com)
    
*   **Community:** Join the Paymob Developer Community

Overview

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/0afbddd7-4510-40d7-bcb2-b0b8a880534c-696ce029f28038f7d24990ca.png"}'>
  <title>Who is this for: Developers and product managers</title>
  <description><p>that are preparing to launch Paymob in production</p>
<strong class="slate-bold">Outcome</strong>
<p>:Confirm that your integration is complete, tested, and ready for a smooth go-live</p></description>
</Card>

<Divider />

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Don't skip steps; each one is required for a successful launch.</p>
</Callout>

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/ab9124c7-7945-4530-94fb-19af4d115ac0.jpg" alt="" caption="" attributes='{"width":"637px","height":"236px"}'/>

Integration Checklist

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/0afbddd7-4510-40d7-bcb2-b0b8a880534c-696ce029f28038f7d24990ca.png"}'>
  <title>Who is this for: Everyone</title>
  <description><span style="background-color:rgb(255, 255, 255);color:rgb(0, 0, 0)"><strong class="slate-bold">Outcome:</strong></span>
<span style="background-color:rgb(255, 255, 255);color:rgb(0, 0, 0)">Build the integration plan using this interaction wizard</span></description>
</Card>

<Divider />

Onboarding Wizard

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/0afbddd7-4510-40d7-bcb2-b0b8a880534c-696ce029f28038f7d24990ca.png"}'>
  <title>Who is this for: Everyone</title>
  <description><p>Outcome: Full and quick guide for the Paymob dashboard.</p></description>
</Card>

### Sign-up

<Video url="https://applepayhelper.mobdocs.online/Paymob_Account_Creation_demo"/>

<Divider />

### Settings

From the settings tab, you manage the main configurations of your account, like:

*   Edit the **Business Branding**, including (Business name, Account Type, Sector, Industry, social media links, and adding your business logo)
    
*   Edit the **Contact Information**, including (Company Name, Phone Numbers, and Email Addresses)
    
*   Get your **Account Info**, including integration credentials (Secret key, Public Key, API Key, and HMAC secret), and account status (Live/Test)
    
*   Control the **Settings** of some notifications and reporting features
    

<Divider />

### Checkout Customization

You can personalize the checkout experience directly from your Merchant Dashboard, enabling you to do the following:

#### **Branding**

*   Add business logo and details
    
*   Customize the colors to match your brand
    
*   Customize the font to match your brand
    
*   Customize the style of buttons (Rounded or Rectangular)
    

#### Payment

*   Customize the way of listing the payment methods on the Unified Checkout (Tab or List)
    
*   Control the enabled and disabled payment methods on the Unified Checkout
    
*   Display the billing address
    
*   Display the sold item(s) details
    
*   Display the **save card** checkbox
    
*   Enable the Split Payment feature and control the number of cards
    
*   Display the terms & conditions link to your customers on the Unified Checkout
    
*   Allow/disable payment retrials
    

#### Post Payment

*   Show a custom thank you message
    
*   Change the after-payment redirection experience
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Notes:</p>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative">Changes will only take effect after you click "Apply changes"</div></li><li class="slate-li "><div style="position:relative">If you wish to revert to the default settings provided by Paymob, click "Reset"</div></li></ul>
</Callout>

<Divider />

### Payment Integrations

From the Payment Integrations tab, you can:

*   Get your integration(s) according to the selected mode (**Live**/**Test**)
    
*   Add **test** Integrations for the payment methods (**Card = MIGS**, **Wallet,** and **Kiosk**) if you don't have one
    
*   Update the callback URLs for your integration(s)
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Make sure that you have selected the desired mode (live/test)</p>
</Callout>

<Divider />

### Transactions

From the Transactions tab, you can:

*   Get your transactions according to the selected mode (**Live**/**Test**).
    
*   Filter transactions using multiple options (**Date range, Transaction ID, Order ID, Merchant Order ID,** and **Status**).
    
*   View all details for the selected transaction (**Transaction Details, Order Details, Shipping Details, Billing Details,** and **Installment information** for installment transactions).
    
*   Perform supported actions on the selected transaction based on its type and current status (e.g., Refund, Void, Capture).
    

<Divider />

### Orders

From the Orders tab, you can:

*   Get your order according to the selected mode (**Live**/**Test**).
    
*   Filter transactions using multiple options (**Date range, Order ID,** and **Merchant Order ID**).

Dashboard

Integration Paths

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
  <title>Who is this for: Product managers and developers</title>
  <description><p>who need a high-level overview to plan the payment feature for their app or website</p>
<strong class="slate-bold">Outcome:</strong>
<p>Understand the overall payment flow and the available integration options</p></description>
</Card><Divider />

### **Phase 1: Define Your Product & Integration Method**

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

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title=""><p>What are you building?</p><ul class="slate-ul "><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Website</strong>: If you're building a website, you can integrate through APIs if you're building it from scratch or with an already-made plugin if you're using an E-commerce platform that we've a plugin for or a partnership with.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Mobile Application</strong>: If you're building a mobile application, you can integrate through APIs and open a native mobile UI using our SDKs or open the web UI through a webview.</div></li></ul><p></p></Step>
<Step stepNumber="2" title="How are you building it?"><ul class="slate-ul "><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Custom-built website or Mobile application with our web UI through a webview</strong>: Check the <a href="69306c6d30bd9ea692214c5f/6942b0bc45d09bd96cb08e54" target="_self"><strong class="slate-bold">APIs</strong></a> page, which provides the high-level integration flow through APIs.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">E-commerce platform</strong>: Please check the <a href="69306c6d30bd9ea692214c5f/6942b087213f1ac94a5921a1" target="_self"><strong class="slate-bold">E-Commerce Plugins</strong></a> section to get full guidance on our supported plugins and how to easily install and configure.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">SDK</strong>: Please check the <a href="69306c6d30bd9ea692214c5f/6942b094213f1ac94a592205" target="_self"><strong class="slate-bold">Mobile SDKs</strong></a> page, which provides the high-level integration flow through the SDKs</div></li></ul><p></p></Step>
</Steps><Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>The</p>
  <strong class="slate-bold">webview</strong>
  <p>doesn't support the Apple Pay payment method; you should integrate through the</p>
  <strong class="slate-bold">SDK</strong>
  <p>.</p>
</Callout>

<Divider />

### **Phase 2: Choose Your Payment Options**

Select the payment methods and types that match your needs.

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title=""><p>Which Payment method will you offer?</p><p>Please check the supported</p><a href="692e3ef227393304f3d695d7/692e3ef227393304f3d695d9" target="_self"><strong class="slate-bold">Payment Methods</strong></a><p>section to get full guidance on each payment method and the integration ways that support it.</p><p></p></Step>
<Step stepNumber="2" title=""><p>Which payment feature will you use?</p><ul class="slate-ul "><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Normal 3D Secure (3DS)</strong>: Please check the <a href="692e3ef227393304f3d695d7/692e3ef227393304f3d695d9/692e3ef227393304f3d695db" target="_self"><strong class="slate-bold">3D Secure (3DS)</strong></a> explained in the Card payment method page to know more about it.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Auth/Cap</strong>: Please check the <a href="692e3ef227393304f3d695d7/692e3ef227393304f3d695e1/692e3ef227393304f3d695e9" target="_self"><strong class="slate-bold">Auth/Cap</strong></a> page to know more about it.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Pay with saved tokens</strong>: Please check the <a href="692e3ef227393304f3d695d7/692e3ef227393304f3d695e1/692e3ef227393304f3d695e5" target="_self"><strong class="slate-bold">Pay With Saved Cards</strong></a> section to know more about it and its types (<strong class="slate-bold">MIT</strong> and <strong class="slate-bold">CIT</strong>), and how to implement each of them.</div></li></ul><p></p></Step>
</Steps>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>For the subscription module, which enables you to configure subscriptions that Paymob will use in the future to deduct an amount periodically without your intervention in the next billings, please check the Subscriptio section.</p>
</Callout>

<Divider />

Still not updated

### **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 [**Payment Actions**](https://developers.paymob.com/egypt/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**](https://support@paymob.com), and we'll be glad to help you get the best payment experience for your business.

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/b4f2de7d-c553-4807-bf4c-8184e0de3bc7-696ce029f28038f7d24990ca.png"}'>
  <title>Who is this for: Product managers and Merchants (non-technical)</title>
  <description><p>who want to start accepting online payments without any coding or development</p>
<strong class="slate-bold">Outcome:</strong>
<p>Start accepting online payments using Payment Links even without a website or development team.</p></description>
</Card>

**Overview**:

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>Payment Links (fastest start)</title>
  <description><p>Ideal when you don't have a website. Share via WhatsApp, social media, or any communication tool.</p>
<strong class="slate-bold">Good for:</strong>
<p>Event tickets, reservations, small businesses, electronic invoices</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>Invoice Links (for services)</title>
  <description><p>Send a customized invoice with full details and let customers pay online.</p>
<strong class="slate-bold">Good for:</strong>
<p>Consulting, training, clinics, repairs, deposits, B2B collections</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>Product Links (reusable)</title>
  <description><p>Create once and share broadly. No website needed.</p>
<strong class="slate-bold">Good for:</strong>
<p>Tickets, subscriptions, digital goods, fixed-price services</p></description>
</Card>
</CardGroup>

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 into an electronic invoice
    

<Divider />

Option B: Invoice Links (for services and custom orders)
--------------------------------------------------------

Send a customized invoice with full details and let customers pay online, with payment confirmation when the payment completes.

**Good for:**

*   Consulting, training, clinics, repairs
    
*   Deposits and partial payments
    
*   B2B collections
    

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Important:</p>
</Callout>

Option C: Product Links (one link you can reuse)
------------------------------------------------

Create a product link once and share it broadly to reach customers wherever they are — no website needed.

**Good for:**

*   Tickets, subscriptions, digital goods
    
*   “Pay now” for a fixed-price service
    
*   Best-selling items you promote regularly
    

<Divider />

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.

<Divider />

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

No Code

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9f43ec87-6e1f-4f2f-8f3d-0f13ed673fc0-696ce029f28038f7d24990ca.svg"}'>
  <title>Who is this for: Product managers and developers</title>
  <description><p>who need a high-level overview of how to integrate through APIs and our available checkout experiences</p>
<strong class="slate-bold">Outcome:</strong>
<p>Understand the overall API payment flow, the available checkout options, and how payment results are securely communicated back to your system</p></description>
</Card>

custom website

calling third-party APIs

mobile app

web-based checkout in a WebView

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/48ee4b1b-6b30-45cc-9e3d-ea79b0c1277b.jpg" alt="API Integration Flow" caption="" attributes='{"width":"903px","height":"307px"}'/>

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="" title=""><p>Every payment starts by calling the</p><strong class="slate-bold">Intention Creation API</strong><p>from your backend.</p><p>This step initializes the payment by defining:</p><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Amount and currency</div></li><li class="slate-li "><div style="position:relative">Allowed payment methods</div></li><li class="slate-li "><div style="position:relative">Your internal order or reference ID</div></li></ul><p>The response includes a reference (client secret) that is used to launch the checkout experience.</p></Step>
<Step stepNumber="" title=""><p>Once the intention is created, you present one of Paymob's checkout experiences:</p><strong class="slate-bold">Unified Checkout (Redirect)</strong><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Customer is redirected to a Paymob-hosted checkout page</div></li><li class="slate-li "><div style="position:relative">Fastest integration with minimal frontend effort</div></li><li class="slate-li "><div style="position:relative">Paymob handles UI, validation, and security</div></li></ul><strong class="slate-bold">Embedded Checkout (Pixel)</strong><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Paymob checkout UI component is embedded inside your website or WebView</div></li><li class="slate-li "><div style="position:relative">More control over the checkout look and feel</div></li><li class="slate-li "><div style="position:relative">Sensitive payment data is still handled securely by Paymob</div></li></ul></Step>
<Step stepNumber="" title=""><p>The customer enters their payment details and completes any required authentication (such as 3D Secure). Paymob processes the transaction and determines the final payment status.</p></Step>
<Step stepNumber="" title=""><p>After processing the payment, Paymob sends callbacks to your backend to notify you of the payment result.</p><p>Callbacks should be used to:</p><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Confirm the final payment status</div></li><li class="slate-li "><div style="position:relative">Update order records</div></li><li class="slate-li "><div style="position:relative">Trigger business actions (e.g., fulfillment, notifications)</div></li></ul></Step>
<Step stepNumber="" title=""><p>Each callback can be authenticated using</p><strong class="slate-bold">HMAC verification</strong><p>to ensure it was sent by Paymob and was not altered.</p><p>Always verify callbacks before trusting their data.</p></Step>
</Steps><Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <strong class="slate-bold">Important:</strong>
  <p>Callbacks are the source of truth for payment status. Redirects are mainly for user experience.</p>
</Callout>

APIs

Who is this for: E-commerce store owners and developers

using platforms like Shopify, WooCommerce, Magento, OpenCart, or other supported CMS

**Outcome:** 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 \## Supported Platforms<CardGroup attributes='{"isFitToPage":false,"style":{"width":"60%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Shopify</p>
<p>Native Shopify integration for seamless checkout</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>WooCommerce</p>
<p>WordPress plugin for WooCommerce stores</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Magento</p>
<p>Extension for Magento 1.x and 2.x</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>OpenCart</p>
<p>Extension for OpenCart stores</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>PrestaShop</p>
<p>Module for PrestaShop stores</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Odoo</p>
<p>Integration for Odoo ERP versions 15-18</p></description>
</Card>
</CardGroup>\## How it works

Download and install the Paymob plugin from your platform's marketplace or extensions directory.

Enter your Paymob API credentials (API Key, Integration ID, HMAC Secret) in the plugin settings.

Select which payment methods to offer (Cards, Wallets, BNPL, etc.).

Test with sandbox mode, then switch to live mode when ready.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Check the detailed setup guides for each platform in the Developer Reference section.</p>
</Callout>

Plugins

Who is this for: Product managers and mobile developers

who need a high-level overview of how to integrate through Mobile SDKs

**Outcome:** Understand the overall mobile flow, 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. \## Available SDKs<CardGroup attributes='{"isFitToPage":false,"style":{"width":"60%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>iOS SDK</p>
<p>Native Swift SDK for iPhone and iPad apps</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Android SDK</p>
<p>Native Kotlin/Java SDK for Android apps</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Flutter SDK</p>
<p>Cross-platform SDK for Flutter apps</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>React Native SDK</p>
<p>Cross-platform SDK for React Native apps</p></description>
</Card>
</CardGroup>\## Integration flow

Every SDK payment starts from your backend by calling the **Intention Creation API**.

This step is responsible for:

*   Defining the amount and currency
*   Selecting the allowed payment methods
*   Linking the payment to your internal order or reference ID

The response includes an **intention reference (client secret)** that will be passed to the Mobile SDK.

In your mobile app (iOS or Android), initialize the Paymob Mobile SDK using the intention reference received from your backend.

At this stage:

*   The SDK is configured with the payment intention
*   No sensitive payment data is handled by your app

This keeps your mobile application outside the PCI scope.

Once initialized, the SDK presents Paymob's **native checkout UI** within your app, where the customer will complete the payment.

The checkout experience follows the platform's native look and feel, while Paymob handles **input validation, security, and any required authentication** (such as 3D Secure) seamlessly.

After the payment is processed, Paymob **sends callbacks to your backend** with the final payment result and **returns a status to the mobile app via the SDK callback**.

*   **Backend callbacks** must be used to confirm the final payment status, update orders, and trigger business actions.
*   **SDK callbacks** should be used only to update the UI and show success or failure messages.

Each callback can be authenticated using **HMAC verification** to ensure it was sent by Paymob and was not altered.

Always verify callbacks before trusting their data.

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <strong>Important:</strong>
  <p>Always rely on backend callbacks, not SDK responses alone, to confirm payment success. Backend callbacks are the source of truth.</p>
</Callout>

Mobile SDKs

**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

<Divider />

Paymob enables businesses to accept and manage digital payments through a wide range of **payment methods** and **payment 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.

Payments & Features

**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

<Divider />

### 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

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Card Payments</p>
<p>Allow customers to pay using debit or credit cards. This is the most common payment method and supports standard online card payment flows</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Mobile Wallets</p>
<p>Enable payments using mobile wallets linked to a customer’s phone number</p>
<p></p></description>
</Card>
</CardGroup>

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Buy Now, Pay Later (BNPL)</p>
<p>Allow customers to split payments into installments over time. This option helps increase affordability and conversion rates</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Apple Pay</p>
<p>Provide a fast and secure payment experience for Apple users using their saved cards on supported Apple devices</p></description>
</Card>
</CardGroup>

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Google Pay</p>
<p>Enable quick checkout for Android and Chrome users using cards saved to their Google account</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Kiosk</p>
<p>Allow customers to generate a payment reference and complete the payment later through supported offline kiosks</p></description>
</Card>
</CardGroup>

Payment Methods

**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 model

<Divider />

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

<div class="card-group-box" style="width:100%; min-width:540px;">
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Subscription Module</p>
<p>Automate recurring payments by charging customers periodically based on predefined subscription plans.</p></div></div></div>
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Pay With Saved Cards</p>
<p>Allows returning customers to pay quickly without re-entering card details, streamlining checkout and increasing repeat purchases.</p></div></div></div>
</div><div class="card-group-box" style="width:100%; min-width:540px;">
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Authorization & Capture (Auth/Cap)</p>
<p>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.</p></div></div></div>
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Split Features</p>
<p>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).</p></div></div></div>
</div><div class="card-group-box" style="width:100%; min-width:540px;">
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Convenience Fee</p>
<p>Merchants can add additional charges to cover transaction processing costs or service fees, clearly presented to customers at checkout.</p></div></div></div>
<div class="card-box"><div class="card-title-and-description"><div class="card-description"><p>Transaction Inquiry & Reports</p>
<p>Provides insights into payments through detailed reports and Transaction Inquiry APIs, helping merchants track performance and reconcile accounts.</p></div></div></div>
</div>

Core Features

**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

<Divider />

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**](692e3ef227393304f3d695d7/692e3ef227393304f3d695f1/692e3ef227393304f3d695f7) Used when you need to return funds to a customer.
    
*   [**Void**](692e3ef227393304f3d695d7/692e3ef227393304f3d695f1/6964c1e61ec3ce2a761cdc52) Used when you need to cancel a transaction, mostly available on the same business day.
    
*   [**Capture**](692e3ef227393304f3d695d7/692e3ef227393304f3d695f1/692e3ef227393304f3d695f3) Used when you need to collect funds from a previously authorized transaction.

Managing Payments

Authentication Request (Generate Auth Token)

Intention APIs

**Who is this for:** Developers who implement the integration

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

<Divider />

### Endpoint

`/v1/intention/`

### Method

**POST**

### Authorization

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

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>To know how to get your secret key, please check the</p>
  <p>Getting Integration Credentials</p>
  <p>page.</p>
</Callout>

### Request body

Parameters clarified below:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"f88093ea-d51e-4312-b97e-5563aed27d9e","title":"Title"},{"id":"6fac172b-a7e0-4341-b9b1-82f77d6acf27","title":"Description"},{"id":"0a377a1a-924e-4e9a-91cc-0cdb88203c55","title":"Mandatory"}]'>
  <table-row>
    <table-cell>Total Amount (amount)</table-cell>
    <table-cell>The total transaction amount, expressed in cents.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Payment Methods (payment_methods)</table-cell>
    <table-cell>The Integration ID(s) used to process the payment. Values can be provided as integers (e.g., 1256) or as names enclosed in quotes (e.g., "card"). The status (Live/Test) of the provided ID(s) should match the status of the secret key used for authentication.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Currency (currency)</table-cell>
    <table-cell>The currency in which the transaction is processed. This must match the currency of the selected Integration ID.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Description (description)</table-cell>
    <table-cell>A textual description of the item, located under the items array. The maximum allowed length is 255 characters.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Quantity (quantity)</table-cell>
    <table-cell>The number of units for the item, located under the items array.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Amount (amount)</table-cell>
    <table-cell>The item amount, expressed in cents and located under the items array. When multiple items are provided, the sum of all item amounts must equal the total transaction amount.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Name (name)</table-cell>
    <table-cell>The name of the item, located under the items array. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>First Name (first_name)</table-cell>
    <table-cell>The customer’s first name, located under the billing_data object. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Last Name (last_name)</table-cell>
    <table-cell>The customer’s last name, located under the billing_data object. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Email (email)</table-cell>
    <table-cell>The customer’s email address, located under the billing_data object.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Country (country)</table-cell>
    <table-cell>The customer’s country name, located under the billing_data object.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Phone Number (phone_number)</table-cell>
    <table-cell>The customer’s phone number, located under the billing_data object. Both international and domestic formats are supported, including alpha-2 and standard numeric country codes.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Extras (extras)</table-cell>
    <table-cell>A set of additional custom parameters provided by the merchant. These values are returned in callbacks under the payment key claims object.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Expiration (expiration)</table-cell>
    <table-cell>The validity duration of the payment intention, expressed in seconds. After expiration, the intention can no longer be paid.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Special Reference (special_reference)</table-cell>
    <table-cell>A unique reference associated with the transaction or order, returned in the transaction callback under merchant_order_id.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Notification URL (notification_url)</table-cell>
    <table-cell>A callback URL that receives a POST request with full transaction details after the transaction succeeds or fails. Supported only with card Integration IDs. This endpoint</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Redirection URL (redirection_url)</table-cell>
    <table-cell>A URL to which the customer is redirected after the transaction completes, with transaction details included as query parameters. Supported only with card and wallet payment methods.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
</Table>

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Important Notes:</p>
  <p>The endpoint used in the notification URL will receive the transaction callback (transaction details) and the card token (for pay with saved card features)</p>
</Callout>

### Response

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

**Important parameters:** **Order ID**: Paymob order ID, which will be received in the transaction callback and can be used to correlate the transaction to the order on your system.

**Intention ID**: Paymob intention ID can be used to do the same of the Order ID.

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

<Divider />

### Common errors

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Using a wrong or not well-configured integration ID</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 404 Not Found</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "detail": "Integration ID/Name does not exist in our system . You can find the list of Integration ID’/Names from Merchant Dashboard under Developers → Payment Integrations Tab"</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "detail": "Integration ID/Name does not exist in our system . You can find the list of Integration ID’/Names from Merchant Dashboard under Developers → Payment Integrations Tab"</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>To know how to get your integration ID, please check the</p>
  <p>Getting Integration Credentials</p>
  <p>page.</p>
</Callout>

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Missing item name or amount</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 400 Bad Request</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "items": {</CodeLine>
  <CodeLine>        "name": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "items": {</CodeLine>
  <CodeLine>        "name": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
    "items": {
        "amount": [
            "This field is required."
        ]
    }
}</CodeLine>
  <CodeLine>{
    "items": {
        "amount": [
            "This field is required."
        ]
    }
}</CodeLine>
</CodeBlock>

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

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Missing phone number in the billing data object</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 400 Bad Request</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "billing_data": {</CodeLine>
  <CodeLine>        "phone_number": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "billing_data": {</CodeLine>
  <CodeLine>        "phone_number": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

**Solution** : Make sure to enter a phone number.

Create Intention

**Who is this for:** Developers who implement the integration

**Outcome:** Update an **Intention** that will be used to complete a payment, either via APIs or through one of our UI options. Mostly used with the **Pixel component**.

<Divider />

### Endpoint

`/v1/intention/`

### Method

**PUT**

### Authorization

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

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>To know how to get your secret key, please check the</p>
  <p>Getting Integration Credentials</p>
  <p>page.</p>
</Callout>

### Path parameter

You should pass the **client\_secret** as a path parameter like below: `/v1/intention/<client_secret>`

### Request body

Parameters that can be sent in the body of the request are clarified below:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"1ce77135-c2f0-481f-9e9d-d1cdbfdf7419","title":"Title"},{"id":"702abf33-735b-4842-b9a3-0055039772c9","title":"Description"},{"id":"f7d0a2e8-f057-438d-a9f3-be0420fedeee","title":"Mandatory"}]'>
  <table-row>
    <table-cell>Accept Order ID (accept_order_id)</table-cell>
    <table-cell>Reference to an existing Accept order ID connected with the client secret sent as a path parameter, as explained above.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Total Amount (amount)</table-cell>
    <table-cell>The total transaction amount, expressed in cents.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Description (description)</table-cell>
    <table-cell>A textual description of the item, located under the items array. The maximum allowed length is 255 characters.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Quantity (quantity)</table-cell>
    <table-cell>The number of units for the item, located under the items array.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Amount (amount)</table-cell>
    <table-cell>The item amount, expressed in cents and located under the items array. When multiple items are provided, the sum of all item amounts must equal the total transaction amount.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Items Name (name)</table-cell>
    <table-cell>The name of the item, located under the items array. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>First Name (first_name)</table-cell>
    <table-cell>The customer’s first name, located under the billing_data object. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Last Name (last_name)</table-cell>
    <table-cell>The customer’s last name, located under the billing_data object. The maximum allowed length is 50 characters.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Email (email)</table-cell>
    <table-cell>The customer’s email address, located under the billing_data object.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Country (country)</table-cell>
    <table-cell>The customer’s country name, located under the billing_data object.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Phone Number (phone_number)</table-cell>
    <table-cell>The customer’s phone number, located under the billing_data object. Both international and domestic formats are supported, including alpha-2 and standard numeric country codes.</table-cell>
    <table-cell>Yes</table-cell>
  </table-row>
  <table-row>
    <table-cell>Special Reference (special_reference)</table-cell>
    <table-cell>A unique reference associated with the transaction or order, returned in the transaction callback under merchant_order_id.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Notification URL (notification_url)</table-cell>
    <table-cell>A callback URL that receives a POST request with full transaction details after the transaction succeeds or fails. Supported only with card Integration IDs. This endpoint</table-cell>
    <table-cell>No</table-cell>
  </table-row>
  <table-row>
    <table-cell>Redirection URL (redirection_url)</table-cell>
    <table-cell>A URL to which the customer is redirected after the transaction completes, with transaction details included as query parameters. Supported only with card and wallet payment methods.</table-cell>
    <table-cell>No</table-cell>
  </table-row>
</Table>

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Important Notes:</p>
  <p>The endpoint used in the notification URL will receive the transaction callback (transaction details) and the card token (for pay with saved card features)</p>
</Callout>

#### Response

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

**Important parameters:** **Order ID**: Paymob order ID, which will be received in the transaction callback and can be used to correlate the transaction to the order on your system.

**Intention ID**: Paymob intention ID can be used to do the same of the Order ID.

**Client Secret**: A variable token that is unique per intention, and will be used to redirect the customer to **Paymob's UnifiedCheckout** or render **Paymob's Pixel component**.

<Divider />

### Common errors

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Missing Accept Order ID parameter</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 400 Bad Request</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>accept_order_id": [</CodeLine>
  <CodeLine>        "This field is required."</CodeLine>
  <CodeLine>    ]</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>accept_order_id": [</CodeLine>
  <CodeLine>        "This field is required."</CodeLine>
  <CodeLine>    ]</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

**Solution** : Make sure the Accept Order ID parameter is included in the request.

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Missing item name or amount</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 400 Bad Request</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "items": {</CodeLine>
  <CodeLine>        "name": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "items": {</CodeLine>
  <CodeLine>        "name": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
    "items": {
        "amount": [
            "This field is required."
        ]
    }
}</CodeLine>
  <CodeLine>{
    "items": {
        "amount": [
            "This field is required."
        ]
    }
}</CodeLine>
</CodeBlock>

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

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title></title>
  <description><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Missing phone number in the billing data object</CodeLine>
  <CodeLine>Status Code</CodeLine>
  <CodeLine>: 400 Bad Request</CodeLine>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "billing_data": {</CodeLine>
  <CodeLine>        "phone_number": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "billing_data": {</CodeLine>
  <CodeLine>        "phone_number": [</CodeLine>
  <CodeLine>            "This field is required."</CodeLine>
  <CodeLine>        ]</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine></CodeLine>
</CodeBlock>

</description>
</Card>

**Solution** : Make sure the phone number parameter is included in the request.

Update Intention

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers and technical stakeholders</h3>
<p>building online payment flows who need to understand Paymob's front-end checkout options and choose the one that best fits their product</p>
<p><strong>Outcome:</strong> Understand the checkout experiences supported by Paymob, and know when to use Unified Checkout vs. Pixel.</p>
</Card>

---

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.

<div style="width:100%;min-width:100%;" class="callout-widget" data-type="info"><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div><p>You can customize the Unified Checkout appearance through the Checkout Customization section in the Dashboard.</p></div></div>

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

<div style="width:100%;min-width:100%;" class="callout-widget" data-type="info"><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div><p>The client secret serves as the bridge between your backend (where you create the intention) and the checkout UI (hosted or embedded) that the customer interacts with.</p></div></div>

### Choosing Between Unified Checkout and Pixel

| Feature | Unified Checkout | Pixel |
|---------|------------------|-------|
| Checkout location | Redirect to hosted page | Embedded on your site |
| Branding control | Standard Paymob look, with simple customization | Matches your UI |
| Setup complexity | Simple | Requires SDK integration |
| Best for | Quick integration | Custom embedded experience |

Checkout Experiences

**Who is this for:** Developers who implement the integration

**Outcome:** Redirect the customers to Paymob's Unified Checkout to process and complete the payment, and customize the Unified Checkout.

<Divider />

### Endpoint

Use the following URL to redirect the user to Paymob's Unified Checkout page:

/unifiedcheckout/?publicKey=&clientSecret=

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Each region has its own base URL, as clarified below.</p>
</Callout>

### Base URLs

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Egypt:</CodeLine>
  <CodeLine>https://accept.paymob.com/</CodeLine>
  <CodeLine>Oman:</CodeLine>
  <CodeLine>https://oman.paymob.com/</CodeLine>
  <CodeLine>Saudi Arabia:</CodeLine>
  <CodeLine>https://ksa.paymob.com/</CodeLine>
  <CodeLine>United Arab Emirates:</CodeLine>
  <CodeLine>https://uae.paymob.com/  </CodeLine>
</CodeBlock>

### Query Parameters

#### Client Secret

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

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can get a client secret by calling the</p>
  <p>.</p>
</Callout>

#### Public Key

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>To know how to get your public key, please check the</p>
  <p>Getting Integration Credentials</p>
  <p>page.</p>
</Callout>

<Divider />

Customize Your Checkout
-----------------------

You can personalize the checkout experience directly from your Merchant Dashboard, enabling you to do the following:

### **Branding**

*   Add business logo and details
    
*   Customize the colors to match your brand
    
*   Customize the font to match your brand
    
*   Customize the style of buttons (Rounded or Rectangular)
    

### Payment

*   Customize the way of listing the payment methods on the Unified Checkout (Tab or List)
    
*   Control the enabled and disabled payment methods on the Unified Checkout
    
*   Display the billing address
    
*   Display the sold item(s) details
    
*   Display the **save card** checkbox
    
*   Enable the Split Payment feature and control the number of cards
    
*   Display the terms & conditions link to your customers on the Unified Checkout
    
*   Allow/disable payment retrials
    

### Post Payment

*   Show a custom thank you message
    
*   Change the after-payment redirection experience
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Notes:</p>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative">Changes will only take effect after you click "Apply changes"</div></li><li class="slate-li "><div style="position:relative">If you wish to revert to the default settings provided by Paymob, click "Reset"</div></li></ul>
</Callout>

Unified Checkout (Redirection)

**Who is this for:** Developers who implement the integration

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

<Divider />

### Pre-Requisites

*   Integrate the Intention API as described in the documentation for the [Create Payment Intention API.](692e3ef227393304f3d695fd/69525e7a0c92ee7c7bdb1fed/6953c994885397a8b1cdb3e3)
    
*   Include the following script and stylesheets in your HTML file
    

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"html","label":"HTML"}'>

</CodeBlock>

### Usage

Create a new Pixel instance

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>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'
   },});</CodeLine>
</CodeBlock>

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' }, });

Note

: If Google Pay is passed as a Payment Method, you must include the Google Pay SDK

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Google Pay isn't supported in</p>
  <p>Egypt</p>
  <p>yet; it's coming soon. Stay tuned.</p>
</Callout>

#### Properties

The full list of properties is as follows:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"2e799ea3-f66c-4b18-83a1-52e3f9d32f56","title":"Property name"},{"id":"fcf03928-7000-46e7-b58a-abca61d4a511","title":"Type"},{"id":"a5a96df0-0911-4bbb-940e-65cd9a5e2272","title":"Definition"}]'>
  <table-row>
    <table-cell>publicKey</table-cell>
    <table-cell>String</table-cell>
    <table-cell>To know how to get your public key, please check the Getting Integration Credentials page.</table-cell>
  </table-row>
  <table-row>
    <table-cell>clientSecret</table-cell>
    <table-cell>String</table-cell>
    <table-cell>Once you fire the 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 it expires in an hour.</table-cell>
  </table-row>
  <table-row>
    <table-cell>paymentMethods</table-cell>
    <table-cell>Array of String</table-cell>
    <table-cell>Pass “card” for Card Payments, "google-pay" for Google Pay, and “apple-pay” for Apple Pay.</table-cell>
  </table-row>
  <table-row>
    <table-cell>elementId</table-cell>
    <table-cell>String</table-cell>
    <table-cell>ID of the HTML element where the checkout pixel will be embedded.</table-cell>
  </table-row>
  <table-row>
    <table-cell>disablePay</table-cell>
    <table-cell>Boolean</table-cell>
    <table-cell>Pass true. If you don’t want to use Paymob’s Pay Button for Card Payment, in this case, you will dispatchEvent with the name (payFromOutside) to fire the pay.</table-cell>
  </table-row>
  <table-row>
    <table-cell>showSaveCard</table-cell>
    <table-cell>Boolean</table-cell>
    <table-cell>If this option is set to TRUE, users will have the option to save their card details for future payment.</table-cell>
  </table-row>
  <table-row>
    <table-cell>forceSaveCard</table-cell>
    <table-cell>Boolean</table-cell>
    <table-cell>If this option is set to true, the user's card details will be saved automatically without requiring their consent</table-cell>
  </table-row>
  <table-row>
    <table-cell>afterPaymentComplete</table-cell>
    <table-cell>Function</table-cell>
    <table-cell>This Functionality will be processed after payment is processed by Paymob. Check the full example below.</table-cell>
  </table-row>
  <table-row>
    <table-cell>customStyle</table-cell>
    <table-cell>Object</table-cell>
    <table-cell>You can pass custom styles; for more details, check the full example below.</table-cell>
  </table-row>
</Table>

#### 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:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"217344e7-3a1c-4528-b27b-e5a1f6a6bbb9","title":"Title"},{"id":"27aa5c5d-f0d3-4558-8f47-3856a5ac6c88","title":"Description"}]'>
  <table-row>
    <table-cell>Event</table-cell>
    <table-cell>Definition</table-cell>
  </table-row>
  <table-row>
    <table-cell>payFromOutside</table-cell>
    <table-cell>In case you need to use you pay button instead of the SDK pay button.</table-cell>
  </table-row>
</Table>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"html","label":"HTML"}'>
  <CodeLine>Pay From Outside Button  </CodeLine>
</CodeBlock>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>const button = document.getElementById('payFromOutsideButton');
      button?.addEventListener
	  ('click', function () 
	  {
        // Calling pay request
        const event = new Event('payFromOutside');
        window.dispatchEvent(event);
      });</CodeLine>
  <CodeLine>const button = document.getElementById('payFromOutsideButton');
      button?.addEventListener
	  ('click', function () 
	  {
        // Calling pay request
        const event = new Event('payFromOutside');
        window.dispatchEvent(event);
      });</CodeLine>
</CodeBlock>

#### Functions

The full list of functions is as follows:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"ac201162-5790-4680-a017-dd774cb8ae49","title":"Function"},{"id":"83fe147f-f402-4ba5-b285-be9ac0a8038a","title":"Definition"},{"id":"929f53c5-3408-45a9-bd73-a86bd3f09e4d","title":"What should you do with?"}]'>
  <table-row>
    <table-cell>cardValidationChanged</table-cell>
    <table-cell>This Functionality will be processed whenever the card validation status changes.</table-cell>
    <table-cell>Writes the function logic</table-cell>
  </table-row>
  <table-row>
    <table-cell>beforePaymentComplete</table-cell>
    <table-cell>Merchants can implement their own custom logic or functions before the payment is processed by Paymob. Check the full example below.</table-cell>
    <table-cell>Writes the function logic</table-cell>
  </table-row>
  <table-row>
    <table-cell>afterPaymentComplete</table-cell>
    <table-cell>This Functionality will be processed after payment is processed by Paymob. Check the full example below.</table-cell>
    <table-cell>Writes the function logic</table-cell>
  </table-row>
  <table-row>
    <table-cell>onPaymentCancel</table-cell>
    <table-cell>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.</table-cell>
    <table-cell>Writes the function logic</table-cell>
  </table-row>
  <table-row>
    <table-cell>updateIntentionData</table-cell>
    <table-cell>Update the intention data within the SDK if any changes occur to the intention. For more details, refer to the Intention Update API documentation.</table-cell>
    <table-cell>Calls the function</table-cell>
  </table-row>
</Table>

### Full sample

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"html","label":"HTML"}'>
  <CodeLine>  </CodeLine>
  <CodeLine>  Pixel Experience</CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>    Hello in my website</CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>    </CodeLine>
  <CodeLine>      </CodeLine>
  <CodeLine>      Pay From Outside Button</CodeLine>
  <CodeLine>    </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
  <CodeLine>  </CodeLine>
</CodeBlock>

Pixel (Embedded)

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers</h3>
<p>who implement the integration</p>
<p><strong>Outcome:</strong> Integrate different SDKs to create and complete payment intentions within your app.</p>
</Card>

---

Paymob's **Mobile SDKs** allow you to integrate Paymob's checkout experience into mobile applications. They support rendering the checkout flow within mobile apps.

If you're already using **Unified Checkout** on the web, think of the mobile SDKs as the same idea but built specifically for mobile apps.

If your app is built with **Flutter** or **React Native**, you can still use the SDKs through our official bridging options.

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

**1. Create Intention**

You need to call the Create Intention API to get a **client secret**.

**2. Initialize the SDK**

Initialize the Mobile SDK by passing:
* client secret
* public key
* Optional configuration parameters that control how the checkout UI is rendered

**3. Receive the payment results**

After the payment is completed, the SDK triggers **predefined callback functions** based on the payment status. You are required to implement the logic for these callbacks to define how your application should behave in each scenario.

IOS SDK

Android SDK

Flutter SDK

**Who is this for:** Developers who implement the integration

**Outcome:** Integrate the React Native SDK to create and complete payment intentions within your app.

This guide walks you through installing and using the Paymob React Native SDK so you can start accepting payments in your app.

**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`

<Divider />

**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:

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-plainText keep-markup drop-tokens"><div class="slate-code_line">cd ios</div><div class="slate-code_line">pod install</div><div class="slate-code_line">cd ..</div></code></pre></div>

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

<div style="width:100%;min-width:100%;" class="callout-widget" data-type="info"><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div><strong class="slate-bold">Important Notice:</strong>
<p>If you run into issues with the native iOS SDK, try creating a new blank</p>
<strong class="slate-bold">Swift file</strong>
<p>in Xcode. When prompted, make sure to select</p>
<p>Create Bridging Header</p></div></div>

<Divider />

**Android**
-----------

### Add the dependency repository

AAdd the following snippet to your **project-level** `build.gradle`file.

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Java</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-java keep-markup drop-tokens"><div class="slate-code_line">allprojects {</div><div class="slate-code_line">repositories {</div><div class="slate-code_line">maven {</div><div class="slate-code_line">url = rootProject.projectDir.toURI().resolve("../node_modules/paymob-reactnative/android/libs")</div><div class="slate-code_line">}</div><div class="slate-code_line">maven {</div><div class="slate-code_line">url = uri("https://jitpack.io")</div><div class="slate-code_line">}</div><div class="slate-code_line">}</div><div class="slate-code_line">}</div></code></pre></div>

#### Enable data binding

Add the following snippet to your app-level `build.gradle`file.

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Java</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-java keep-markup drop-tokens"><div class="slate-code_line">android {</div><div class="slate-code_line">buildFeatures { dataBinding = true }</div><div class="slate-code_line">}</div></code></pre></div>
<Divider />

Using Paymob
------------

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

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">import Paymob, { PaymentResult, CreditCardType } from 'paymob-reactnative';</div></code></pre></div>

Customize the SDK
-----------------

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

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">Paymob.setAppIcon(base64Image); // Set your merchant logo using a base64 encoded image</div><div class="slate-code_line">Paymob.setAppName('Paymob SDK'); // Customize merchant app name displayed in the Paymob interface</div><div class="slate-code_line">Paymob.setButtonTextColor('#FFFFFF'); // Set the text color of buttons in the SDK</div><div class="slate-code_line">Paymob.setButtonBackgroundColor('#000000'); // Set the background color of buttons in the SDK</div><div class="slate-code_line">Paymob.setShowSaveCard(true); // Enable the option for users to save their cards</div><div class="slate-code_line">Paymob.setSaveCardDefault(true); // Set saved card option as default for transactions</div></code></pre></div>

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

<div style="width:100%;min-width:100%;" class="callout-widget" data-type="info"><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div><p>Make sure all customization is done</p>
<strong class="slate-bold">before</strong>
<p>calling</p>
<strong class="slate-bold"> </strong>
<strong class="slate-bold">Paymob.presentPayVC()</strong>
<strong class="slate-bold">. </strong>
<p>Any changes made after that won’t appear on the payment screen.</p></div></div>

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:

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">Paymob.setSdkListener((status: PaymentResult) => {</div><div class="slate-code_line">switch (status) {</div><div class="slate-code_line">case PaymentResult.SUCCESS:</div><div class="slate-code_line">// Handle successful payment</div><div class="slate-code_line">break;</div><div class="slate-code_line">case PaymentResult.FAIL:</div><div class="slate-code_line">// Handle failed payment</div><div class="slate-code_line">break;</div><div class="slate-code_line">case PaymentResult.PENDING:</div><div class="slate-code_line">// Handle pending payment status</div><div class="slate-code_line">break;</div><div class="slate-code_line">}</div><div class="slate-code_line">});</div></code></pre></div>

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:

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">const savedBankCards = [</div><div class="slate-code_line">{</div><div class="slate-code_line">maskedPan: '1234', // The masked card number displayed to the user</div><div class="slate-code_line">savedCardToken: 'CARD_TOKEN', // The token representing the saved card</div><div class="slate-code_line">creditCard: CreditCardType.MASTERCARD, // The type of the credit card (e.g., Mastercard)</div><div class="slate-code_line">},</div><div class="slate-code_line">];</div><div class="slate-code_line">Paymob.presentPayVC('CLIENT_SECRET', 'PUBLIC_KEY', savedBankCards);</div></code></pre></div>

**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:

<Divider />

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 Repository**Clone 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.

React Native SDK

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Technical product managers and developers</h3>
<p>who need to understand how Paymob updates a merchant's system with transaction details</p>
<p><strong>Outcome:</strong> Understand the different types of Paymob callbacks, their purposes, and HMAC calculation.</p>
</Card>

---

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

Webhook (Callbacks) & HMAC

Transaction callbacks

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

<Divider />

### 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](695b93700c92ee7c7b34283f/695b93700c92ee7c7b342845), 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.

HMAC 

Webhook Testing Tool

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers</h3>
<p>who need to manage payment transactions after they are completed</p>
<p><strong>Outcome:</strong> Learn how to refund, void, and capture transactions through the Dashboard and API.</p>
</Card>

---

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

Manage Payment APIs

Refund

Void

Capture

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers</h3>
<p>who need to implement recurring payments and subscription billing</p>
<p><strong>Outcome:</strong> Learn how to create, manage, and cancel subscriptions using Paymob APIs.</p>
</Card>

---

This section covers the Subscription APIs for implementing recurring billing in your application.

Subscription

Create Subscription plan

Create Subscription

**Who is this for:** Technical product managers and developers.

**Outcome:** know briefly the actions that can be executed on the subscription plan.

<Divider />

### Overview

There are some actions that can be executed on the subscription plan through APIs.

### Actions can be executed on the subscription plan

*   Update the parameters (number of deductions, plan amount, Moto integration ID)
    
*   Suspend the plan temporarily
    
*   Resume a suspended plan
    
*   List the plans

Plan actions

**Who is this for:** Developers who implement the integration

**Outcome:** A brief about the actions that can be executed on the subscription plans

<Divider />

### Overview

There are some actions that can be executed on the subscription plan through APIs.

### Actions can be executed on the subscription plan

*   Update the parameters (number of deductions, plan amount, Moto integration ID)
    
*   Suspend the plan temporarily
    
*   Resume a suspended plan
    
*   List the plans

Subscription actions

When a webhook is registered to a subscription, any actions performed on the subscription will trigger a callback. This callback is sent as a POST request to the registered webhook, containing the updated subscription data. The HMAC value for this callback is provided in the body of the subscription callback request as a parameter named `hmac` (unlike transaction or card token callbacks, where it is typically sent as a query parameter).

<Divider />

### Subscription Callback:

<div class="code-block-wrapper" style="width:100%;min-width:100%"><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><code class="language-plainText keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">"paymob_request_id": "df9e4ecf-12e0-4925-b258-65423f32bc98",</div><div class="slate-code_line">"subscription_data": {</div><div class="slate-code_line">"id": 1264,</div><div class="slate-code_line">"client_info": {</div><div class="slate-code_line">"email": "test@test.com",</div><div class="slate-code_line">"full_name": "mo ay",</div><div class="slate-code_line">"phone_number": "01010101010"</div><div class="slate-code_line">},</div><div class="slate-code_line">"frequency": 365,</div><div class="slate-code_line">"created_at": "2024-12-03T22:11:02.280164",</div><div class="slate-code_line">"updated_at": "2024-12-03T22:11:02.280179",</div><div class="slate-code_line">"name": "Testplan 3",</div><div class="slate-code_line">"reminder_days": null,</div><div class="slate-code_line">"retrial_days": null,</div><div class="slate-code_line">"plan_id": 1186,</div><div class="slate-code_line">"state": "suspended",</div><div class="slate-code_line">"amount_cents": 330,</div><div class="slate-code_line">"starts_at": "2024-12-20",</div><div class="slate-code_line">"next_billing": "2024-12-20",</div><div class="slate-code_line">"reminder_date": null,</div><div class="slate-code_line">"ends_at": null,</div><div class="slate-code_line">"resumed_at": null,</div><div class="slate-code_line">"suspended_at": "2024-12-03",</div><div class="slate-code_line">"webhook_url": "https://webhook.site/a16ba9d5-4f4a-47dc-8005-e6ec2d197f26",</div><div class="slate-code_line">"integration": 4565330,</div><div class="slate-code_line">"initial_transaction": 241322967</div><div class="slate-code_line">},</div><div class="slate-code_line">"trigger_type": "suspended",</div><div class="slate-code_line">"hmac": "dd5b3018888d9f98574cd180793db10d969b522e08c62baf2ea33357d1546b567b7fd79760e90046e90eaacf30024ede5539cbd0748bd9e6c005faf5117e0e7b"</div><div class="slate-code_line">}</div></code></pre></div>
<Divider />

### **HMAC Calculation Method**

#### 1\. **Extract the Relevant Parameters**

*   `subscription_data.id`: Subscription ID (`1264` in the example).
    
*   `trigger_type`: The action taken on the subscription (`suspended` in the example).
    

#### 2\. **Create the Concatenated String**

The string format is:

`”{action}for{subscription_id}”`

Example: The string for the above object is “suspendedfor1264“

#### 3\. **Hash the String**

*   Use the SHA-512 hashing algorithm.
    
*   Hash the concatenated string using the merchant’s HMAC secret key. (This step is the same as calculating HMAC for normal [callbacks](https://developers.paymob.com/egypt/manage-callback/transaction-callbacks).)
    

#### 4\. **Compare the HMAC**

Compare the HMAC value sent in the request body (`hmac` parameter) with the calculated HMAC. If they match, the request is authenticated.

<Divider />

Subscription Callback and HMAC Calculation

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers</h3>
<p>who need to implement tokenization and saved card payments</p>
<p><strong>Outcome:</strong> Learn how to save customer card tokens and charge them for future payments.</p>
</Card>

---

This section covers the Pay With Saved Cards APIs for implementing tokenized payments.

Pay With Saved Cards

Create Card Token

CIT (Customer Initiated Transaction)

MIT (Merchant Initiated Transaction)

<Card attributes='{"isFitToPage":true,"iconUrl":"https://d14vbsg24p2jga.cloudfront.net/9496b328-83af-443a-bbea-f71fc79fd125-696ce029f28038f7d24990ca.svg"}'>
<h3>Who is this for: Developers and technical teams</h3>
<p>who want to generate and manage payment links from their systems, rather than manually creating them through the dashboard</p>
<p><strong>Outcome:</strong> Understand what QuickLinks APIs are used for</p>
</Card>

---

QuickLinks APIs allow you to **programmatically create and manage payment links** using Paymob's backend APIs. These links can then be shared with customers to complete payments through a Paymob-hosted checkout experience.

### What Are QuickLinks APIs?

QuickLinks APIs enable you to:

* Create secure, Paymob-hosted payment links programmatically
* Define payment details such as amount, currency, and allowed payment methods
* Cancel payment links from your backend

Once created, a QuickLink can be shared with customers through any communication channel, allowing them to complete the payment without additional integration steps.

### Available API Operations

#### Create QuickLink

Use this API to generate a new payment link with predefined payment details and configurations.

#### Cancel QuickLink

Use this API to invalidate an existing payment link and prevent it from being used for future payments.

QuickLink APIs

Create QuickLink

**Who is this for:** Developers who implement the integration

**Outcome:** Permanently terminate subscription

<Divider />

### Endpoint:

`/api/ecommerce/payment-links/cancel`

### Method

**POST**

### **Authorization**

You should send a valid auth token as a Bearer Token.

<div style="width:100%;min-width:100%;" class="callout-widget" data-type="info"><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div><p>You can get a valid auth token by</p>
<strong class="slate-bold">Authentication Request (Generate Auth Token)</strong></div></div>

### Request Body

Cancel QuickLink

Transaction Inquiry APIs

By Transaction ID

By Order ID or Reference

Split Features Implementation

Need Help?

**A bank/processor that acquires card transactions and settles funds to the merchant.**  

**Accept (Paymob Accept / Checkout)**  Paymob’s online checkout that supports card, wallets, BNPL, etc., via hosted page, plugins, SDKs, or APIs.  

**API Keys (Secret/Public)**  Credentials for API auth. **Secret** is server‑side; **Public** is safe for client init. Rotate on go‑live and incidents.  

**Apple Pay**   Wallet method using tokenized credentials from Apple devices. 

**Authorization (Auth)**  Real‑time issuer approval that reserves funds. May be captured later or reversed.  **Auth/Capture (Two‑step) payment process** that allows you to: 

1.  **Authorize** a payment (hold funds on the customer’s card).
    
2.  **Capture** the payment later (within a time window), either fully or partially.
    

This is useful when you want to **verify funds first**, then **charge only when the product/service is delivered**. **Use Cases** 

*   **E-commerce**: Authorize payment when an order is placed, capture only when shipped.
    
*   **Hotels**: Hold a deposit at check-in, capture actual charges at checkout.
    
*   **Car Rentals**: Hold a security deposit, capture only if there are extra charges.
    

**A bank/processor that acquires card transactions and settles funds to the merchant.**  

**Accept (Paymob Accept / Checkout)**  Paymob’s online checkout that supports card, wallets, BNPL, etc., via hosted page, plugins, SDKs, or APIs.  

**API Keys (Secret/Public)**  Credentials for API auth. **Secret** is server‑side; **Public** is safe for client init. Rotate on go‑live and incidents.  

**Apple Pay**   Wallet method using tokenized credentials from Apple devices. 

**Authorization (Auth)**  Real‑time issuer approval that reserves funds. May be captured later or reversed.  **Auth/Capture (Two‑step) payment process** that allows you to: 

1.  **Authorize** a payment (hold funds on the customer’s card).
    
2.  **Capture** the payment later (within a time window), either fully or partially.
    

This is useful when you want to **verify funds first**, then **charge only when the product/service is delivered**. **Use Cases** 

*   **E-commerce**: Authorize payment when an order is placed, capture only when shipped.
    
*   **Hotels**: Hold a deposit at check-in, capture actual charges at checkout.
    
*   **Car Rentals**: Hold a security deposit, capture only if there are extra charges.
    

**BNPL (Buy Now, Pay Later)** UAE KSA  Installment providers (e.g., **Tabby**, **Tamara**). Terms vary by region/currency and affect refunds/settlement. **BIN / IIN (Bank Identification Number)**  First 6–8 digits of a card; used for routing and eligibility (scheme, issuer, card type). **Callback (Webhook / HMAC‑Signed)**  Server‑to‑server POST from Paymob for state changes. Verify HMAC, implement retries, and ensure idempotent handlers.**Capture**  Converts an approved authorization into a transaction for settlement (full or partial).  **Card on File (CoF)**  Tokenized card reference for future charges (CIT/MIT). Never store PAN; use Paymob tokens.  **Chargeback / Dispute**  Issuer/cardholder‑initiated reversal after settlement (not the same as _Refund_). Involves reason codes and timelines. **Checkout (Hosted Checkout)**  Hosted page that renders methods, handles 3DS, and returns users to your site/app.  **CIT / MIT**  Cardholder‑Initiated vs. Merchant‑Initiated Transaction (e.g., subscriptions). Impacts 3DS and descriptors.  **Descriptor**   Statement text shown to cardholders. Must meet acquirer limits (length/charset). Invalid descriptors can cause declines/disputes. **Environments (Test/Live)**  Separate base URLs, keys, and integration IDs per environment. Never mix.  **Google Pay**   Wallet method for Android/web. Requires gateway config. Region availability applies. **HMAC (Hash‑based Message Authentication Code)**  Signature to verify webhook authenticity/integrity. Compute locally and compare to header. **Integration ID**  An **Integration ID** is a unique identifier in your Paymob dashboard that links your account to a specific **payment method configuration** and **environment** (e.g., live or test). It’s required when making API calls to ensure the transaction uses the correct payment method and setup.  **Intention (Payment Intention / Intent)**  Represents what the customer intends to pay (amount, currency, method, return URLs). Orchestrates 3DS/redirects/callbacks. **Issuer (Issuing Bank)**  Cardholder’s bank that approves/declines an authorization.  **KYC (Know Your Customer)**  Compliance checks required for onboarding and method enablement. Impacts availability/limits in some regions. **KSA**  Regional marker for Saudi Arabia behavior/requirements. **Live Mode (Production)**  Production environment with real funds. Confirm descriptors, callbacks, and 3DS before switching. **MCC (Merchant Category Code)**  Four‑digit code identifying merchant vertical; influences risk, rules, and method availability. **MIT (CIT/MIT)**  Merchant‑initiated, typically off‑session (e.g., subscriptions). Often 3DS‑exempt with prior CIT/consent. **MPGS (Mastercard Payment Gateway Services)**  Mastercard’s gateway platform used by many acquirers; underpins processing/routing in multiple regions. **MIGS (Mastercard Internet Gateway Service)**  Legacy Mastercard internet gateway; largely replaced by MPGS; term persists in older setups.  **MOTO (Paymob MOTO)**  Paymob MOTO allows businesses to charge a customer's credit card without the card being physically present by using securely saved card tokens from previous transactions. This feature is useful for various businesses like hotels, service providers, and personal shoppers, enabling remote payment processing while prioritizing secure data handling.  **MOTO Use Cases:** 

*   **Hotels & Resorts**: Charge for room upgrades or facilities usage after the guest checks out.
    
*   **Service Providers**: Recurring or follow-up charges for services like cleaning, consulting, or repairs.
    
*   **Medical Clinics**: Charge for follow-up appointments or lab results without needing the card again.
    

**Network Token (Scheme Token)**  Tokenized credential issued by schemes to replace PAN and improve auth rates; distinct from gateway/Paymob tokens. **Order vs. Transaction**  _Order_ is your business object (cart/reference); _Transaction_ is the payment event (auth, capture, refund). Reconcile both. **Payment Link (Quick Link)**  Hosted URL you share to collect payment without a website. Configurable amount, expiry, and methods. **Use Cases:** 

*   **Freelancers & Consultants**: Send a payment link after completing a service.
    
*   **Small Businesses**: Collect payments for orders via WhatsApp or Instagram.
    
*   **Event Organizers**: Share links for ticket payments or deposits.
    
*   **Delivery Services**: Send a link once the order is confirmed.
    

 **PCI DSS**  Security standard for handling card data. Hosted checkout/fields and tokens reduce merchant PCI scope.  **Pixel (Native Payment Experience / JS SDK)**  Embedded component for app/web payments while keeping PCI scope minimized. Secrets stay server‑side. **Use Cases:** 

*   **E-commerce Platforms**: Embed checkout directly into product pages or carts.
    
*   **Mobile Apps**: Native payment flow without redirecting to external pages.
    
*   **Subscription Services**: Save cards securely for recurring billing.
    

 **Public Key (Client)**  Client‑side init key; never authorizes payments alone.  **Refund**  Merchant‑initiated return of captured funds (full/partial). BNPL/wallets may have constraints. **Reconciliation**  Match _Orders_ ↔ _Transactions_ ↔ _Payouts_. Keep merchant\_order\_id stable and log Paymob transaction\_id. **Saved Card Token (Token, Card Token)**  Opaque token representing a card for future charges. Scope/expiry defined by Paymob/acquirer.  **Settlement / Payout**  Funds moving from acquirer to merchant after capture/clearing; timing varies by method/currency/acquirer. **Split Payments**  Distribute a single payment to multiple beneficiaries/sub‑accounts per rules or percentages; impacts reconciliation. **Subscriptions**  Recurring billing using initial CIT (often 3DS) then scheduled MIT charges. Document retry windows and events. **Use Cases:** 

*   **Streaming Services**: Monthly billing for content access.
    
*   **Gyms & Fitness Centers**: Auto-renew memberships.
    
*   **Education Platforms**: Recurring payments for courses or tutoring.
    

**Tamara / Tabby** UAE KSA  Regional BNPL providers with specific onboarding, settlement, and refund rules. **Tokenization**  Replace PAN with a token chargeable later; reduces PCI scope and enables saved‑card, subscriptions, and MOTO. **Transaction Reference IDs**  Trackers like merchant\_order\_id (yours) and transaction\_id (Paymob/acquirer). Log both. **UAE**  Regional marker for United Arab Emirates behavior/requirements. **Void**  Cancel an authorization before capture (funds released). Not the same as _Refund_ (post‑capture). **Wallets (Apple Pay, Google Pay, etc.)**  Tokenized device/browser payments; require region‑specific setup and merchant/domain verification. **Webhooks (Events)**  Notifications like authorized, captured, failed, refunded, subscription\_renewed. Verify HMAC, retry idempotently, and log.

Glossary

Documentation

Developers

Paymob-docs

Production

Sandbox

Add Secondary Card

Apple Pay [All regions]

Apple Pay - Certificates Creation

Apple Pay - Domain Verification

Auth/Cap

Bank Installments [EGY]

BNPLs [EGY, KSA, UAE]

Cancel Subscription

Cards [All regions]

Change Subscription Primary card

Convenience Fee

CS-Cart

Delete Secondary Card

Drupal

Getting Integration Credentials

Google Pay [KSA, UAE, OMN]

HMAC Card Token Callback:

HMAC Transaction Callback

Payment Links

Joomla

Laravel-Bagisto

Magento 2

Odoo

OpenCart

OsCommerce

PrestaShop

Shopify

Staah

WHMCS

WordPress (WooCommerce)

ZenCart

Kiosk [EGY]

Last Transaction Subscription

List Subscription Cards

List Subscription Details

List Subscription Plans

List Subscription Transactions

Mobile Wallets [EGY, KSA]

Test Credentials

Split Features

Subscriptions

Transaction inquiry & Reports

Register Webhook

Resume Subscription

Resume Subscription Plan

Suspend Subscription Plan

Update Subscription Plan

Suspend Subscription

Update Subscription

<p class="slate-p " ><strong class="slate-bold">Outcome </strong>- Changing the primary card associated with a specific subscription</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h3 class="slate-h3 " ></h3><h3 class="slate-h3 " ><strong class="slate-bold">Authorization</strong></h3><p class="slate-p slate-indent-0" style="0px">You should send a valid auth token as a Bearer Token. </p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >You can get a valid auth token by <a href="https://developers.paymob.com/paymob-docs/developers/authentication-request-generate-auth-token-1" target=""><strong class="slate-bold">Authentication Request (Generate Auth Token)</strong></a></p></div></div><p class="slate-p " ></p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><div class="accordions-widget " style="width:100%"><details class="accordion-item"><summary class=accordion-header><div class=accordion-title><h3>Common errors</h3></div><div class=accordion-toggle><svg fill=none height=8 viewBox="0 0 12 8"width=12><path d="M11.3278 0.792629C11.1872 0.795955 11.0535 0.854737 10.956 0.956171L5.99972 5.91242L1.04347 0.956171C0.993767 0.90508 0.93433 0.86447 0.868669 0.836738C0.803007 0.809006 0.732454 0.794716 0.661176 0.794712C0.555079 0.79474 0.4514 0.826409 0.363395 0.885669C0.27539 0.94493 0.207057 1.02909 0.167133 1.12739C0.12721 1.22569 0.117509 1.33366 0.139271 1.4375C0.161033 1.54135 0.213269 1.63634 0.289301 1.71034L5.62264 7.04367C5.72266 7.14365 5.85829 7.19982 5.99972 7.19982C6.14114 7.19982 6.27678 7.14365 6.3768 7.04367L11.7101 1.71034C11.7876 1.63586 11.8407 1.53972 11.8626 1.43451C11.8845 1.32931 11.8741 1.21995 11.8328 1.12076C11.7915 1.02157 11.7212 0.937165 11.6311 0.878615C11.541 0.820064 11.4353 0.790094 11.3278 0.792629Z"fill=#141719 fill-opacity=0.84 /></svg></div></summary><div class="accordion-content"><div class="slate-div"></div><h3 class="slate-h3 " ></h3><div class="card-box without-icon" style="width:60%;"><div ><h3 class="slate-h3 " >Invalid Auth Token</h3><p class="slate-p " >401 Unauthorized</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
   &quot;detail&quot;:&quot;incorrect credentials&quot;
}</div></div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Solution</strong>: Make sure to pass a valid and fresh auth token. (Each auth token is valid for an hour)</p></div></div><div class="card-box without-icon" style="width:60%;"><div ><h3 class="slate-h3 " >Passing a wrong card ID</h3><p class="slate-p " >404 Not Found</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
   &quot;message&quot;:&quot;Card not found.&quot;
}</div></div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Solution</strong>: Make sure to pass a valid ID for the card you want to set as a primary one.</p></div></div></div></details></div><p class="slate-p " ></p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p>

- Changing the primary card associated with a specific subscription

You should send a valid auth token as a Bearer Token. 

To Change specific card to make it Primary,from any subscriptions, first check the list of subscription cards and then run this IP by selecting correct card id.Every card has its own id.

Sections

Change Subscription Primary card

Authorization

Common errors

Invalid Auth Token

Passing a wrong card ID

Header Parameters

Path Parameters

Body Parameters

Response

Response Attributes

What made this section unhelpful for you?

Language Box

Response

What made this section unhelpful for you?

Sections

Change Subscription Primary card

Authorization

Common errors

Invalid Auth Token

Passing a wrong card ID

Header Parameters

Path Parameters

Body Parameters

Response

Response Attributes

What made this section unhelpful for you?

Language Box

Response

What made this section unhelpful for you?

Ask an AI

Code with AI