Create a deposit

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/deposits \
  --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_DYNAMIC_QR_CODE"
  },
  "payer": {
    "identificationDocument": {
      "type": "CPF",
      "value": "52998224725"
    },
    "firstName": "Maria",
    "lastName": "Silva",
    "address": {
      "city": "São Paulo"
    }
  }
}
'

import requests

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

payload = {
    "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "quoteId": "f6a7b8c9-d0e1-2345-fabc-456789012cde",
    "fundingInstruction": { "rail": "PIX_DYNAMIC_QR_CODE" },
    "payer": {
        "identificationDocument": {
            "type": "CPF",
            "value": "52998224725"
        },
        "firstName": "Maria",
        "lastName": "Silva",
        "address": { "city": "São Paulo" }
    }
}
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({
    accountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    quoteId: 'f6a7b8c9-d0e1-2345-fabc-456789012cde',
    fundingInstruction: {rail: 'PIX_DYNAMIC_QR_CODE'},
    payer: {
      identificationDocument: {type: 'CPF', value: '52998224725'},
      firstName: 'Maria',
      lastName: 'Silva',
      address: {city: 'São Paulo'}
    }
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/deposits', 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/deposits",
  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([
    'accountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'quoteId' => 'f6a7b8c9-d0e1-2345-fabc-456789012cde',
    'fundingInstruction' => [
        'rail' => 'PIX_DYNAMIC_QR_CODE'
    ],
    'payer' => [
        'identificationDocument' => [
                'type' => 'CPF',
                'value' => '52998224725'
        ],
        'firstName' => 'Maria',
        'lastName' => 'Silva',
        'address' => [
                'city' => 'São Paulo'
        ]
    ]
  ]),
  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/deposits"

	payload := strings.NewReader("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\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/deposits")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\n  }\n}"

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

{
  "id": "3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a",
  "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-04-27T15:08:21Z"
  },
  "intent": {
    "type": "DEPOSIT",
    "fundingInstruction": {
      "rail": "PIX_DYNAMIC_QR_CODE",
      "qrCode": "00020126830014br.gov.bcb.pix2561qr.sandbox.tracefinance.com/pix/v2/f6a7b8c9-d0e1-2345-fabc-456789012cde5204000053039865802BR5913Acme Importacao6009Sao Paulo62070503***63045E2A",
      "expiresAt": "2026-04-28T15:08:21Z"
    }
  },
  "quote": {
    "id": "f6a7b8c9-d0e1-2345-fabc-456789012cde",
    "effectiveRate": {
      "value": "1.00",
      "base": "BRL",
      "quote": "BRL"
    },
    "expiresAt": "2026-04-27T15:08:51Z"
  },
  "createdAt": "2026-04-27T15:08:21Z",
  "updatedAt": "2026-04-27T15:08:21Z"
}

POST

operations

deposits

Create a deposit

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/deposits \
  --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_DYNAMIC_QR_CODE"
  },
  "payer": {
    "identificationDocument": {
      "type": "CPF",
      "value": "52998224725"
    },
    "firstName": "Maria",
    "lastName": "Silva",
    "address": {
      "city": "São Paulo"
    }
  }
}
'

import requests

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

payload = {
    "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "quoteId": "f6a7b8c9-d0e1-2345-fabc-456789012cde",
    "fundingInstruction": { "rail": "PIX_DYNAMIC_QR_CODE" },
    "payer": {
        "identificationDocument": {
            "type": "CPF",
            "value": "52998224725"
        },
        "firstName": "Maria",
        "lastName": "Silva",
        "address": { "city": "São Paulo" }
    }
}
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({
    accountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    quoteId: 'f6a7b8c9-d0e1-2345-fabc-456789012cde',
    fundingInstruction: {rail: 'PIX_DYNAMIC_QR_CODE'},
    payer: {
      identificationDocument: {type: 'CPF', value: '52998224725'},
      firstName: 'Maria',
      lastName: 'Silva',
      address: {city: 'São Paulo'}
    }
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/deposits', 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/deposits",
  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([
    'accountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'quoteId' => 'f6a7b8c9-d0e1-2345-fabc-456789012cde',
    'fundingInstruction' => [
        'rail' => 'PIX_DYNAMIC_QR_CODE'
    ],
    'payer' => [
        'identificationDocument' => [
                'type' => 'CPF',
                'value' => '52998224725'
        ],
        'firstName' => 'Maria',
        'lastName' => 'Silva',
        'address' => [
                'city' => 'São Paulo'
        ]
    ]
  ]),
  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/deposits"

	payload := strings.NewReader("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\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/deposits")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"f6a7b8c9-d0e1-2345-fabc-456789012cde\",\n  \"fundingInstruction\": {\n    \"rail\": \"PIX_DYNAMIC_QR_CODE\"\n  },\n  \"payer\": {\n    \"identificationDocument\": {\n      \"type\": \"CPF\",\n      \"value\": \"52998224725\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Silva\",\n    \"address\": {\n      \"city\": \"São Paulo\"\n    }\n  }\n}"

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

{
  "id": "3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a",
  "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-04-27T15:08:21Z"
  },
  "intent": {
    "type": "DEPOSIT",
    "fundingInstruction": {
      "rail": "PIX_DYNAMIC_QR_CODE",
      "qrCode": "00020126830014br.gov.bcb.pix2561qr.sandbox.tracefinance.com/pix/v2/f6a7b8c9-d0e1-2345-fabc-456789012cde5204000053039865802BR5913Acme Importacao6009Sao Paulo62070503***63045E2A",
      "expiresAt": "2026-04-28T15:08:21Z"
    }
  },
  "quote": {
    "id": "f6a7b8c9-d0e1-2345-fabc-456789012cde",
    "effectiveRate": {
      "value": "1.00",
      "base": "BRL",
      "quote": "BRL"
    },
    "expiresAt": "2026-04-27T15:08:51Z"
  },
  "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 /v1/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 the funding rail via fundingInstruction.rail; the response returns the concrete instruction — the PIX dynamic QR code payload — 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 /v1/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

payer

object | null

Optional payer details for the incoming funds. When omitted, the account owner is assumed to be the payer.

Show child attributes

Response

Deposit accepted. The operation is in REQUESTED status.

A created operation. Withdrawals, swaps, deposits, and transfers share this shape; intent.type identifies which. quote is present for withdrawals, swaps, and transfers (transfers take no quoteId and get a 1:1 quote generated internally); it is null for deposits created without a prior quote.

string<uuid>

required

read-only

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

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 deposit

Authorizations

Headers

Body

Response