Create a deposit

Creates a deposit and returns the funding instruction the customer should use to send money in.

POST /api/operations/deposit

cURL

pixDeposit

curl --request POST \ --url https://api.sandbox.tracefinance.com/api/operations/deposit \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: <x-idempotency-key>' \ --data ' { "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "quoteId": "f6a7b8c9-d0e1-2345-fabc-456789012cde", "fundingInstruction": { "rail": "PIX_KEY" } } '

201

pixDeposit

{ "id": "3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a", "customerId": "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": [], "tags": [ { "key": "psp", "value": "Amazon" }, { "key": "compliance-tier", "value": "high" } ], "currentState": { "status": "REQUESTED", "createdAt": "2026-04-27T15:08:21Z" }, "states": [ { "status": "REQUESTED", "createdAt": "2026-04-27T15:08:21Z" } ], "intent": { "type": "DEPOSIT", "fundingInstruction": { "rail": "PIX_KEY", "keyType": "CNPJ", "key": "12345678000101" } }, "quote": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012cde", "effectiveRate": { "value": "1.00", "base": "BRL", "quote": "BRL" }, "expiresAt": "2026-04-27T15:08:51Z", "consumedAt": null }, "createdAt": "2026-04-27T15:08:21Z", "updatedAt": "2026-04-27T15:08:21Z" }

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"

Body

application/json

Every deposit references a quote previously obtained from POST /api/quotes. The quote determines sourceAmount and targetAmount and locks the FX rate (or the 1:1 spot for same-asset). A quote can be consumed by at most one operation. The customer picks which funding rail they will use to send money in via fundingInstruction.rail. The response returns the concrete instruction details (PIX key, boleto barcode, TED account, etc.) under intent.fundingInstruction.

accountId · string<uuid> · required

Account that will be credited. Must match the account on the referenced quote.

Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

quoteId · string<uuid> · required

ID of a quote returned by POST /api/quotes. Must belong to the same customer, must not have expired, and must not have been consumed by another operation.

Example:

"f6a7b8c9-d0e1-2345-fabc-456789012cde"

fundingInstruction · object · required

Selects which funding rail the customer will use to send the money in.

Show child attributes

Response

201

application/json

Deposit accepted. The operation is in REQUESTED status.

An operation. Withdrawals (POST /api/operations/withdrawal), swaps (POST /api/operations/swap), deposits (POST /api/operations/deposit), and transfers (POST /api/operations/transfer) share this shape, discriminated by intent.type. The quote field is always present; for transfers without an explicit quoteId in the request, the system generates a 1:1 same-asset quote.

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

customerId · string<uuid> · required

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 · required

Reference to the quote consumed by the operation.

Show child attributes

fees · object[] · required

Show child attributes

transactions · object[] · required

Show child attributes

currentState · object · required

A single entry in an operation's state history. Carries a status, optional reason, and the time the state was entered.

Show child attributes

states · object[] · required

Full state history of the operation, oldest first. The last entry equals currentState.

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" }
]