Skip to main content
POST
Refund a captured payment

Authorizations

X-Suby-Api-Key
string
header
required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key
string

Optional key (≤255 chars, e.g. a UUID v4) making this POST safe to retry · the response is cached 24h and a retry with the SAME key replays it instead of re-executing. The same key with a different body → 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first is in flight → 409.

Maximum string length: 255
Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Path Parameters

id
string
required
Example:

"pay_abc123"

Body

application/json
refundCents
string

Minor units as a string of digits · "500" = 5.00. Omit for a full refund of what remains; above that answers 422.

Pattern: ^[1-9]\d*$
Example:

"500"

reason
string

Merchant-facing refund reason.

Maximum string length: 500

Response

Refund accepted (status flips to REFUNDED / PARTIALLY_REFUNDED via webhook)

success
boolean
required
Example:

true

data
object
required

Endpoint-specific payload.

message
string