Skip to main content
Off-ramping is converting stablecoins into fiat currencies such as USD or BRL. This conversion is facilitated by the PFIs on the Borderless network and can be part of either a payin or payout flow simply depending on if you are sending or receiving the payments. In this scenario you are ultimately sending or receiving local fiat currencies, after the stablecoins are converted at the PFI.
An important note on payment instructions below.
Withdrawals are very similar to deposits as we’ve already accomplished above. The key difference to highlight, is around payment instructions. With deposits, the local fiat leg is to the PFI’s bank, and they provide the payment instructions in the api response when you open an order to deposit with them. For a withdrawal, the local fiat leg is ultimately received by you or your clients in the respective banks. This means, we need to instruct the partner financial institution (PFI) where to send the fiat leg, and you must provide these payment instructions. With this additional step in mind, withdrawals are a simple 4 step process. Optionally, you can also request a quote before initiating the withdrawal to have a transparent view of the estimated fees and exchange rates.
Quotes are returned directly from the PFIs, and are regularly changing. Quotes are not firm, and they do not guarantee any final received amount. They are estimates only, and Borderless is not responsible for incorrect quotes provided to us by PFIs.
Endpoint: GET /withdrawals/quotes
curl -X GET 'https://sandbox-api.borderless.xyz/v1/withdrawals/quotes' \
     -H 'Authorization: Bearer your-access-token' \
     -H 'Content-Type: application/json' \
     -d '{  
            "country": "US",
            "fiat": "USD",
            "asset": "USDC_POLYGON",
            "paymentMethod": "ACH",
			"fromAmount": "10"
        }'

​
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 of the matching amount of stablecoins. This alerts the PFI to expect the payment, and allows them to attribute the funds to your 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 capture the onchain instructions from the PFI in the response field onchainInstructionTransaction to use it to send stablecoins in the next step.
Please use both the account id from an 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": "USD",
  "country": "US",
  "asset": "BTC",
  "amount": "100.00",
  "accountId": "cm2c4x3cc000019stwv7um4zl",
  "developerFee": "5.00",
  "paymentInstructionId": "cm2c4x3cc000019stwv7um4zl",
  "paymentPurpose": "delivery fees",
  "purposeDescription": "string",
  "memo": "string"
}
'

​
Send stablecoins direct to PFI

Once the local fiat payment instructions are sent to the PFI, and the withdrawal request is made, this order will remain open until the PFI receives the stablecoins as outlined in the instructions they shared via response to the withdrawal request. At the time the stablecoins arrive, the PFI will send the local fiat transfer as defined in the payment instructions.
It is important to note that most PFIs match withdrawal orders with a combination of amount, from_account (stablecoin wallet), and deposit_address .Please ensure you are sending the stablecoins to the correct deposit address, on the correct blockchain, with the correct assets (i.e. USDC, USDT, etc.).It is also important that the stablecoins come from the same from_address that you shared with the PFI. If the PFI is told that stablecoins will come from and addres 0x…456 and then they arrive from 0x…987, this can result in potentially lost funds. Borderless will not provide refunds for stablecoins sent incorrectly.

​
Release local fiat to beneficiary

Finally, when the partner financial institution (PFI) receives the stablecoins, they will then 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 stablecoin withdrawal!
If you have any questions, please don’t hesitate to reach out to us via email or slack.