Quickstart

Go from zero to your first payment in under 10 minutes. This guide walks you through a complete checkout flow using the Mazad sandbox.

1Create a Sandbox Account

sk_sandbox_* — Secret key (server-side only)
pk_sandbox_* — Publishable key (safe for the browser)

Sandbox money is free

Every sandbox merchant starts with 10,000,000 IQD of test funds. You can reset your balance at any time from the dashboard.

2Sync a Test User

Before you can charge a user, Mazad needs to know about them. Call the sync endpoint to register or update a user. A wallet is created automatically on first sync.

POST/api/v1/users/sync

Create or update a user and auto-provision their wallet.

Request Body

Name	Type	Required	Description
external_user_id	string	required	Your unique identifier for this user.
name	string	required	Full name of the user.
email	string	optional	Email address.
phone	string	optional	Phone number in E.164 format.

curl -X POST https://wallet.e-mazad.store/api/v1/users/sync \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "usr_buyer_001",
    "name": "Ahmed Al-Bayati",
    "email": "ahmed@example.com",
    "phone": "+9647701234567"
  }'

3Create a Checkout Session

A checkout session represents a single payment attempt. Mazad returns acheckout_urlthat you open in a popup or redirect the buyer to.

POST/api/v1/checkout/sessions

Create a new checkout session for the given amount.

Request Body

Name	Type	Required	Description
external_user_id	string	required	The buyer who will pay.
amount	integer	required	Amount in the smallest currency unit (e.g., IQD fils).
currency	string	required	ISO 4217 currency code, e.g. IQD.
description	string	optional	Human-readable description shown to the buyer.
success_url	string	required	Redirect URL after successful payment.
cancel_url	string	required	Redirect URL if the buyer cancels.
metadata	object	optional	Arbitrary key-value pairs attached to the session.

curl -X POST https://wallet.e-mazad.store/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_user_id": "usr_buyer_001",
    "amount": 45000,
    "currency": "IQD",
    "description": "Order #1042 — Antique Vase",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "metadata": { "order_id": "1042" }
  }'

4Open the Payment Popup

Use the checkout_url returned in Step 3 to open the Mazad payment UI. You can redirect or open it in a popup window.

# Not applicable — this step runs in the browser.
# Use the HTML/JS snippet from the JavaScript tab.

5Poll for Payment Status

After the buyer completes (or cancels) the checkout, retrieve the session to check its status. In production you should rely on webhooks, but polling works great for getting started.

GET/api/v1/checkout/sessions/:session_id

Retrieve the current status of a checkout session.

curl https://wallet.e-mazad.store/api/v1/checkout/sessions/cs_test_9f8a7b6c5d4e \
  -H "Authorization: Bearer sk_sandbox_abc123"

# Response:
# {
#   "id": "cs_test_9f8a7b6c5d4e",
#   "status": "authorized",
#   "amount": 45000,
#   "currency": "IQD",
#   "payment_id": "pay_test_a1b2c3d4e5f6",
#   ...
# }

Use webhooks in production

Polling is fine for testing, but in production you should configure a webhook endpoint to receive real-time checkout.authorized events.

6Capture the Payment

Once the session status is authorized, capture the payment to move funds from the buyer's hold into your merchant balance. You can capture the full amount or a partial amount.

POST/api/v1/payments/:payment_id/capture

Capture an authorized payment (full or partial).

Request Body

Name	Type	Required	Description
amount	integer	optional	Amount to capture. Omit to capture the full authorized amount.

curl -X POST https://wallet.e-mazad.store/api/v1/payments/pay_test_a1b2c3d4e5f6/capture \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 45000 }'

# Response:
# {
#   "id": "pay_test_a1b2c3d4e5f6",
#   "status": "captured",
#   "captured_amount": 45000,
#   "currency": "IQD"
# }

You just processed your first payment!

The 45,000 IQD has moved from the buyer's wallet into your merchant balance. From here you can:

Issue a refund via POST /payments/:id/refund
Set up webhooks to listen for real-time events
Explore embedded wallets to hold, release, and transfer funds

Overview Authentication