Charges

Overview

A charge represents a single payment transaction. Paygate automatically routes charges to the correct provider based on the payment_method field.

Payment method	Provider	Supported networks
`card`	Stripe	Visa, Mastercard
`apple_pay`	Stripe	Apple Pay
`mada`	Checkout.com	Mada (Saudi debit)

Charge states

PENDING → AUTHORIZED → CAPTURED → REFUNDED
        ↘ FAILED      ↘ VOIDED

Charges are created as pending, move to authorized once the provider approves, then auto-advance to captured. Invalid state transitions return 422 Unprocessable Content.

Create a charge

POST /v1/charges
Authorization: Bearer sk_test_...
Idempotency-Key: <unique_key>
Content-Type: application/json

{
  "amount": 5000,
  "currency": "SAR",
  "payment_method": "card",
  "token": "tok_visa",
  "metadata": {
    "order_id": "1042",
    "customer_id": "cust_99"
  }
}

The Idempotency-Key header is required. Replaying a request with the same key within 24 hours returns the original response — no duplicate charge is created.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 5000,
  "currency": "SAR",
  "status": "captured",
  "payment_method": "card",
  "provider": "stripe",
  "provider_charge_id": "ch_3O...",
  "idempotency_key": "order-9f3a1b",
  "metadata": { "order_id": "1042" },
  "environment": "sandbox",
  "merchant_id": "...",
  "captured_at": "2024-01-15T10:30:01.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:01.200Z"
}

Retrieve a charge

GET /v1/charges/:id
Authorization: Bearer sk_test_...

List charges

GET /v1/charges
Authorization: Bearer sk_test_...

Filters

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `captured`, `failed`, etc.
`payment_method`	string	Filter by method: `card`, `mada`, `apple_pay`
`from`	ISO 8601	Start of date range
`to`	ISO 8601	End of date range
`from` + `to` together	Both required to apply date range filter

Every mutating request should include an Idempotency-Key header — typically a UUID or your internal order ID. If Paygate receives a duplicate key within 24 hours, it returns the cached response without calling the provider again.

Idempotency-Key: order-9f3a1b-attempt-1

If the original request is still in-flight, the duplicate returns 409 Conflict.

Amounts and currencies

Amounts are in the smallest currency unit (halalas for SAR, cents for USD). 5000 SAR = 50.00 SAR.

Supported currencies: SAR, USD, AED, KWD, BHD, QAR, OMR.

On this page