Skip to main content
Transactions are a core pillar of the Borderless network. These are the actions taken by users and organizations across many functions. Types of transactions include converting stablecoins to local fiat currencies via withdrawals (off-ramp), or vice versa as a deposit (on-ramp). We’ve also recently expanded these concepts to include fx exchange, now decoupled from a withdrawal or deposit, as well as upcoming OTC type transactions.
If you’re just getting started, please check out our quick start guide.
All transactions with Borderless are asynchronous, meaning when you initiate an operation, you receive a transaction object in an initial state. As the transaction progresses, you can track updates either via webhooks or by polling the transaction status using the API. For full API details and request structure, please refer to the API Reference. Transactions are primarily divided into two main categories:

​
Transaction Structure

A transaction in Borderless contains rich metadata. Below are some of the main fields:
​
id
string
required
Unique transaction identifier
​
type
string enum
required
The type of transaction such as AssetDeposit Deposit Withdrawal Transfer TransferToExternalWallet Swap Approval Exchange
​
status
string enum
required
The status of the transaction such as Submitted Verifying Orchestrating Pending Processing Completed Failed CancelledWhen a transaction is in the Pending status, it may include instructions which are required whenever additional action is needed from the user.For example, in a Deposit transaction, Borderless creates a transaction with an instruction that tells the user where to send the fiat funds to complete the deposit.Similar instruction objects are used in other types of transactions and may vary depending on the web3 infrastructure provider you’re using.
Make sure to check the specific operation documentation to understand what instructions may be required and how to handle them.
​
pfiName
string | null enum
required
The name of the partner financial institution (PFI) who is completing the transaction such as Bridge Pipes Koywe Kotanipay LIFI Hercle Manual Bitso YellowCard TraceFinance HoneyCoin BlindPay Finity Ares Infinia Walapay Abra Yativo Capa
​
source
object
required
An object of data that describes the source or beginning leg of the transaction. This object contains fields such as asset amount fiatCurrency paymentMethod accountId accountName sender
​
destination
object
required
An object of data that describes the destination or end leg of the transaction. This object contains fields such as asset amount fiatCurrency imad omad traceNumber externalAddress accountId accountName paymentInstructionId
​
createdAt
date-time
required
Date and time the transaction was created.
​
updatedAt
date-time
required
Date and time the transaction was updated.
​
txHash
array of strings
required
The hash of an onchain transaction that was completed.
​
feeAmount
object
required
The developer fee amount that was charged in the transaction.
… and more. Please see the full and current list on our API Reference here

​
Transaction Statuses

Let’s take a moment to provide a detailed explanation of the various statuses a transaction can go through during its lifecycle. Each status represents a specific stage in the process, from the moment a transaction is created to its final completion or failure. Understanding these statuses helps users track their transactions and take necessary actions when required. Every transaction begins with the Submitted status and progresses through various stages depending on its type and requirements. Ultimately, a transaction concludes with one of the following final statuses: Completed, Failed, Canceled Submitted - The transaction has been received by Borderless and sent to the queue for processing. It begins to be processed in less than one second. Verifying - This status applies only to transactions involving Partner Financial Institutions that require KYC reviews. If the identity has already been verified (KYC/KYB review completed successfully), the status will immediately change to the next one. Please note that a compliance check may take seconds for a personal identity or days for a business identity. Orchestrating - Borderless is preparing the necessary data and selecting the optimal PFI to execute the transaction. This process takes milliseconds. Pending - This status requires action from the user who initiated the transaction. For Deposit transactions, this status means that the PFI is waiting for the user to complete the fiat transfer (usually a bank transfer). For Withdrawal, Swap, or Transfer transactions, this status means that the PFI is waiting for an on-chain transaction to be completed. The execution time depends on the user, and the blockchain confirmation time. Processing - Funds have been received, and the transaction is being executed by a PFI. Failed - An error occurred during the transaction lifecycle. Details can be found in the failureReason via the API or on the transaction details page in the Borderless Dashboard. Cancelled - The transaction was canceled by the user. A transaction can only be canceled if it is in one of the following statuses: Submitted, Verifying, Preparing, or Pending. Once the transaction moves beyond these statuses, it cannot be canceled. For additional details, please contact our support team. Completed - The user has received the funds, and the transaction has been successfully completed. This status may update some time after the user has actually received the funds.
If you have any questions, please don’t hesitate to reach out to us via email or slack.