API reference
Refunds
Give money back, fully or in part.
Refund a payment
POST /v1/payments/{id}/refunds
Full or partial, several times up to the captured amount. The answer may be PENDING or PROCESSING: the final result comes as a webhook (refund.succeeded / refund.failed).
Permission: refunds:write
curl -X POST https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/refunds \
-H "Authorization: Bearer sw_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"amount":1000}'Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string (path) | yes | The payment id (pay_…) |
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 | integer | yes | In the minor unit; at most what is left to refund. > 0 |
metadata | object | no | Your own key-value data, returned as sent (at most 8 KB as JSON) |
reason | string | no | at most 500 characters |
200 — The same refund, replayed
| Field | Type | Description |
|---|---|---|
amount | integer | Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR) |
created_at | string (date-time) | |
currency | string | ISO 4217 currency code, upper case. pattern ^[A-Z]{3}$ |
failure_code | string or null | |
failure_message | string or null | |
id | string | |
metadata | object | Your own key-value data, returned as sent (at most 8 KB as JSON) |
object | refund | |
payment_id | string | pattern ^pay_[0-9A-HJKMNP-TV-Z]{26}$ |
reason | string or null | |
status | PENDING, PROCESSING, SUCCEEDED, FAILED, CANCELED |
201 — The refund
| Field | Type | Description |
|---|---|---|
amount | integer | Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR) |
created_at | string (date-time) | |
currency | string | ISO 4217 currency code, upper case. pattern ^[A-Z]{3}$ |
failure_code | string or null | |
failure_message | string or null | |
id | string | |
metadata | object | Your own key-value data, returned as sent (at most 8 KB as JSON) |
object | refund | |
payment_id | string | pattern ^pay_[0-9A-HJKMNP-TV-Z]{26}$ |
reason | string or null | |
status | PENDING, PROCESSING, SUCCEEDED, FAILED, CANCELED |
Errors answer with the error object.
A payment's refunds
GET /v1/payments/{id}/refunds
Permission: refunds:read
curl -X GET https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/refunds \
-H "Authorization: Bearer sw_test_…"Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string (path) | yes | The payment id (pay_…) |
200 — The refunds
None.
Errors answer with the error object.
Retrieve a refund
GET /v1/refunds/{id}
Permission: refunds:read
curl -X GET https://api.sw-staging.dev/v1/refunds/pay_01M6XF0H2MAC63MEKQAT4K3AXF \
-H "Authorization: Bearer sw_test_…"Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string (path) | yes | The refund id |
200 — The refund
| Field | Type | Description |
|---|---|---|
amount | integer | Amount in the minor unit of the currency (e.g. halalas: 1050 = 10.50 SAR) |
created_at | string (date-time) | |
currency | string | ISO 4217 currency code, upper case. pattern ^[A-Z]{3}$ |
failure_code | string or null | |
failure_message | string or null | |
id | string | |
metadata | object | Your own key-value data, returned as sent (at most 8 KB as JSON) |
object | refund | |
payment_id | string | pattern ^pay_[0-9A-HJKMNP-TV-Z]{26}$ |
reason | string or null | |
status | PENDING, PROCESSING, SUCCEEDED, FAILED, CANCELED |
Errors answer with the error object.
Void an authorized payment
POST /v1/payments/{id}/void
Releases an authorization that was not captured.
Permission: payments:write
curl -X POST https://api.sw-staging.dev/v1/payments/pay_01M6XF0H2MAC63MEKQAT4K3AXF/void \
-H "Authorization: Bearer sw_test_…" \
-H "Idempotency-Key: $(uuidgen)"Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string (path) | yes | The payment id (pay_…) |
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 (optional)
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | no | at most 500 characters |
200 — The same void, replayed
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | |
failure_code | string or null | |
failure_message | string or null | |
id | string | |
metadata | object | Your own key-value data, returned as sent (at most 8 KB as JSON) |
object | void | |
payment_id | string | pattern ^pay_[0-9A-HJKMNP-TV-Z]{26}$ |
reason | string or null | |
status | PENDING, PROCESSING, SUCCEEDED, FAILED |
201 — The void
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | |
failure_code | string or null | |
failure_message | string or null | |
id | string | |
metadata | object | Your own key-value data, returned as sent (at most 8 KB as JSON) |
object | void | |
payment_id | string | pattern ^pay_[0-9A-HJKMNP-TV-Z]{26}$ |
reason | string or null | |
status | PENDING, PROCESSING, SUCCEEDED, FAILED |
Errors answer with the error object.