Payments

Create a payment

POST /v1/payments

Creates a payment to be paid on the hosted page (POST /v1/payments/{id}/checkout-link) or on your own page (client secret). The same Idempotency-Key with the same body answers the first result again (header Idempotency-Replayed: true); with another body it is refused.

Permission: payments:write

curl -X POST https://api.sw-staging.dev/v1/payments \
  -H "Authorization: Bearer sw_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"currency":"SAR"}'

Parameters

Field	Type	Required	Description
`Idempotency-Key`	string (header)	yes	A unique key per operation (1-255 visible ASCII characters). Retrying with the same key and body answers the first result.. at most 255 characters

Request body

Field	Type	Required	Description
`amount`	number	yes	In the minor unit of the currency (1050 = 10.50 SAR)
`capture_method`	`automatic`, `manual`	no	Only 'automatic' today (authorize and capture at once). default "automatic"
`currency`	string	yes	ISO 4217 currency code, upper case. pattern `^[A-Z]{3}$`
`customer_reference`	string	no	at most 255 characters
`description`	string	no	at most 1000 characters
`expires_in_seconds`	integer	no	How long the payment can be paid. default 86400. min 300. max 604800
`merchant_reference`	string	no	Your order number; searchable with GET /v1/payments. at most 255 characters
`metadata`	object	no	Your own key-value data, returned as sent (at most 8 KB as JSON). default {}

201 — The payment

Field	Type	Description
`amount`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_authorized`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_captured`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_refunded`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`capture_method`	`automatic`, `manual`
`created_at`	string (date-time)
`currency`	string	ISO 4217 currency code, upper case. pattern `^[A-Z]{3}$`
`customer_reference`	string or null
`description`	string or null
`environment`	`test`, `live`
`expires_at`	string (date-time) or null
`id`	string	pattern `^pay_[0-9A-HJKMNP-TV-Z]{26}$`
`merchant_reference`	string or null
`metadata`	object	Your own key-value data, returned as sent (at most 8 KB as JSON)
`status`	`CREATED`, `REQUIRES_PAYMENT_METHOD`, `REQUIRES_ACTION`, `PROCESSING`, `AUTHORIZED`, `CAPTURED`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED`, `PARTIALLY_REFUNDED`, `REFUNDED`

Errors answer with the error object.

List payments

GET /v1/payments

Newest first. Page with starting_after (the last id of the previous page).

Permission: payments:read

curl -X GET https://api.sw-staging.dev/v1/payments \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`limit`	integer (query)	no	default 20. min 1. max 100
`starting_after`	string (query)	no	The last id of the previous page. pattern `^pay_[0-9A-HJKMNP-TV-Z]{26}$`
`status`	`CREATED`, `REQUIRES_PAYMENT_METHOD`, `REQUIRES_ACTION`, `PROCESSING`, `AUTHORIZED`, `CAPTURED`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED`, `PARTIALLY_REFUNDED`, `REFUNDED` (query)	no
`merchant_reference`	string (query)	no	at most 255 characters

200 — A page of payments

Field	Type	Description
`data`	array of object
`data[].amount`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`data[].amount_authorized`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`data[].amount_captured`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`data[].amount_refunded`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`data[].capture_method`	`automatic`, `manual`
`data[].created_at`	string (date-time)
`data[].currency`	string	ISO 4217 currency code, upper case. pattern `^[A-Z]{3}$`
`data[].customer_reference`	string or null
`data[].description`	string or null
`data[].environment`	`test`, `live`
`data[].expires_at`	string (date-time) or null
`data[].id`	string	pattern `^pay_[0-9A-HJKMNP-TV-Z]{26}$`
`data[].merchant_reference`	string or null
`data[].metadata`	object	Your own key-value data, returned as sent (at most 8 KB as JSON)
`data[].status`	`CREATED`, `REQUIRES_PAYMENT_METHOD`, `REQUIRES_ACTION`, `PROCESSING`, `AUTHORIZED`, `CAPTURED`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED`, `PARTIALLY_REFUNDED`, `REFUNDED`

Errors answer with the error object.

Retrieve a payment

GET /v1/payments/{id}

Permission: payments:read

curl -X GET https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The payment id (pay_…)

200 — The payment

