Skip to main content
POST
Request transaction refund

Authorizations

Authorization
string
header
required

Access token obtained from POST /auth (client_id + client_secret). Valid for 300 seconds.

Headers

X-Sub-Account
string

Reference of the sub-account the operation runs against. When omitted, the operation happens on the main account; the reserved value principal also resolves to the main account and is equivalent to omitting the header. Accepted on every endpoint except POST /auth and the /sub-accounts endpoints themselves, which always operate on the main account.

Possible errors: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.

Requires the credential to have sub-account access enabled (Settings → Integration → API Credentials). It starts turned off and is not replaced by any permission, not even FULL_ACCESS: without it the response is 403 SUB_ACCOUNT_FORBIDDEN.

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
Example:

"loja-centro"

Path Parameters

id
string<uuid>
required

ID of the payment transaction to be refunded

Body

application/json
reason
string

Refund reason (optional, up to 255 characters)

Maximum string length: 255
Example:

"Cliente solicitou cancelamento"

Response

Refund requested successfully. Status remains PENDING until confirmation via webhook.

originalTransactionId
string<uuid>
required

ID of the original transaction being refunded

pspProvider
string
required

PSP provider that processed the refund

pspRefundTransactionId
string
required

Refund transaction ID at the PSP

status
enum<string>
required

Status returned by the PSP. PENDING means the refund was accepted but not yet confirmed — confirmation arrives via the refund_completed webhook.

Available options:
PENDING,
CONFIRMED,
ERROR
Example:

"PENDING"