Deposit

Step-by-step guide to crediting an account using PIX, TED, Boleto, or a crypto wallet.

Overview

Deposits credit an account when funds arrive via the chosen funding rail. The customer creates a deposit operation referencing a quote and a rail; the response returns the concrete funding instruction (PIX key, boleto barcode, TED account, or crypto wallet) the customer uses to send money in. The deposit transitions to COMPLETED once the inbound payment is reconciled.

Prerequisites

• An active account configured for the asset to be credited.
• Valid authentication credentials.

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 what the customer will send and targetAsset for what gets credited.

   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 pick which funding rail the customer 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_KEY"
       }
     }'
   

   Returns 201 with the operation in REQUESTED status. The response carries intent.fundingInstruction with the concrete details for the chosen rail — for PIX_KEY that’s the keyType and key to pay; for BOLETO it’s the barcode and dueDate; for TED the bank, branch, and account number; for CRYPTO the network and wallet address.

3. Send the funds

   Use the intent.fundingInstruction from the previous step to make the inbound payment via the chosen rail. 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

• Execute a swap — convert the deposited asset within the account.
• Make a withdrawal — send funds out.