Transfer

Step-by-step guide to moving funds between two accounts of the same customer.

Overview

Transfers move funds between two accounts owned by the same customer. They are same-asset — the same value is debited from the source account and credited to the target account, with no FX conversion. The system generates a 1:1 quote internally and returns it on the response; you do not need to create a quote first. To move between assets, execute a swap and then transfer.

Prerequisites

• Two active accounts owned by the same customer, both with the requested asset enabled. The source must hold sufficient balance.
• Valid authentication credentials.

Steps

1. Create the transfer

   Reference the source account, the target account, and the amount to move. Source and target must differ; the target account must be in ACTIVE status with the requested asset enabled.

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/operations/transfer \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "sourceAccountId": "<source-account-id>",
       "targetAccountId": "<target-account-id>",
       "amount": {
         "value": "500.00",
         "asset": "BRL"
       }
     }'
   

   Returns 201 immediately with the operation in REQUESTED status. Settlement happens asynchronously.

2. Track the transfer

   Subscribe to OPERATION_COMPLETED and OPERATION_FAILED to receive the terminal outcome — 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>'
   

Cross-customer transfers are not supported — both accounts must belong to the same customer. If the target account belongs to another customer, the API returns 404 RESOURCE_NOT_FOUND.

What happens next

• Execute a swap — convert between assets within a single account.
• Make a withdrawal — send funds out to an external beneficiary.