canonical: https://jentic.com/apis/paytabs.com/paytabs

# PayTabs API

PayTabs API provides payment processing for merchants operating in the Middle East and North Africa region. It supports payment page creation, transaction capture, void, refund, and query operations across cards and local payment methods. The API handles tokenized recurring payments and serves merchants in Saudi Arabia, UAE, Egypt, Oman, Jordan, and other MENA markets with multi-currency settlement.

## For AI agents

Process payments, capture authorized transactions, issue refunds, and manage tokenized cards for merchants across the MENA region.

## Scope

Does not handle accounting, inventory management, or shipping - use for payment collection and transaction management only.

## Capabilities

- Create hosted payment pages with customizable fields for MENA payment methods
- Capture pre-authorized transactions with full or partial amounts
- Process refunds for completed transactions with reference tracking
- Void pending authorizations before settlement
- Query transaction status and details by transaction reference
- Tokenize cards for recurring and one-click payment flows

## Use cases

### MENA E-Commerce Checkout

Accept online payments from customers across the Middle East and North Africa. PayTabs creates a hosted payment page supporting cards (Visa, Mastercard, mada, AMEX), Apple Pay, and local methods like SADAD and Fawry. The merchant sends a payment request via POST /request with amount, currency, and callback URL, then redirects the customer to complete payment. PayTabs handles 3D Secure authentication and returns the result to the configured callback.

Example prompt: Create a payment request for 500 SAR with cart description 'Order #1234', customer email buyer@example.com, and return URL https://shop.example.com/callback

### Pre-Authorization and Capture

Hold funds on a customer's card at order time and capture when the goods ship. PayTabs supports authorize-then-capture flows where the initial request places a hold and a subsequent capture call collects the funds. This is common for hotel bookings, car rentals, and marketplaces that need to confirm availability before charging.

Example prompt: Submit an authorization-only payment request for 1200 AED, then capture 1000 AED against the returned transaction reference via POST /capture

### Refund and Void Management

Issue refunds for completed transactions or void pending authorizations before settlement. PayTabs processes full and partial refunds via POST /refund and cancels pre-settlement holds via POST /void. Each operation returns a reference for reconciliation and triggers webhook notifications to the merchant's configured endpoint.

Example prompt: Issue a partial refund of 200 SAR against transaction reference TST2345678 via POST /refund and confirm the refund status

### AI Agent Payment Operations via Jentic

AI agents use the PayTabs API through Jentic to process payments, check transaction statuses, and issue refunds for MENA merchants without handling raw server keys. Agents search by intent, receive typed schemas, and execute calls with Jentic managing credential isolation. This allows automated order management workflows across Saudi Arabia, UAE, and Egypt.

Example prompt: Search Jentic for 'query a PayTabs transaction status', load the schema for POST /query, and execute with the transaction reference to check payment completion

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/request` | Create a payment page and initiate a transaction |
| POST | `/capture` | Capture a pre-authorized transaction |
| POST | `/refund` | Issue a refund for a completed transaction |
| POST | `/void` | Void a pending authorization |
| POST | `/query` | Query transaction status by reference |
| POST | `/token` | Manage tokenized card operations |

## Key resources

- **Payment Requests** — Create hosted payment pages and process card transactions
- **Captures** — Capture pre-authorized amounts fully or partially
- **Refunds** — Issue full or partial refunds for settled transactions
- **Voids** — Cancel pending authorizations before settlement
- **Queries** — Retrieve transaction details and status by reference
- **Tokens** — Manage tokenized card data for recurring payments

## Why Jentic

- **Setup:** Wiring the PayTabs API by hand means managing its server-key authorization header on the secure.paytabs.sa host and sequencing request, capture, and refund calls yourself. Through Jentic you install once, import PayTabs from the API Directory, store the server key once, and your agent calls it.
- **Permission scoping:** PayTabs carries its payment and transaction details in the request body, so scope the agent by the operations it needs, such as query or capture. You choose that set, so operations like refund or void are not included unless you add them.
- **Credential handling:** Your PayTabs server key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a payment in Saudi Arabia' or 'query a transaction', and Jentic returns the matching PayTabs operation with its typed request and response schemas so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Paystack API** — African-focused payment gateway with mobile money support but limited MENA coverage
- **Stripe API** — Global payment processor with broader feature set but fewer local MENA payment methods
- **Flutterwave API** — African payment gateway that can handle Sub-Saharan payouts alongside MENA collection

## FAQ

### What authentication does the PayTabs API use?

The PayTabs API uses a server key passed in the Authorization header. The key format is a string starting with 'S' provided in your PayTabs merchant dashboard. Through Jentic, this server key is stored encrypted and agents never see the raw credential.

### Can I process mada card payments with the PayTabs API?

Yes. PayTabs supports mada debit cards as a payment method for Saudi merchants. When creating a payment request via POST /request, mada appears as an available payment method alongside Visa, Mastercard, and Apple Pay for SAR-denominated transactions.

### What are the rate limits for the PayTabs API?

PayTabs applies per-merchant rate limits based on your subscription tier. Standard accounts can process up to 100 API calls per minute across all endpoints. Contact PayTabs support for higher throughput requirements.

### How do I check a transaction status through Jentic?

Search Jentic for 'query PayTabs transaction', load the schema for POST /query, and execute with the transaction reference in the request body. Jentic injects the server key automatically and returns the transaction status, amount, and payment method in a structured response.

### Which countries does the PayTabs API support?

PayTabs serves merchants in Saudi Arabia, UAE, Egypt, Oman, Jordan, and other MENA markets. Each region has specific payment methods available. The base URL varies by region (secure.paytabs.sa for Saudi, secure.paytabs.com for global).

### Does PayTabs support recurring payments?

Yes. PayTabs supports tokenized recurring payments via POST /token. After the initial payment, the card token can be used for subsequent charges without the customer re-entering card details, enabling subscription and installment models.

### Can I limit what my agent is allowed to do with the PayTabs API?

Yes. Because you self-host Jentic One, your own rules decide which PayTabs operations and credentials the agent may use. You can grant read-only access such as POST /query to check transaction status while withholding money-moving calls, or allow POST /request and POST /capture without exposing POST /refund and POST /void. Only the operations you explicitly add are available to the agent, and your server key is injected at execution time rather than shared with it.