Create a transfer

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "externalId": "order-2026-0043",
  "sourceAccountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "targetAccountId": "b2c3d4e5-6f70-8901-bcde-f12345678901",
  "amount": {
    "value": "500.00",
    "asset": "BRL"
  }
}
'

import requests

url = "https://api.sandbox.tracefinance.com/v1/operations/transfers"

payload = {
    "externalId": "order-2026-0043",
    "sourceAccountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "targetAccountId": "b2c3d4e5-6f70-8901-bcde-f12345678901",
    "amount": {
        "value": "500.00",
        "asset": "BRL"
    }
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: 'order-2026-0043',
    sourceAccountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    targetAccountId: 'b2c3d4e5-6f70-8901-bcde-f12345678901',
    amount: {value: '500.00', asset: 'BRL'}
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.tracefinance.com/v1/operations/transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalId' => 'order-2026-0043',
    'sourceAccountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'targetAccountId' => 'b2c3d4e5-6f70-8901-bcde-f12345678901',
    'amount' => [
        'value' => '500.00',
        'asset' => 'BRL'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.tracefinance.com/v1/operations/transfers"

	payload := strings.NewReader("{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.tracefinance.com/v1/operations/transfers")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.tracefinance.com/v1/operations/transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "4c6d1f10-5b4d-7e6d-cf5b-ae4d7e6dcf5b",
  "externalId": "order-2026-0043",
  "customer": {
    "id": "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-05-06T16:24:11Z"
  },
  "intent": {
    "type": "TRANSFER",
    "targetAccount": {
      "id": "b2c3d4e5-6f70-8901-bcde-f12345678901",
      "owner": "Acme Importação Ltda"
    }
  },
  "quote": {
    "id": "d4e5f6a7-b8c9-0123-defa-2345678901bc",
    "effectiveRate": {
      "value": "1.00",
      "base": "BRL",
      "quote": "BRL"
    },
    "expiresAt": "2026-05-06T16:24:41Z"
  },
  "refund": null,
  "createdAt": "2026-05-06T16:24:11Z",
  "updatedAt": "2026-05-06T16:24:11Z"
}

POST

operations

transfers

Create a transfer

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "externalId": "order-2026-0043",
  "sourceAccountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "targetAccountId": "b2c3d4e5-6f70-8901-bcde-f12345678901",
  "amount": {
    "value": "500.00",
    "asset": "BRL"
  }
}
'

import requests

url = "https://api.sandbox.tracefinance.com/v1/operations/transfers"

payload = {
    "externalId": "order-2026-0043",
    "sourceAccountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "targetAccountId": "b2c3d4e5-6f70-8901-bcde-f12345678901",
    "amount": {
        "value": "500.00",
        "asset": "BRL"
    }
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: 'order-2026-0043',
    sourceAccountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    targetAccountId: 'b2c3d4e5-6f70-8901-bcde-f12345678901',
    amount: {value: '500.00', asset: 'BRL'}
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.tracefinance.com/v1/operations/transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalId' => 'order-2026-0043',
    'sourceAccountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'targetAccountId' => 'b2c3d4e5-6f70-8901-bcde-f12345678901',
    'amount' => [
        'value' => '500.00',
        'asset' => 'BRL'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.tracefinance.com/v1/operations/transfers"

	payload := strings.NewReader("{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.tracefinance.com/v1/operations/transfers")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.tracefinance.com/v1/operations/transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"order-2026-0043\",\n  \"sourceAccountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"targetAccountId\": \"b2c3d4e5-6f70-8901-bcde-f12345678901\",\n  \"amount\": {\n    \"value\": \"500.00\",\n    \"asset\": \"BRL\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "4c6d1f10-5b4d-7e6d-cf5b-ae4d7e6dcf5b",
  "externalId": "order-2026-0043",
  "customer": {
    "id": "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-05-06T16:24:11Z"
  },
  "intent": {
    "type": "TRANSFER",
    "targetAccount": {
      "id": "b2c3d4e5-6f70-8901-bcde-f12345678901",
      "owner": "Acme Importação Ltda"
    }
  },
  "quote": {
    "id": "d4e5f6a7-b8c9-0123-defa-2345678901bc",
    "effectiveRate": {
      "value": "1.00",
      "base": "BRL",
      "quote": "BRL"
    },
    "expiresAt": "2026-05-06T16:24:41Z"
  },
  "refund": null,
  "createdAt": "2026-05-06T16:24:11Z",
  "updatedAt": "2026-05-06T16:24:11Z"
}

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

Same-asset transfer between two accounts of the same customer. The asset on amount must be enabled on both accounts. No FX is performed — sourceAmount and targetAmount on the response are equal to amount. The system generates a 1:1 quote internally and returns it on quote.

sourceAccountId

string<uuid>

required

Source account that will be debited.

Example:

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

targetAccountId

string<uuid>

required

Target account that will be credited. Must belong to the same customer as the source account, must be in ACTIVE status, and must have amount.asset enabled. Cannot equal sourceAccountId.

Example:

"b2c3d4e5-6f70-8901-bcde-f12345678901"

amount

object

required

Amount to move. The same value is debited from the source and credited to the target.

Show child attributes

externalId

string | null

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"

Response

Transfer accepted. The operation is in REQUESTED status.

A created operation. Withdrawals, swaps, deposits, and transfers share this shape; intent.type identifies which.

string<uuid>

required

read-only

externalId

string | null

required

Required string length: 1 - 255

Example:

"order-2026-0043"

customer

object

required

Reference to the customer that owns the operation.

Show child attributes

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

Show child attributes

intent

Withdrawal · object

required

Operation intent. Discriminated by type.

Withdrawal
Swap
Deposit
Transfer

Show child attributes

quote

object | null

required

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

Show child attributes

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.

Show child attributes

fees

object[]

required

Show child attributes

transactions

object[]

required

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

Show child attributes

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.

Show child attributes

Example:

{
  "currentlyDue": [
    {
      "type": "BENEFICIARY_DOCUMENT",
      "documentType": "CUSTODY_ATTESTATION",
      "anyOf": ["CUSTODY_ATTESTATION"]
    }
  ],
  "pendingVerification": [],
  "errors": [],
  "satisfied": []
}

currentState

object

required

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

Show child attributes

createdAt

string<date-time>

required

read-only

updatedAt

string<date-time>

required

read-only

Accounts

Operations

Reports

Quotes

Beneficiaries

Webhooks

Create a transfer

Authorizations

Headers

Body

Response