Sandbox

Testing & Sandbox

Everything you need to test your Mazad Wallet integration without using real money. The sandbox environment mirrors production behavior with predictable test data.

Getting sandbox access

Follow these steps to get started with the sandbox environment.

Contact Sales

Reach out to our team to register your merchant account and receive sandbox credentials.

Get your API keys

You will receive a sandbox API key starting with sk_sandbox_ and a merchant ID.

Set the base URL

Point all API calls to https://wallet.e-mazad.store/api/v1 for sandbox testing.

Use test users

The sandbox comes pre-loaded with test users and balances (see below).

Sandbox behavior

The sandbox environment is designed to behave identically to production with a few key differences for testing convenience.

Fixed FX Rates

Exchange rates are fixed and do not fluctuate, making test results predictable and reproducible.

Pre-loaded Balances

Test users come with pre-loaded wallet balances. Balances reset daily at midnight UTC.

No Real Money

No actual funds are moved. All transactions are simulated in an isolated environment.

Instant Processing

Payroll batches and subscription charges process instantly instead of asynchronously.

Webhook Delivery

Webhooks are delivered to your configured URL just like production, with test payloads.

Rate Limits Relaxed

Sandbox has higher rate limits (1000 req/min vs 100 req/min in production).

Test users

The sandbox comes with pre-configured test users. Use their IDs in API calls just like real customer IDs.

Customer ID	Balance	Description
test_buyer_rich	10,000,000 IQD	Pre-loaded buyer with high balance. Use for successful payment flows.
test_buyer_broke	0 IQD	Buyer with zero balance. Use to test insufficient funds errors.
test_buyer_usd	5,000 USD	Buyer with USD balance only. Use for multi-currency and FX flows.
test_seller	500,000 IQD	Seller/merchant account. Use as the receiving end for payments.

Daily balance reset

Test user balances are reset to their default values every day at midnight UTC. If you need a persistent balance for multi-day testing, contact support.

Test PIN and OTP

In the sandbox environment, all PIN and OTP verification use the same fixed values.

Verification type	Value	Notes
Wallet PIN	000000	6-digit PIN for checkout popup authorization
SMS OTP	000000	6-digit OTP for phone verification
Email OTP	000000	6-digit OTP for email verification
Transaction PIN	000000	6-digit PIN for high-value transfer confirmation

Sandbox only

The universal 000000 PIN/OTP only works in the sandbox environment. In production, real PINs and OTPs are required.

Integration test scenarios

Before going live, make sure your integration handles all of these scenarios correctly.

Create a payment and verify the checkout popup flow end-to-end

Process a refund and confirm the buyer wallet is credited

Create a hold, then capture partial and release the remainder

Subscribe a user to a plan and verify the first charge

Simulate a failed payment and verify the subscription enters past_due

Pause and resume a subscription, confirming billing date recalculation

Submit a payroll batch and track per-recipient completion

Execute an FX conversion and verify both currency balances update

Generate a QR code payment and complete it with the test buyer

Test webhook delivery by triggering each event type in sequence

Simulating edge cases

Use special sandbox headers to simulate failure scenarios and edge cases that are hard to reproduce naturally.

Header	Value	Effect
X-Sandbox-Fast-Expire	true	Makes payment links, QR codes, and checkout sessions expire in 30 seconds instead of the default timeout. Use to test expiry handling.
X-Sandbox-Force-Fail-Recipient	customer_id	Forces a specific recipient to fail in a payroll batch. Set the value to the customer_id that should fail. The failure reason will be `wallet_suspended`.
X-Sandbox-Force-Decline	true	Forces the next payment or subscription charge to be declined, even if the wallet has sufficient funds.
X-Sandbox-Slow-Response	5000	Adds an artificial delay (in milliseconds) to the API response. Use to test timeout handling.
X-Sandbox-Webhook-Delay	10000	Delays webhook delivery by the specified milliseconds. Use to test your app's behavior when webhooks arrive late.

# Create a payment link that expires in 30 seconds
curl -X POST https://wallet.e-mazad.store/api/v1/gateway/payment-links \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -H "X-Sandbox-Fast-Expire: true" \
  -d '{
    "amount": 25000,
    "currency": "IQD",
    "description": "Test expiry flow"
  }'

Headers are sandbox-only

These X-Sandbox-* headers are silently ignored in production. You do not need to strip them from your code before going live, but it is good practice to only include them in your test environment configuration.

Ready to integrate Mazad into your platform?

Our team will review your business and issue your production API keys within 2 business days.

Contact Sales Create Sandbox Account

Wallets FX API Reference