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

# MyFatoorah Payment API

Jentic publishes the only available OpenAPI specification for MyFatoorah Payment API, keeping it validated and agent-ready. MyFatoorah is a payment gateway covering the Middle East and North Africa, supporting cards, KNET, mada, BENEFIT, and a range of regional wallets. The API enables initiating a payment session, executing direct card payments, sending payment links via email and SMS, polling payment status, and processing refunds. Both a sandbox host (apitest.myfatoorah.com) and a production host (api.myfatoorah.com) are available, authenticated with a bearer token in the Authorization header.

## For AI agents

Initiate, execute, and refund payments across MENA payment methods using a MyFatoorah bearer token, with sandbox and production environments.

## Scope

Does not handle subscription billing, payouts to external bank accounts, or in-person POS terminals - use for one-off MENA online payments and refunds only.

## Capabilities

- Initiate a payment session and retrieve the available regional payment methods for the merchant account
- Execute a direct charge against a chosen payment method ID and amount
- Send a hosted payment link to a customer by email or SMS for asynchronous collection
- Poll the status of a transaction by InvoiceId or payment reference to confirm settlement
- Process full or partial refunds against a settled MyFatoorah invoice

## Use cases

### MENA E-Commerce Checkout

Accept online payments in MENA currencies including KWD, SAR, AED, BHD, OMR, and QAR through cards, KNET, mada, and BENEFIT. The integration calls `/v2/InitiatePayment` to surface available methods and `/v2/ExecutePayment` to capture funds. MyFatoorah handles 3D Secure and regional scheme routing so a single integration covers most Gulf payment rails.

Example prompt: Call POST `/v2/InitiatePayment` for a 25.000 KWD order, then call POST `/v2/ExecutePayment` with the chosen PaymentMethodId and customer card details to capture the charge.

### Send Payment Link by SMS or Email

Collect payments asynchronously by sending a hosted MyFatoorah payment link via SMS or email. The integration calls `/v2/SendPayment` with customer contact details and the invoice value, and MyFatoorah delivers the link and a return URL for completion. This suits invoicing, deposits, and remote sales where the customer is not on a checkout page.

Example prompt: Call POST `/v2/SendPayment` with the customer's phone number, an InvoiceValue of 50 SAR, and a CallBackUrl, and return the generated payment link.

### Refund Reconciliation Workflow

Issue full or partial refunds against MyFatoorah invoices when customers cancel or return goods. The integration calls `/v2/MakeRefund` with the InvoiceId and refund amount and writes the result back to the order management system. `/v2/GetPaymentStatus` is used to confirm the original transaction is in a refundable state before issuing.

Example prompt: Call POST `/v2/GetPaymentStatus` to confirm the invoice is paid, then call POST `/v2/MakeRefund` with the InvoiceId and the refund amount.

### AI Agent Payment Assistant

An AI agent operating a MENA storefront takes a natural-language order, searches Jentic for MyFatoorah payment operations, loads the InitiatePayment and ExecutePayment schemas, and chains them into a single charge. Jentic isolates the bearer token so the agent never holds the secret. This compresses MyFatoorah onboarding from days of bearer auth and webhook plumbing to a single intent search.

Example prompt: Search Jentic for 'process a MyFatoorah payment', load POST `/v2/InitiatePayment` and POST `/v2/ExecutePayment`, and charge the customer 100.50 SAR via mada.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/InitiatePayment` | Initiate a payment session and list available methods |
| POST | `/v2/ExecutePayment` | Execute a direct charge against a payment method |
| POST | `/v2/SendPayment` | Send a hosted payment link by SMS or email |
| POST | `/v2/GetPaymentStatus` | Look up transaction status by InvoiceId |
| POST | `/v2/MakeRefund` | Process a full or partial refund |

## Key resources

- **InitiatePayment** — Surface available regional payment methods for an invoice value.
- **ExecutePayment** — Capture a charge against a chosen payment method ID.
- **SendPayment** — Send a hosted payment link to a customer by SMS or email.
- **GetPaymentStatus** — Look up the current status of a transaction by InvoiceId or reference.
- **MakeRefund** — Issue a full or partial refund against a paid invoice.

## Why Jentic

- **Setup:** Wiring the MyFatoorah Payment API by hand means learning its bearer auth, choosing between the apitest and production host, and chaining InitiatePayment into ExecutePayment yourself. Through Jentic you install once, import the MyFatoorah Payment API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Payment targets travel in the request body, so limit the agent to the operations it needs, such as initiating a payment or checking its status. You choose which operations are in scope, so a call like issuing a refund is not included unless you add it.
- **Credential handling:** Your MyFatoorah bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a mena online payment' or 'check payment status', and Jentic returns the matching MyFatoorah operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Tap Payments API** — Tap is another MENA-focused gateway covering KNET, mada, BENEFIT, and cards across the Gulf.
- **PayTabs API** — PayTabs is a regional payment gateway with broad MENA coverage and a similar hosted-page model.
- **Stripe API** — Stripe handles global card processing alongside MyFatoorah's regional MENA coverage.

## FAQ

### Why is there no official OpenAPI spec for MyFatoorah Payment API?

MyFatoorah does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call MyFatoorah Payment API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the MyFatoorah Payment API use?

MyFatoorah uses HTTP bearer authentication - every request must include `Authorization: Bearer {Token}`. Through Jentic, the bearer token sits in the encrypted vault and is injected at execution time, so agent code and prompts never see the raw secret.

### Can I send a payment link by SMS with the MyFatoorah Payment API?

Yes. Call POST `/v2/SendPayment` with the customer's phone number, an InvoiceValue, and a CallBackUrl. MyFatoorah generates a hosted payment URL and delivers it to the customer; the response includes the same link for your records.

### How do I process a refund through Jentic?

Search Jentic for 'refund a MyFatoorah payment', load the POST `/v2/MakeRefund` schema, and execute it with the original InvoiceId and the refund amount. The agent can chain GET payment status before refunding to verify the original charge settled.

### Does the MyFatoorah Payment API have a sandbox?

Yes. The spec defines two servers: apitest.myfatoorah.com for the sandbox and api.myfatoorah.com for production. Develop against the sandbox host, then swap the base URL when going live - all five endpoints behave the same in both environments.

### What payment methods does MyFatoorah cover?

MyFatoorah routes to MENA-specific rails including KNET (Kuwait), mada (Saudi Arabia), BENEFIT (Bahrain), Visa, Mastercard, and Apple Pay. The exact list available to your account is returned by POST `/v2/InitiatePayment` based on the invoice currency and amount.

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

Yes. Because you run Jentic One yourself, your own rules decide which MyFatoorah operations and credentials the agent may use. You can scope the agent to only the calls it needs, such as POST `/v2/InitiatePayment` and POST `/v2/GetPaymentStatus`, while keeping fund-moving operations like POST `/v2/ExecutePayment` or POST `/v2/MakeRefund` out of scope unless you add them. Since payment targets travel in the request body, this operation-level control is how you constrain what the agent can charge or refund.