API Reference Overview

The Amwal REST API empowers developers to create installment links, test sandbox transactions, and retrieve real-time payment data for both Online Checkout and In-Store POS integrations.

Authorization

Retrieve your secret API key and merchant public key from the Merchant Dashboard under Integrations → API Keys, then include both in the request headers for every request.

Base URL: https://backend.sa.amwal.tech

Pass your merchant public key in the required X-Amwal-Key header:

Sandbox: X-Amwal-Key: sandbox-amwal-xxx
Production: X-Amwal-Key: prod-amwal-xxx

Request Headers

Authorization: your_secret_key_here
X-Amwal-Key: sandbox-amwal-xxx
Content-Type: application/json

Header	Type	Required	Description
`Authorization`	String	Yes	Your confidential Amwal Secret Key (e.g. `<YOUR_SECRET_KEY_UUID>`).
`X-Amwal-Key`	String	Yes	Merchant Public Key (`sandbox-amwal-xxx` in Sandbox, `prod-amwal-xxx` in Production).
`Content-Type`	String	Yes	Must be set to `application/json` for requests with a body.

Response Status Codes

Status Code	Description
`200`	The request succeeded.
`400`	Invalid input parameters or payload validation failure.
`401`	Authentication failed. Check your API key.
`404`	Resource not found or invalid URL path.

Interactive Testing & Checkout Flows

High-Level Architecture

Explore Amwal's multi-tier system architecture, core engine services, SAMA compliance, and banking networks.

API Playground

Run live and simulated cURL requests, import commands, and generate multi-language client code.

Online Checkout Flow

Create installment links for web-based e-commerce transactions and reconcile via callbacks and webhooks.

In-Store Checkout (POS)

Create installment links for in-store physical retail transactions with cashier terminals and dynamic QR codes.