# Fawaterak API

> API v2 reference — For the previous v2 documentation, see fawaterak-api.readme.io/reference/overview.

JSON over HTTPS. Merchant API responses use `{ status, message, data }`.
Authenticate `/api/v3/*` with OAuth 2.0 client credentials (`POST /oauth/token`).
Browser iframe checkout uses a domain hash (`FAWATERAK-HASH-KEY` + `FAWATERAK-DOMAIN`).
Confirm paid status from webhooks, not only from customer redirects.

Base URLs:
- https://staging.fawaterk.com — Application Staging base URL
- https://app.fawaterk.com — Application Live base URL

## API description

- [OpenAPI document](https://staging.fawaterk.com/documentation/api/openapi.json): Complete OpenAPI 3.1 description of every endpoint, schema, and example
- [API reference](https://staging.fawaterk.com/documentation): Human-readable Scalar reference
- [Full Markdown](https://staging.fawaterk.com/documentation/llms-full.txt): Concatenated Markdown of tags and operations

## Overview

- [Get started](https://staging.fawaterk.com/documentation#tag/Get-started): To get started you need to create a business account from here appUrl/regsiter.
- [Auth token](https://staging.fawaterk.com/documentation#tag/Auth-token): Obtain and renew Bearer access tokens for `/api/v3/*` OAuth-protected endpoints (transactions, refunds, e-invoicing).
- [POST /oauth/token — Obtain access token (client credentials)](https://staging.fawaterk.com/documentation#tag/Auth-token/POST/oauth/token): Exchange the client ID and client secret (vendor dashboard → Integrations → OAuth client credentials) for a Bearer access token used on `/a…
- [POST /oauth/token#refresh — Refresh access token](https://staging.fawaterk.com/documentation#tag/Auth-token/POST/oauth/token#refresh): Exchange a valid refresh token (from a previous `client_credentials` token response) for a new Bearer access token.

## Payment transactions

- [Transactions overview](https://staging.fawaterk.com/documentation#tag/Transactions-overview): Transactions let you process a single one-time payment with a clear lifecycle status: success, fail, or pending.
- [API integration](https://staging.fawaterk.com/documentation#tag/API-integration): This is server to server APIs integtatoins enables you to list active payment methods / create trasaction link / get transaction data.
- [GET /api/v3/getTrPaymentmethods — List payment methods](https://staging.fawaterk.com/documentation#tag/API-integration/GET/api/v3/getTrPaymentmethods): Returns integration-enabled payment methods for the vendor linked to the OAuth client.
- [POST /api/v3/createTransaction — Create transaction](https://staging.fawaterk.com/documentation#tag/API-integration/POST/api/v3/createTransaction): Transaction types:
- Hosted checkout: do not send `payment_method_id`. This creates a transaction link and returns a hosted checkout URL in…
- [POST /api/v3/getTransactionData — Get transaction data](https://staging.fawaterk.com/documentation#tag/API-integration/POST/api/v3/getTransactionData): Returns the current TR transaction details for the vendor linked to the OAuth client using `intent_key`.
- [GET /api/v3/getTransactionsData — List transactions](https://staging.fawaterk.com/documentation#tag/API-integration/GET/api/v3/getTransactionsData): Date-range paginated export of persisted TR rows.
- [Iframe integration](https://staging.fawaterk.com/documentation#tag/Iframe-integration): Embed Fawaterak checkout on your website with fawaterkPlugin.js (`/fawaterkPlugin/fawaterkPlugin.js`).
- [Tokenization and recurring](https://staging.fawaterk.com/documentation#tag/Tokenization-and-recurring): Tokenization allows you to store card payment details in exchange for a token.
- [POST /api/v2/createCardTokenScreen — Create card data screen](https://staging.fawaterk.com/documentation#tag/Tokenization-and-recurring/POST/api/v2/createCardTokenScreen): Generates a Fawaterak-hosted URL containing the collect-card-data form.
- [POST /api/v2/createTokenizationPayRequest — Pay with tokenization](https://staging.fawaterk.com/documentation#tag/Tokenization-and-recurring/POST/api/v2/createTokenizationPayRequest): Processes a saved-card payment when `tokenAction: "tokenization"` is present.
- [POST /api/v2/createTokenizationPayRequest#recurring — Pay with recurring](https://staging.fawaterk.com/documentation#tag/Tokenization-and-recurring/POST/api/v2/createTokenizationPayRequest#recurring): Processes a recurring saved-card payment when `tokenAction` is not sent.
- [POST /api/v2/deleteCustomerToken — Delete customer token](https://staging.fawaterk.com/documentation#tag/Tokenization-and-recurring/POST/api/v2/deleteCustomerToken): Deletes a saved customer card token.
- [Webhooks](https://staging.fawaterk.com/documentation#tag/Webhooks): Fawaterak sends server-to-server POST notifications to your endpoints.
- [POST /webhooks/fawaterak/paid — Paid / pending payment webhook](https://staging.fawaterk.com/documentation#tag/Webhooks/POST/webhooks/fawaterak/paid): Fawaterak POSTs to your webhook URL when a payment completes or is pending (async methods such as Fawry, Aman, Masary).
- [POST /webhooks/fawaterak/failed — Failed payment webhook](https://staging.fawaterk.com/documentation#tag/Webhooks/POST/webhooks/fawaterak/failed): Fawaterak POSTs to your Failed webhook URL when a payment attempt fails (e.g.
- [POST /webhooks/fawaterak/cancel — Cancel / expired reference webhook](https://staging.fawaterk.com/documentation#tag/Webhooks/POST/webhooks/fawaterak/cancel): Fawaterak POSTs to your Cancellation webhook when a payment reference expires or is canceled (Aman, Masary, Meeza, and similar async refere…
- [POST /webhooks/fawaterak/refund — Refund webhook](https://staging.fawaterk.com/documentation#tag/Webhooks/POST/webhooks/fawaterak/refund): Fawaterak POSTs to your Refund webhook when a refund request is approved.
- [E-Commerce Plugins](https://staging.fawaterk.com/documentation#tag/E-Commerce-Plugins): We provide multiple ready-made plugins to accept Fawaterak payments on popular e-commerce platforms.

## Payment links

- [Overview](https://staging.fawaterk.com/documentation#tag/Overview): E-invoicing lets you create an invoice and share it with your customers via email, SMS, or manually (copy the payment link).
- [E-invoicing](https://staging.fawaterk.com/documentation#tag/E-invoicing): Create and manage e-invoices via OAuth client credentials.
- [POST /api/v3/createEinvoice — Create e-invoice](https://staging.fawaterk.com/documentation#tag/E-invoicing/POST/api/v3/createEinvoice): Creates a new e-invoice in the `invoices` table with `create_source = API.v3.EI.IN` and returns a hosted payment link.
- [POST /api/v3/invoice/index — List e-invoices](https://staging.fawaterk.com/documentation#tag/E-invoicing/POST/api/v3/invoice/index): Paginated list of e-invoices created via this API (`create_source = API.v3.EI.IN`) for the authenticated vendor.
- [POST /api/v3/invoice/get — Get e-invoice](https://staging.fawaterk.com/documentation#tag/E-invoicing/POST/api/v3/invoice/get): Returns full details for a single e-invoice owned by the authenticated vendor.
- [POST /api/v3/invoice/update — Update e-invoice](https://staging.fawaterk.com/documentation#tag/E-invoicing/POST/api/v3/invoice/update): Updates an existing e-invoice.
- [POST /api/v3/invoice/delete — Delete e-invoice](https://staging.fawaterk.com/documentation#tag/E-invoicing/POST/api/v3/invoice/delete): Soft-deletes an unpaid e-invoice after verifying no active payment references block deletion.

## Mobile integrations

- [Mobile integrations](https://staging.fawaterk.com/documentation#tag/Mobile-integrations): Easy integration with your mobile app (React Native, Flutter, Kotlin, Java, Swift) using API v3 and TR (cache-based transactions).
- [Mobile — List payment methods](https://staging.fawaterk.com/documentation#tag/Mobile-%E2%80%94-List-payment-methods): Step 1 — Retrieve payment methods assigned to your vendor account.
- [GET /api/v3/getTrPaymentmethods — List payment methods](https://staging.fawaterk.com/documentation#tag/Mobile-%E2%80%94-List-payment-methods/GET/api/v3/getTrPaymentmethods): Returns integration-enabled payment methods for the vendor linked to the OAuth client.
- [Mobile — Process transaction](https://staging.fawaterk.com/documentation#tag/Mobile-%E2%80%94-Process-transaction): Step 2 — Create a TR transaction and initiate payment on the selected method.
- [POST /api/v3/createTransaction — Create transaction](https://staging.fawaterk.com/documentation#tag/Mobile-%E2%80%94-Process-transaction/POST/api/v3/createTransaction): Transaction types:
- Hosted checkout: do not send `payment_method_id`. This creates a transaction link and returns a hosted checkout URL in…

## Refund APIs

- [Refund APIs](https://staging.fawaterk.com/documentation#tag/Refund-APIs): Manage refund requests for paid transactions via OAuth client credentials.
- [POST /api/v3/refund/index — List refund requests](https://staging.fawaterk.com/documentation#tag/Refund-APIs/POST/api/v3/refund/index): Returns a paginated list of refund requests for the vendor linked to the OAuth client (10 per page).
- [GET /api/v3/refund/details/{id} — Get refund request details](https://staging.fawaterk.com/documentation#tag/Refund-APIs/GET/api/v3/refund/details/{id}): Get refund request details
- [POST /api/v3/refund/refundTypes — List refund types](https://staging.fawaterk.com/documentation#tag/Refund-APIs/POST/api/v3/refund/refundTypes): Returns refund type keys used as `refund_type` when creating a refund.
- [POST /api/v3/refund/refundReasons — List refund reasons](https://staging.fawaterk.com/documentation#tag/Refund-APIs/POST/api/v3/refund/refundReasons): Returns allowed refund reason strings.
- [POST /api/v3/refund/create — Create refund request](https://staging.fawaterk.com/documentation#tag/Refund-APIs/POST/api/v3/refund/create): Submit a refund for a paid transaction.
- [POST /api/v3/refund/delete — Delete (cancel) refund request](https://staging.fawaterk.com/documentation#tag/Refund-APIs/POST/api/v3/refund/delete): Deletes a pending refund request.

## Payment operations

- [Payment operations](https://staging.fawaterk.com/documentation#tag/Payment-operations): Capture or void card payments (auth-and-capture) via OAuth client credentials.
- [POST /api/v3/payment/capture — Capture authorized payment](https://staging.fawaterk.com/documentation#tag/Payment-operations/POST/api/v3/payment/capture): Capture (settle) an authorized card hold.
- [POST /api/v3/payment/void — Void authorized payment](https://staging.fawaterk.com/documentation#tag/Payment-operations/POST/api/v3/payment/void): Void an authorized (waiting-capture) hold.

## References

- [Test cards](https://staging.fawaterk.com/documentation#tag/Test-cards): Use these sandbox / test card numbers when testing Mastercard, Visa, and Meeza flows on staging or in test mode.