Skip to main content
POST

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
required

Key that makes the request safe to retry. Any non-blank string of up to 255 characters. See Idempotency.

Maximum string length: 255
Example:

"00000000-0000-4000-8000-000000000001"

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. Stored on the operation's refund.motive and returned as given; the REFUNDING and REFUNDED states carry no reason.

Response

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.

account
object
required

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

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.

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.

intent
Withdrawal · object
required

Operation intent. Discriminated by type.

quote
object | null
required

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

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.

fees
object[]
required
transactions
(PIX · object | Crypto · object | TED · object | Boleto · object | Internal debit · object | Internal credit · object)[]
required

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

A rail-level transaction associated with the operation. Discriminated by type, which names the rail that moved the money — INTERNAL_DEBIT and INTERNAL_CREDIT are the two legs of a movement that stays inside the platform and touches no external rail.

tags
object[]
required

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

Example:
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.

Example:
currentState
object
required

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

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