Prerequisites

Before reading this documentation, it is recommended that the reader reviews the following topics:

What is a Settlement?

A settlement represents the financial completion process of one or more foreign exchange orders. Through an agreement, the payment and receipt instructions are defined, grouping compatible operations for joint execution.

Each settlement carries all necessary information to ensure that the operation is processed correctly, including monetary values, banking channels, and counterparties.

Key Properties

type

Identifies the type of settlement and should be used to correctly parse the data returned by the API.

counterparty

Contains the details of the counterparty associated with the orders included in the agreement (for more details, see the counterparties section).

operation

Type of operations associated with the settlement.

paymentAmount

Amount to be paid by the sender.

For outbound operations (buy), the amount is expressed in BRL.
For inbound operations (sell), the amount is expressed in the foreign currency or crypto asset.

receivingAmount

Amount to be received by the beneficiary.

For outbound operations (buy), the amount is expressed in the foreign currency or crypto asset.
For inbound operations (sell), the amount is expressed in BRL.

currentState

Reflects the current state of the settlement (see the states section for more details).

sourceBankingChannel

Banking channel through which the sender must make the payment.

For outbound operations (buy), it will be a TED_PIX type banking channel.

{
  "sourceBankingChannel": {
    "id": "source-bank-channel-id",
    "type": "TED_PIX",
    "currency": "BRL",
    "bankCode": "000",
    "bankName": "bank-name",
    "branchCode": "branch-code",
    "accountNumber": "account-number",
    "pixKey": null,
    "beneficiary": {
      "name": "Trace Correspondente Cambial Ltda",
      "taxId": "37041494000162",
      "address": {
        "country": "BR",
        "address": "Avenida Ruy Frazao Soares, 191, Loj F, 22.793-074, Rio de Janeiro, RJ"
      }
    }
  }
}

For inbound operations (sell), it can be:
- Fiat currencies via SWIFT

{
  "sourceBankingChannel": {
    "id": "source-bank-channel-id",
    "type": "SWIFT",
    "currency": "USD",
    "swiftCode": "swift-code",
    "iban": "iban-code",
    "aba": "aba-code",
    "referenceField": null,
    "beneficiary": {
        "name": "TRACE FINANCE HOLDINGS LIMITED",
        "taxId": null,
        "address": {
            "country": "US",
            "address": "10008 WILLOW HOUSE CRICKET SQUARE S N, Georgetown, EF"
        }
    }
  }
}

Virtual assets via CRYPTO_WALLET

{
  "sourceBankingChannel": {
    "id": "source-bank-channel-id",
    "type": "CRYPTO_WALLET",
    "currency": "USDC",
    "address": "wallet-address",
    "chain": "SOLANA",
    "beneficiary": {
        "name": "TRACE FINANCE HOLDINGS LIMITED",
        "taxId": null,
        "address": {
            "country": "US",
            "address": "10008 WILLOW HOUSE CRICKET SQUARE S N, Georgetown, EF"
        }
    }
  }
}

targetBankingChannel

Banking channel through which the beneficiary will receive the funds.

For inbound operations (sell), it will be a TED_PIX type banking channel.

{
  "targetBankingChannel": {
    "id": "target-bank-channel-id",
    "type": "TED_PIX",
    "currency": "BRL",
    "bankCode": "000",
    "bankName": "bank-name",
    "branchCode": "branch-code",
    "accountNumber": "account-number",
    "pixKey": null,
    "beneficiary": {
      "name": "Company Name",
      "taxId": "12345678901234",
      "address": {
        "country": "BR",
        "address": "Avenida XXX, 1, NN.NNN-NNN, Somewhere, XX"
      }
    }
  }
}

For outbound operations (buy), it can be:
- Fiat currencies via SWIFT

{
  "targetBankingChannel": {
    "id": "target-bank-channel-id",
    "type": "SWIFT",
    "currency": "USD",
    "swiftCode": "swift-code",
    "iban": "iban-code",
    "aba": "aba-code",
    "referenceField": null,
    "beneficiary": {
        "name": "Counterparty Name",
        "taxId": null,
        "address": {
            "country": "US",
            "address": "some street, Somewhere, XX"
        }
    }
  }
}

Virtual assets via CRYPTO_WALLET

{
  "targetBankingChannel": {
    "id": "target-bank-channel-id",
    "type": "CRYPTO_WALLET",
    "currency": "USDC",
    "address": "wallet-address",
    "chain": "SOLANA",
    "beneficiary": {
        "name": "Counterparty Name",
        "taxId": null,
        "address": {
            "country": "US",
            "address": "some street, Somewhere, XX"
        }
    }
  }
}

Settlement States

Below are the possible statuses of a settlement.

Status	Description	Webhook Triggered?
`CREATED`	Settlement created	❌
`PROVIDER_REVIEW`	Reviewed and sent to bank (if necessary)	✅
`AWAITING_PAYMENT`	Awaiting payment from the sender	✅
`AWAITING_SETTLEMENT`	Payment confirmed, awaiting settlement	✅
`CANCELLED`	Settlement cancelled	✅
`COMPLETED`	Payment and settlement confirmed, process completed	✅

Notifications

After a settlement is created and reviewed, an email is sent to the company with payment and settlement instructions.

Buy (Outbound) Settlement

Sell (Settlement)

How to Query Settlements

Listing a Company's Settlements

Request

curl --location 'https://faas.dev.tracefinance.io/exchange/api/settlements' \
--header 'Authorization: Bearer *******'

Response

(The response JSON remains unchanged, as it consists of standard API output.)

Listing Settlements by Status

Request

curl --location 'https://faas.dev.tracefinance.io/exchange/api/settlements&filter=currentState.status[last]=CANCELLED' \
--header 'Authorization: Bearer *******'

Response

(The response JSON remains unchanged.)

Sandbox environment

Settlement Review

In the sandbox environment, settlement reviews are conducted automatically by a scheduled job with the following parameters:

Days of Execution: Monday through Friday
Execution Time (GMT): From 08:00 to 21:50, every 10 minutes
Corresponding Time (BRT): From 05:00 to 18:50, every 10 minutes

To ensure a settlement is reviewed and its status transitions to PROVIDER_REVIEW, the targetBankChannelId field must be populated at the time of order creation.

Status Transition

A separate automated job handles the transition of settlement statuses from PROVIDER_REVIEW to subsequent statuses. This job operates on the same schedule:

Days of Execution: Monday through Friday
Execution Time (GMT): From 08:00 to 21:50, every 10 minutes
Corresponding Time (BRT): From 05:00 to 18:50, every 10 minutes

This process simulates the provider's review and approval workflow within the sandbox environment.