Payment Gateway

Refunds

Refund completed payments — fully or partially. Refunds are processed instantly to the user wallet. Understand how Mazad commission is handled on refunds.

Create a refund

POST/gateway/payments/{payment_id}/refund

Refund a completed payment. Supports full and partial refunds. Funds are returned to the customer wallet instantly. Commission is not refunded.

Path Parameters

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

Request Body

Name	Type	Required	Description
amount	integer	optional	Amount to refund in smallest currency unit. Defaults to full remaining capturable amount. Must be <= (captured_amount - refunded_amount).
reason	string	required	Reason for the refund. Shown to user and stored for records. Max 256 characters.
metadata	object	optional	Additional metadata for the refund event.

Full refund

curl -X POST https://wallet.e-mazad.store/api/v1/gateway/payments/pay_x1y2z3/refund \
  -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": "Customer requested return - item defective"
  }'

Partial refund

# Refund 10,000 IQD of a 25,000 IQD payment
curl -X POST https://wallet.e-mazad.store/api/v1/gateway/payments/pay_x1y2z3/refund \
  -H "X-Api-Key: mk_your_key_id"   -H "X-Api-Timestamp: $TIMESTAMP"   -H "X-Api-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "reason": "Partial return - 2 of 5 items returned",
    "metadata": {
      "items_returned": 2,
      "return_id": "ret_456"
    }
  }'

Refund response

{
  "success": true,
  "data": {
    "id": "pay_x1y2z3",
    "status": "partially_refunded",
    "amount": 25000,
    "currency": "IQD",
    "captured_amount": 25000,
    "refunded_amount": 10000,
    "net_amount": 15000,
    "refund": {
      "id": "rfn_m1n2o3p4",
      "amount": 10000,
      "reason": "Partial return - 2 of 5 items returned",
      "status": "completed",
      "created_at": "2026-03-22T11:00:00Z"
    },
    "refunds": [
      {
        "id": "rfn_m1n2o3p4",
        "amount": 10000,
        "reason": "Partial return - 2 of 5 items returned",
        "status": "completed",
        "created_at": "2026-03-22T11:00:00Z"
      }
    ],
    "created_at": "2026-03-20T14:30:00Z",
    "updated_at": "2026-03-22T11:00:00Z"
  }
}

Commission on refunds

Mazad charges a processing commission on each payment. Here is how commission is handled during refunds:

Full refund

The original Mazad commission is returned in full to the merchant. You are not charged for refunded transactions.

Partial refund

Commission is recalculated based on the remaining (non-refunded) amount. The excess commission is credited back to the merchant.

Refund window

Refunds can be issued up to 90 days after the payment was captured. After 90 days, the refund endpoint returns a 422 error.

FX refunds

If the original payment involved currency conversion, the refund is processed at the original locked FX rate. The user receives the exact source amount that was debited, regardless of current market rates.

Capture & Void Payment Links