Skip to main content
POST
/
v1
/
refunds
curl --request POST \
  --url http://localhost:4011/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "endToEndId": "E12345678202501011200000001",
  "accountId": "12345678-1234-1234-1234-123456789012",
  "transactionId": "01989f9e-6508-79f8-9540-835be49fbd0d",
  "code": "FR01",
  "amount": 100.5,
  "description": "Fraudulent transaction detected"
}'
{
  "id": "refund_123456789",
  "accountId": "acc_123456789",
  "code": "MD06",
  "endToEndId": "E1234567820230615123456789012345",
  "endToEndRefundId": "D1234567820230615987654321098765",
  "amount": 100.5,
  "description": "Requested by receiver",
  "status": "PENDING",
  "createdAt": "2023-06-15T11:00:00Z"
}

Authorizations

​
Authorization
string
header
required

JWT Bearer token authentication. Obtain token from /v1/login/oauth/access_token endpoint using client credentials (clientId and clientSecret).

Include token in Authorization header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token expires after 3600 seconds (1 hour).

Body

application/json
​
endToEndId
string
required

Original transaction's end-to-end identifier to be refunded.

Example:

"E12345678202501011200000001"

​
accountId
string<uuid>
required

Account identifier requesting the refund.

Example:

"12345678-1234-1234-1234-123456789012"

​
transactionId
string<uuid>
required

Original transaction identifier to be refunded.

Example:

"01989f9e-6508-79f8-9540-835be49fbd0d"

​
code
enum<string>
required

Refund reason codes as defined by Brazilian Central Bank (BACEN). Standardized codes used when requesting transaction refunds.

Valid values:

  • FR01 = Fraud (Transaction identified as fraudulent)
  • AC03 = Invalid creditor account (Recipient account is invalid or doesn't exist)
  • AG01 = Transaction forbidden (Transaction type not allowed for this account)
  • MD06 = Refund requested by receiver (Payee requested the refund)
  • BE01 = Inconsistent data (Transaction data contains inconsistencies)
  • AC07 = Closed account (Recipient account has been closed)
Available options:
FR01,
AC03,
AG01,
MD06,
BE01,
AC07
Example:

"MD06"

​
amount
number
required

Refund amount (must not exceed original transaction amount).

Example:

100.5

​
description
string
required

Description of the refund reason.

Example:

"Refund requested by receiver"

Response

Refund created successfully

​
id
string
required

Unique refund identifier.

Example:

"refund_123456789"

​
accountId
string
required

Account identifier associated with the refund.

Example:

"acc_123456789"

​
code
enum<string>
required

Refund reason codes as defined by Brazilian Central Bank (BACEN). Standardized codes used when requesting transaction refunds.

Valid values:

  • FR01 = Fraud (Transaction identified as fraudulent)
  • AC03 = Invalid creditor account (Recipient account is invalid or doesn't exist)
  • AG01 = Transaction forbidden (Transaction type not allowed for this account)
  • MD06 = Refund requested by receiver (Payee requested the refund)
  • BE01 = Inconsistent data (Transaction data contains inconsistencies)
  • AC07 = Closed account (Recipient account has been closed)
Available options:
FR01,
AC03,
AG01,
MD06,
BE01,
AC07
Example:

"MD06"

​
endToEndId
string
required

Original transaction's end-to-end identifier that was refunded.

Example:

"E1234567820230615123456789012345"

​
endToEndRefundId
string
required

Refund's end-to-end identifier.

Example:

"D1234567820230615987654321098765"

​
amount
number
required

Refund amount.

Example:

100.5

​
description
string
required

Description of the refund reason.

Example:

"Requested by receiver"

​
status
string
required

Refund status.

Example:

"PENDING"

​
createdAt
string<date-time>
required

Refund creation timestamp.

Example:

"2023-06-15T11:00:00Z"

⌘I