Guides
Dashboard

Settlement

Available since API version 2

Suggest Edits

Table of Contents

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.

StatusDescriptionWebhook Triggered?
CREATEDSettlement created❌
PROVIDER_REVIEWReviewed and sent to bank (if necessary)✅
AWAITING_PAYMENTAwaiting payment from the sender✅
AWAITING_SETTLEMENTPayment confirmed, awaiting settlement✅
CANCELLEDSettlement cancelled✅
COMPLETEDPayment 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.)

Updated 19 days ago