Payment Gateway
The Payment Gateway manages the lifecycle of every payment: creation, authorization, capture, void, and refund. Understand the state machine to build robust integrations.
Payment state machine
Payment statuses
| Status | Description |
|---|---|
| pending | Session created, user has not yet confirmed. |
| authorized | Funds held in escrow. Awaiting capture (manual mode only). |
| completed | Funds captured and settled to merchant. |
| voided | Authorization released. No funds moved. |
| refunded | Funds returned to user (full or partial). |
| failed | Payment failed (insufficient funds, expired, error). |
Escrow (manual capture)
When you set capture_mode: "manual" on a checkout session, funds are held in escrow after the user confirms.
Use cases
Marketplace escrow (hold until delivery confirmed), service bookings (hold until service rendered), auction payments (hold until auction closes).
Hold duration
Authorized holds expire after 7 days by default. If not captured within this window, the hold is automatically voided and funds are released back to the user.
Partial capture
You can capture less than the authorized amount. The remaining held funds are automatically released.
7-day expiry
Typical timeline
| Event | Timing |
|---|---|
| Session created | T+0 |
| Session expires (if unused) | T+30 min |
| User confirms payment | T+0 to T+30 min |
| Funds debited / held | Instant (< 500ms) |
| Webhook delivered | < 5 seconds |
| Manual capture window | Up to 7 days |
| Auto-void (if not captured) | T+7 days |
| Refund window | Up to 90 days |
Gateway endpoints
Ready to integrate Mazad into your platform?
Our team will review your business and issue your production API keys within 2 business days.