Refund a deposit

Refunds a completed deposit in full, returning the funds to the original payer.

POST /v1/operations/{operationId}/refund

cURL

customerRequest

curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/operations/{operationId}/refund \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: <x-idempotency-key>' \ --data ' { "motive": { "code": "CUSTOMER_REQUEST", "message": "Customer requested the deposit be returned" } } '

202

refundAccepted

{ "id": "3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a", "externalId": null, "customer": { "id": "11111111-1111-1111-1111-111111111111" }, "account": { "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "owner": "Acme Importação Ltda" }, "sourceAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "targetAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "fees": [], "transactions": [ { "id": "E18236120202604271508u8h2c5k1p9q", "direction": "CREDIT", "amount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "status": "CONFIRMED" } ], "tags": [], "requirements": { "currentlyDue": [], "pendingVerification": [], "errors": [], "satisfied": [] }, "currentState": { "status": "REFUNDING", "createdAt": "2026-04-29T11:02:04Z" }, "intent": { "type": "DEPOSIT", "fundingInstruction": { "rail": "PIX_DYNAMIC_QR_CODE", "qrCode": "00020126830014br.gov.bcb.pix2561qr.sandbox.tracefinance.com/pix/v2/f6a7b8c9-d0e1-2345-fabc-456789012cde5204000053039865802BR5913Acme Importacao6009Sao Paulo62070503***63045E2A", "expiresAt": "2026-04-28T15:08:21Z" } }, "quote": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012cde", "effectiveRate": { "value": "1.00", "base": "BRL", "quote": "BRL" }, "expiresAt": "2026-04-27T15:08:51Z" }, "refund": { "motive": { "code": "CUSTOMER_REQUEST", "message": "Customer requested the deposit be returned", "details": {} }, "requestedAt": "2026-04-29T11:02:04Z" }, "createdAt": "2026-04-27T15:08:21Z", "updatedAt": "2026-04-29T11:02:04Z" }

Authorizations

Authorization · string · header · required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Idempotency-Key · string<uuid> · required

Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.

X-Trace-Version · string

API version. Omit to use the default version.

Example:

"1"

Path Parameters

operationId · string<uuid> · required

UUID of the operation.

Body

application/json

Request to refund a completed deposit. The refund is always for the full deposit amount and returns the funds to the original payer.

motive · object · required

Why the deposit is being refunded. Recorded as the reason on the operation's REFUNDED state.

Show child attributes

Response

202

application/json

Refund accepted for processing. The body is the deposit in REFUNDING; poll GET /v1/operations/{operationId} to follow it to REFUNDED.

A created operation. Withdrawals, swaps, deposits, and transfers share this shape; intent.type identifies which.

id · string<uuid> · required · read-only

externalId · string | null · required

Your own identifier for the operation. Stored as given and returned on every read and every webhook. Free-form: it is not deduplicated, and the same value may appear on more than one operation. null when none was sent, and on a deposit credited from an incoming payment nobody requested.

Required string length: 1 - 255

Example:

"order-2026-0043"

customer · object · required

Reference to the customer that owns the operation.

Show child attributes

account · object · required

Reference to a customer account, including the registered owner name.

Show child attributes

sourceAmount · object · required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.

Show child attributes

targetAmount · object · required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.

Show child attributes

intent · Withdrawal · object · required

Operation intent. Discriminated by type.

Withdrawal

Swap

Deposit

Transfer

Show child attributes

quote · object | null · required

Consumed quote. null for deposits created without a prior quote; present for all other operations.

Show child attributes

refund · object | null · required

The refund you asked for on this deposit. null on every operation nobody asked back, and on a return the payer's bank issued on its own.

Show child attributes

fees · object[] · required

Show child attributes

transactions · object[] · required

Rail-level transactions for the operation. Only confirmed transactions are included; pending or failed rail movements are omitted.

Show child attributes

requirements · object · required

What compliance is waiting on for this operation, read live at request time. All four groups are empty for an operation that never went through a compliance review. An operation in ACTION_REQUIRED is waiting on whatever is in currentlyDue and errors.

Show child attributes

Example:

{
  "currentlyDue": [
    {
      "type": "BENEFICIARY_DOCUMENT",
      "documentType": "CUSTODY_ATTESTATION",
      "anyOf": ["CUSTODY_ATTESTATION"]
    }
  ],
  "pendingVerification": [],
  "errors": [],
  "satisfied": []
}

currentState · object · required

The operation's current state. Carries a status, optional reason, and the time the state was entered.

Show child attributes

createdAt · string<date-time> · required · read-only

updatedAt · string<date-time> · required · read-only

tags · object[]

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Show child attributes

Example:

[
  { "key": "psp", "value": "Amazon" },
  { "key": "compliance-tier", "value": "high" }
]