Skip to main content

​
Overview

Deposits credit an account when funds arrive. The customer references a quote that locks the rate (or a 1:1 spot for same-asset) and picks a funding rail; the response returns the concrete funding instruction — a PIX dynamic QR code — the payer uses to send money in. The deposit transitions to COMPLETED once the inbound payment is reconciled.

​
Prerequisites

​
Steps

1

Create a quote

Quotes lock the FX rate (or a 1:1 spot for same-asset) for a short window and are bound to one account. Use sourceAsset for the asset paid in and targetAsset for the asset credited to the account.
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "<account-id>",
    "sourceAsset": "BRL",
    "targetAsset": "BRL",
    "sourceAmount": "500.00"
  }'
The response returns the quote id, the locked effectiveRate, and expiresAt. The quote can be consumed by exactly one operation before it expires.
2

Create the deposit

Reference the account, the quote, and the funding rail the payer will use to send the money in.
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/operations/deposit \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "<account-id>",
    "quoteId": "<quote-id>",
    "fundingInstruction": {
      "rail": "PIX_DYNAMIC_QR_CODE",
      "expiresIn": 86400
    }
  }'
expiresIn is optional: how long the funding instruction stays valid, in seconds, up to 172800 (48 hours). It applies only to PIX_DYNAMIC_QR_CODE deposits where the quote’s source and target asset match. Otherwise the operation inherits the quote’s expiresAt.Returns 201 with the operation in REQUESTED status. The response carries intent.fundingInstruction with the concrete details for the rail — for PIX_DYNAMIC_QR_CODE that’s the qrCode payload (EMV-encoded BR Code) and its expiresAt — and intent.expiresAt, when the deposit itself expires.
3

Send the funds

Present the qrCode from intent.fundingInstruction to the payer to pay via PIX before expiresAt. The amount must match the quote’s sourceAmount.
4

Track the deposit

Subscribe to OPERATION_COMPLETED to receive the deposit confirmation once the inbound payment is reconciled, or OPERATION_FAILED if reconciliation fails. Both deliver the same payload as OPERATION_REQUESTED, with currentState.status set to the new status (and currentState.reason populated on failure). The intermediate PROCESSING status is not published as a webhook; poll GET /api/operations/{operationId} if you need to surface it in your UI.
curl --request GET \
  --url https://api.sandbox.tracefinance.com/api/operations/<operation-id> \
  --header 'Authorization: Bearer <token>'

​
What happens next