Skip to main content
POST
/
v1
/
transfers
/
{transfer_id}
/
refunds
Refund a Received Pix Transfer
curl --request POST \
  --url https://plugin-pix-indirect.api.lerian.net/v1/transfers/{transfer_id}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Reason: <x-reason>' \
  --data '
{
  "amount": "100.00"
}
'
{
  "id": "019c96a0-0c53-7a8d-8e29-67971d96d0e3",
  "originalEndToEndId": "E123456789BR1234567890123456789",
  "returnEndToEndId": "D123456789BR1234567890123456789",
  "amount": "100.00",
  "status": "COMPLETED",
  "reason": "FR01",
  "createdAt": "2024-01-15T10:30:00Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Account-Id
string
required

Unique identifier of the Midaz Ledger Account (UUID format).

​
X-Reason
enum<string>
required

Refund reason code. BE08 = Bank Error, FR01 = Fraud, MD06 = Refund Requested by End Customer, SL02 = PixWithdrawal/PixChange Error.

Available options:
BE08,
FR01,
MD06,
SL02
​
X-Idempotency
string

Optional idempotency key for safe retries. Reuse the same value only when retrying the same operation after an unknown outcome.

See Retries and idempotency for details.

​
X-TTL
integer

Time-to-live in seconds for the idempotency key cache. Defines how long the system remembers a processed request.

See Retries and idempotency for details.

Path Parameters

​
transfer_id
string
required

Unique identifier of the Pix transfer (UUID format).

Body

application/json
​
amount
string
required

Total refund amount. When operations is provided, this must equal the sum of all operation amounts.

Example:

"100.50"

​
description
string

Optional description for the refund.

Maximum string length: 140
Example:

"Customer reported unauthorized transaction"

​
metadata
object

Custom key-value attributes for this refund. Maximum 50 keys, key max 100 chars, value max 2000 chars.

​
operations
object[]

Explicit per-account debit operations for partial distributed refunds. When present, each operation specifies the accountAlias and amount to debit, and the sum of all operation amounts must equal the total refund amount. When absent, the existing refund flow is used (simple or full refund with fee inversion).

Required array length: 1 - 50 elements

Response

Refund instruction submitted successfully.

The response includes the X-Idempotency-Replayed header.

If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request.

See Retries and idempotency for more details.

​
id
string

Refund unique identifier.

Example:

"019c96a0-0c53-7a8d-8e29-67971d96d0e3"

​
originalEndToEndId
string

Original transfer E2E ID.

Example:

"E123456789BR1234567890123456789"

​
returnEndToEndId
string

Return transfer E2E ID.

Example:

"D123456789BR1234567890123456789"

​
amount
string

Refund amount.

Example:

"100.00"

​
status
string

Refund status.

Example:

"COMPLETED"

​
reason
string

Refund reason code.

Example:

"FR01"

​
createdAt
string<date-time>
Example:

"2024-01-15T10:30:00Z"