Skip to main content
Withdrawals (Balances) all you to move local fiat balances out of a PFI Account to an external bank account of your beneficiary. PFI Accounts were described in detail in the Accounts section above, but at a high level they represent local fiat balances that your organization holds with a specific partner financial institution (PFI). Withdrawals (Balances) are very similar to Withdrawals (Off-ramps), described above, but with a few important differences. Withdrawals (Off-ramps) convert stablecoins held on your Web3 account into local fiat currencies (for example, USDC_POLYGON to BRL in a Brazilian bank account) through one of our off-ramp PFIs. In this flow, you first create a withdrawal order, receive on-chain payment instructions, and then send stablecoins on-chain to the PFI. Withdrawals (Balances), on the other hand, do not involve any on-chain transfer. Instead, they use the existing fiat balance that you already have on a PFI Account. For example, you can withdraw COP from a PFI Account and send it directly to a beneficiary’s COP bank account. In this case, the PFI simply debits your PFI Account and initiates a local payout to the payment instructions that you provide. And it has just 3 simple steps.

​
Create payment instruction

First, create payment instructions to share with the partner financial institution (PFI) who is off-ramping or processing your withdrawal. This step is critical to ensure the local fiat currency arrives in the correct account at the end.
Please use account id in the deposit creation request from an account created above in the Accounts section.
Please capture payment instructions id from the response to use it for the withdrawal request after.
The PFI will be initiating the off-ramp directly to the payment instructions you create in this step. Borderless cannot be held responsible for transfers that originate outside the Borderless network to incorrect addresses. It is your responsibility to review the payment instructions and ensure they are correct.
Endpoint: POST /identities/{id}/payment-instructions
curl -X POST 'https://sandbox-api.borderless.xyz/v1/identities/{id}/payment-instructions' \
      -H 'Authorization: Bearer your-access-token' \
      -H 'Content-Type: application/json' \
    -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
      -d '{
        "country": "US",
        "currency": "USD",
        "name": "Primary Bank Account",
        "paymentMethod": "ACH",
          "details": {
            "bankName": "Example Bank",
            "accountHolderName": "John Doe",
            "bankAccountNumber": "123456789012",
            "bankRoutingNumber": "123456789",
            "bankAccountType": "Checking",
            "address": {
                "street1": "123 Main St",
                "street2": "Apt 4B",
                "city": "New York",
                "state": "NY",
                "country": "US",
                "postalCode": "10001"
              }
            }
    }'

​
Create a withdrawal order

Second, you will create an order for a withdrawal. This will send the payment instructions to the PFI, who will send the local fiat currency upon receipt. This alerts the PFI to expect the payment, and allows them to attribute the funds to your bank account when they arrive. It’s important to note that in the response to this withdrawal order, the PFI will return the onchain stablecoin payment instructions (generally a deposit address) that will handle the stablecoins which are being off-ramped.
Please use both the account id from an PFI Account created above in the Accounts section, and the payment instructions id in the withdrawal creation request from the step above where you created the payment instructions.
Endpoint: POST /withdrawals 
curl -X POST 'https://sandbox-api.borderless.xyz/v1/withdrawals' \
      -H 'Authorization: Bearer your-access-token' \
      -H 'Content-Type: application/json' \
    -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
      -d '
{
  "fiat": "COP",
  "country": "CO",
  "amount": "100.00",
  "accountId": "cm2c4x3cc000019stwv7um4zl",
  "paymentInstructionId": "cm2c4x3cc000019stwv7um4zl",
  "paymentPurpose": "delivery fees",
  "purposeDescription": "string",
  "memo": "string"
}
'

​
Release local fiat to beneficiary

Finally, PFI provider will issue the local fiat payment to the bank defined in the payment instructions. Once the local fiat currency is received, this completes the off-ramp or withdrawal flow. You can easily track the status of transactions, request cancellation of transactions, and export transactions with the following endpoints.
Please ensure you are using the transaction id value which you will receive from the request to create a transaction such as the first step in this sequence on the /withdrawals endpoint.
To track the status of your withdrawal transactions and other types of transactions:
We recommend listening to the statuses via Webhook.
Endpoint: GET /transactions/{id}
To request a cancellation of your withdrawal transaction and other types of transactions:
Endpoint: POST /transactions/{id}/cancel
To export your transactions:
Endpoint: GET /transactions/export
Congratulations! You’ve now completed your first fiat withdrawal!
If you have any questions, please don’t hesitate to reach out to us via email or slack.