Skip to main content
POST
/
v1
/
refunds
curl --request POST \
  --url https://plugin-pix-direct.api.lerian.net/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endToEndId": "E12345678202501011200000001",
  "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
  "transactionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "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).

Headers

​
Idempotency-Key
string

Optional idempotency key for safe retries (IETF standard). Use a UUID v4 or unique business identifier. If the same key is sent again and the original request was already processed, the cached response is returned.

See Retries and idempotency for details.

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:

"019c96a0-0c0c-7221-8cf3-13313fb60081"

​
transactionId
string<uuid>
required

Original transaction identifier to be refunded.

Example:

"019c96a0-0a98-7287-9a31-786e0809c769"

​
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<double>
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<double>
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"