Field	Type	Description
`amount`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_authorized`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_captured`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_refunded`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`capture_method`	`automatic`, `manual`
`created_at`	string (date-time)
`currency`	string	ISO 4217 currency code, upper case. pattern `^[A-Z]{3}$`
`customer_reference`	string or null
`description`	string or null
`environment`	`test`, `live`
`expires_at`	string (date-time) or null
`id`	string	pattern `^pay_[0-9A-HJKMNP-TV-Z]{26}$`
`merchant_reference`	string or null
`metadata`	object	Your own key-value data, returned as sent (at most 8 KB as JSON)
`status`	`CREATED`, `REQUIRES_PAYMENT_METHOD`, `REQUIRES_ACTION`, `PROCESSING`, `AUTHORIZED`, `CAPTURED`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED`, `PARTIALLY_REFUNDED`, `REFUNDED`

Errors answer with the error object.

A payment's history

GET /v1/payments/{id}/events

Every state change of the payment, oldest first.

Permission: payments:read

curl -X GET https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/events \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The payment id (pay_…)

200 — The events

Field	Type	Description
`data`	array of object
`data[].data`	object
`data[].occurred_at`	string (date-time)
`data[].type`	string

Errors answer with the error object.

Cancel an unpaid payment

POST /v1/payments/{id}/cancel

Only a payment nobody has started paying can be canceled.

Permission: payments:write

curl -X POST https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/cancel \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The payment id (pay_…)

200 — The canceled payment

Field	Type	Description
`amount`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_authorized`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_captured`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`amount_refunded`	integer	Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR)
`capture_method`	`automatic`, `manual`
`created_at`	string (date-time)
`currency`	string	ISO 4217 currency code, upper case. pattern `^[A-Z]{3}$`
`customer_reference`	string or null
`description`	string or null
`environment`	`test`, `live`
`expires_at`	string (date-time) or null
`id`	string	pattern `^pay_[0-9A-HJKMNP-TV-Z]{26}$`
`merchant_reference`	string or null
`metadata`	object	Your own key-value data, returned as sent (at most 8 KB as JSON)
`status`	`CREATED`, `REQUIRES_PAYMENT_METHOD`, `REQUIRES_ACTION`, `PROCESSING`, `AUTHORIZED`, `CAPTURED`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED`, `PARTIALLY_REFUNDED`, `REFUNDED`

Errors answer with the error object.

A hosted payment page for the payment

POST /v1/payments/{id}/checkout-link

Redirect the customer to the returned url. After paying they return to return_url; confirm the result from your server (GET the payment, or a webhook), never from the return alone.

Permission: payments:write

curl -X POST https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/checkout-link \
  -H "Authorization: Bearer sw_test_…" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"string"}'

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The payment id (pay_…)

Request body

Field	Type	Required	Description
`return_url`	string	yes	Where the customer returns after paying. at most 2048 characters

201 — The link

Field	Type	Description
`expires_at`	string (date-time) or null
`id`	string
`url`	string	Send the customer here (the hosted payment page)

Errors answer with the error object.

A client secret for your own checkout page

POST /v1/payments/{id}/client-secret

For a checkout page you host: the browser uses the secret, never your API key. Ask for it from your server.

Permission: payments:write

curl -X POST https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/client-secret \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The payment id (pay_…)

Request body (optional)

Field	Type	Required	Description
`return_url`	string	no	Where the customer returns; its origin must be one of your registered origins. at most 2048 characters

201 — The secret

Field	Type	Description
`client_secret`	string	For your own checkout page in the browser; never log it
`expires_at`	string (date-time)

Errors answer with the error object.

Create a paymentCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

201 — The paymentCopy Anchor Link

List paymentsCopy Anchor Link

ParametersCopy Anchor Link

200 — A page of paymentsCopy Anchor Link

Retrieve a paymentCopy Anchor Link

ParametersCopy Anchor Link

200 — The paymentCopy Anchor Link

A payment's historyCopy Anchor Link

ParametersCopy Anchor Link

200 — The eventsCopy Anchor Link

Cancel an unpaid paymentCopy Anchor Link

ParametersCopy Anchor Link

200 — The canceled paymentCopy Anchor Link

A hosted payment page for the paymentCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

201 — The linkCopy Anchor Link

A client secret for your own checkout pageCopy Anchor Link

ParametersCopy Anchor Link

Request body (optional)Copy Anchor Link

201 — The secretCopy Anchor Link

On this page

Create a payment

Parameters

Request body

201 — The payment

List payments

Parameters

200 — A page of payments

Retrieve a payment

Parameters

200 — The payment

A payment's history

Parameters

200 — The events

Cancel an unpaid payment

Parameters

200 — The canceled payment

A hosted payment page for the payment

Parameters

Request body

201 — The link

A client secret for your own checkout page

Parameters

Request body (optional)

201 — The secret