# PayTabs

> PayTabs is a Saudi-built payment orchestration and gateway serving merchants across MENA. The PT2 REST API accepts cards and local methods (mada, Meeza, KNET, OmanNet, Benefit, STC Pay, urpay) plus Apple/Google/Samsung Pay through hosted, managed and own-form flows, with tokenization, recurring billing and invoicing. A small, uniform surface: POST /payment/request creates and manages transactions and POST /payment/query reads their state. Requests are JSON; the merchant server key is sent in the `authorization` header and the profile is identified by `profile_id`.

Generated by API Evangelist (apis.io) from the PayTabs catalog entry and repo artifacts. Not an official PayTabs document.

## Key facts
- Auth: merchant server key as the raw `authorization` header value (NOT Bearer). Separate browser client key for own-form/tokenization. Keys are region-scoped.
- Region hosts: secure.paytabs.com (UAE/default), secure.paytabs.sa (KSA), secure-egypt / -oman / -jordan / -kuwait / -iraq / -morocco / -doha, secure-global. Use the host matching the profile region or auth fails (401).
- Idempotency: merchant `cart_id` is the idempotency key; a duplicate within ~2 minutes is rejected (response code 4). Reconcile with /payment/query before retrying.
- Outcomes: terminal results are delivered via IPN/callback POSTs signed with an HMAC-SHA256 `Signature` header keyed by the Profile ServerKey; HTTPS required; retried up to 5 times.
- Compliance: PCI DSS Level 1; EMV 3-D Secure 2 (Modirum); mada-certified.

## APIs
- [Hosted Payment Page API](https://docs.paytabs.com/manuals/PT-API-Endpoints/Introduction/): POST /payment/request returns a hosted redirect_url.
- [Managed Form API](https://docs.paytabs.com/manuals/PT-API-Endpoints/Introduction/): same flow embedded in an iframe (framed=true).
- [Own Form API](https://docs.paytabs.com/manuals/PT-API-Endpoints/Introduction/): merchant-branded card capture (client key).
- [Transaction Management API](https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Hosted-Payment-Page/HPP-Step-7-Manage-Transactions/HPP-Step-7-Query-Transaction/): POST /payment/query plus capture/void/release/refund.
- [Token & Recurring Billing API](https://docs.paytabs.com/manuals/PT-API-Endpoints/Repeat-Billing/Step-1-Understanding-Workflow-&-Prerequisites/Repeat-Billing-Prerequisites/): tokenise then charge for recurring.
- [Invoices API](https://support.paytabs.com/en/support/solutions/articles/60000902481-3-2-3-invoices-apis-initiating-the-payment-request-download-invoice-pdf): payable invoices / PayLinks.

## Specs & artifacts
- [OpenAPI](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/openapi/paytabs-openapi.yml)
- [Authentication](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/authentication/paytabs-authentication.yml)
- [Conventions](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/conventions/paytabs-conventions.yml)
- [Error / problem types](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/errors/paytabs-problem-types.yml)
- [Decline / response codes](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/errors/paytabs-decline-codes.yml)
- [Webhooks (AsyncAPI)](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/asyncapi/paytabs-webhooks-asyncapi.yml)
- [Data model](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/data-model/paytabs-data-model.yml)
- [Sandbox / testing](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/sandbox/paytabs-sandbox.yml)
- [Packages / SDKs](https://raw.githubusercontent.com/api-evangelist/paytabs/refs/heads/main/packages/paytabs-packages.yml)

## Docs
- [Technical portal](https://docs.paytabs.com/)
- [Support portal](https://support.paytabs.com/en/support/home)
- [PT2 Direct APIs Postman](https://documenter.getpostman.com/view/14575178/TWDRtfWG)
- [Status](https://status.paytabs.com/)
- [Pricing](https://paytabs.com/en/pricing/)