Payment Gateway

Capture & Void

Once a customer completes payment, the payment enters the reserved state — funds are held in escrow. You must explicitly capture (settle) or void (release) them.

Capture a payment

Capture moves funds from escrow to the merchant wallet. You can capture the full authorized amount or a partial amount.

POST/gateway/payments/{payment_id}/capture

Capture a reserved payment. Settles funds from escrow to merchant wallet (minus commission). Triggers payment.completed webhook.

Path Parameters

Name	Type	Required	Description
payment_id	string	required	The payment UUID in reserved status.

Full capture

curl -X POST https://wallet.e-mazad.store/api/v1/gateway/payments/pay_x1y2z3/capture \
  -H "X-Api-Key: mk_your_key_id"   -H "X-Api-Timestamp: $TIMESTAMP"   -H "X-Api-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{}'

Capture response

{
  "success": true,
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "amount": "25.00",
    "currency": "USD",
    "commission_amount": "0.75",
    "net_amount": "24.25",
    "capture_tx_id": "tx_...",
    "created_at": "2026-03-20T14:30:00Z",
    "updated_at": "2026-03-21T09:15:00Z"
  }
}

Commission deducted on capture

The merchant receives net_amount = amount minus the gateway commission. Commission is not refunded if the payment is later refunded. Capture is all-or-nothing — partial captures are not supported.

Void a payment

Void releases all held funds back to the user without settling. Use this when an order is cancelled before fulfillment.

POST/gateway/payments/{payment_id}/void

Void a reserved payment. Releases all held funds back to the customer wallet. Payment status becomes cancelled. Cannot void a completed payment — use refund instead.

Path Parameters

Name	Type	Required	Description
payment_id	string	required	The payment UUID in reserved status.

Request Body

Name	Type	Required	Description
reason	string	optional	Reason for voiding. Stored for audit purposes. Max 256 characters.

curl -X POST https://wallet.e-mazad.store/api/v1/gateway/payments/pay_x1y2z3/void \
  -H "X-Api-Key: mk_your_key_id"   -H "X-Api-Timestamp: $TIMESTAMP"   -H "X-Api-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Order cancelled by customer before shipping"
  }'

Void response

{
  "success": true,
  "data": {
    "id": "pay_x1y2z3",
    "status": "cancelled",
    "amount": 25000,
    "currency": "IQD",
    "captured_amount": 0,
    "refunded_amount": 0,
    "void_reason": "Order cancelled by customer before shipping",
    "authorized_at": "2026-03-20T14:31:00Z",
    "voided_at": "2026-03-20T16:45:00Z",
    "created_at": "2026-03-20T14:30:00Z",
    "updated_at": "2026-03-20T16:45:00Z"
  }
}

Void vs. Refund

Void releases an authorized (held) payment — no money was settled, so there is nothing to return. Refund reverses a captured (completed) payment — money is sent back to the user. Use the correct action based on the payment status.

Payments Refunds