Skip to main content
POST
/
v1
/
withdrawals
Create a new Withdrawal transaction
curl --request POST \
  --url https://sandbox-api.borderless.xyz/v1/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.00",
  "accountId": "cm2c4x3cc000019stwv7um4zl",
  "paymentInstructionId": "cm2c4x3cc000019stwv7um4zl",
  "paymentPurpose": "delivery fees",
  "asset": "BTC",
  "developerFee": "5.00",
  "counterPartyIdentityId": "cm2c4x3cc000019stwv7um4zl",
  "purposeDescription": "<string>",
  "reference": "<string>",
  "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "documents": [
    {
      "type": "Invoice",
      "content": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }
  ],
  "fiat": "USD",
  "country": "AF"
}
'
{
  "id": "<string>",
  "type": "Deposit",
  "status": "Submitted",
  "pfiName": "Bridge",
  "country": "AF",
  "source": {
    "asset": "POL",
    "amount": "<string>",
    "fiatCurrency": "<string>",
    "paymentMethod": "ACH",
    "accountId": "<string>",
    "accountName": "<string>",
    "sender": {
      "name": "<string>",
      "legalName": "<string>",
      "description": "<string>",
      "taxIdLast4": "<string>",
      "bankName": "<string>",
      "bankRoutingNumberLast4": "<string>",
      "bankAccountNumberLast4": "<string>",
      "accountNumberLast4": "<string>",
      "traceNumber": "<string>",
      "originatorName": "<string>",
      "beneficiaryName": "<string>",
      "wireMessage": "<string>",
      "imad": "<string>",
      "iban": "<string>",
      "ibanLast4": "<string>",
      "bic": "<string>",
      "sortCode": "<string>",
      "clabe": "<string>",
      "trackingNumber": "<string>",
      "reference": "<string>",
      "uetr": "<string>",
      "paymentScheme": "<string>",
      "recipientName": "<string>"
    }
  },
  "destination": {
    "asset": "POL",
    "amount": "<string>",
    "fiatCurrency": "<string>",
    "imad": "<string>",
    "reference": "<string>",
    "omad": "<string>",
    "traceNumber": "<string>",
    "externalAddress": "<string>",
    "accountId": "<string>",
    "accountName": "<string>",
    "paymentInstructionId": "<string>"
  },
  "instructions": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "txHash": [
    "<string>"
  ],
  "feeAmount": {},
  "failureReason": {
    "details": [
      {
        "path": "paymentInstruction",
        "pfiErrorMessage": "bank.transitNumber must match /^([0-9]{3}-[0-9]{5}|[0-9]{5}-[0-9]{3})$/ regular expression"
      }
    ],
    "message": "Validation error from PFI"
  },
  "depositInstruction": {
    "paymentMethod": "ACH",
    "details": {
      "depositMessage": "<string>",
      "bankAccountNumber": "<string>",
      "bankRoutingNumber": "<string>",
      "bankBeneficiaryName": "<string>",
      "bankBeneficiaryAddress": "<string>",
      "bankName": "<string>",
      "bankAddress": "<string>",
      "bic": "<string>"
    }
  },
  "destinationPaymentInstruction": {
    "id": "<string>",
    "name": "<string>",
    "paymentMethod": "ACH",
    "currency": "USD",
    "country": "US",
    "deleted": false,
    "details": {
      "bankName": "Chase",
      "bankSlug": "Chase",
      "bankAccountNumberLast4": "7890",
      "bankRoutingNumber": "021000021",
      "bankCode": "40006",
      "phone": "<string>",
      "taxId": "<string>",
      "accountHolderName": "John Doe",
      "bankAccountType": "Checking",
      "recipientRelationship": "first party",
      "address": {
        "id": "<string>",
        "street1": "<string>",
        "street2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "AF",
        "postalCode": "<string>"
      }
    }
  },
  "withdrawalOnchainInstruction": {
    "id": "<string>",
    "amount": "100.00",
    "asset": "BTC",
    "fromAddress": "<string>",
    "toAddress": "<string>",
    "spenderAddress": "<string>",
    "type": "Transfer",
    "onchainInstructionTransaction": {
      "id": "<string>",
      "to": "<string>",
      "from": "<string>",
      "data": "<string>",
      "nonce": "<string>",
      "value": "<string>",
      "chainId": 123,
      "gasLimit": "<string>",
      "gasPrice": "<string>",
      "fee": "<string>",
      "unsignedTx": "<string>",
      "psbt": "<string>",
      "inputs": {},
      "outputs": {},
      "walletId": "<string>",
      "body": {},
      "visible": true,
      "txID": "<string>",
      "rawData": {},
      "rawDataHex": "<string>",
      "spender": "<string>",
      "mint": "<string>"
    }
  },
  "counterPartyIdentityId": "<string>",
  "virtualAccountId": "<string>",
  "reconciliationStatus": "Matched",
  "rateGrade": "Competitive",
  "rateStatus": "Classified",
  "rateConfidenceTier": "Strong",
  "developerFeeAmount": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.borderless.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
amount
string
required

The amount for the operation. For deposits, this is the fiat amount the user must contribute. For withdrawals, this is the amount of the asset to be withdrawn.

Example:

"100.00"

​
accountId
string
required

The id of the account associated with the operation. For withdrawals, this is the account from which assets will be withdrawn. For deposits, this is the account where assets will be deposited.

Example:

"cm2c4x3cc000019stwv7um4zl"

​
paymentInstructionId
string
required

The ID of the payment instruction specifying how the withdrawn funds will be sent. Learn more at Payment Instructions Guide

Example:

"cm2c4x3cc000019stwv7um4zl"

​
paymentPurpose
enum<string>
required

The purpose of the withdrawal payment.

Available options:
salary payment,
personal remittance,
rent payment,
property purchase,
owned account abroad,
advertising expenses,
advisory fees,
business insurance,
construction,
delivery fees,
education,
exports,
donation,
hotel,
loan payment,
maintenance expenses,
medical expense,
office expenses,
royalty fees,
service charge,
shares investment,
tax payment,
transportation fees,
travel,
utility bills,
other
Example:

"delivery fees"

​
asset
enum<string>
required

The token tied to a specific blockchain for the withdrawal. See the list of supported Withdrawal Assets.

Available options:
POL,
USDT_POLYGON,
USDC_POLYGON,
SBC_POLYGON,
ETH,
USDT_ETHEREUM,
USDC_ETHEREUM,
PYUSD_ETHEREUM,
DAI_ETHEREUM,
SBC_ETHEREUM,
TRX,
USDT_TRON,
SBC_TRON,
ETH_BASE,
USDC_BASE,
USDB_BASE,
EURC_BASE,
SBC_BASE,
ETH_OPTIMISM,
USDT_OPTIMISM,
USDC_OPTIMISM,
BTC,
CELO,
CUSD_CELO,
USDC_CELO,
SBC_CELO,
SOL,
USDC_SOLANA,
USDT_SOLANA,
PYUSD_SOLANA,
USDP_SOLANA,
EURC_SOLANA,
SBC_SOLANA
Example:

"BTC"

​
developerFee
string

An optional developer fee for the operation, if applicable

Example:

"5.00"

​
counterPartyIdentityId
string

The ID of the identity on whose behalf the withdraw is being initiated. If not specified, the withdrawal will be initiated for the identity tied to the payment instruction by default.

Example:

"cm2c4x3cc000019stwv7um4zl"

​
purposeDescription
string

Purpose details.

Minimum string length: 255
​
reference
string

A reference message to be sent with a Bank transaction.

Required string length: 1 - 256
​
refundAddress
string

A crypto address where funds should be returned in case the withdrawal fails or is rejected. Supported by select payment providers (e.g., Bridge, Walapay). If not provided, manual coordination may be required for refunds.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
documents
object[]

Documents may be required by certain countries or payment providers (for example, an invoice, contract, or agreement)

​
fiat
enum<string>
deprecated

Deprecated: resolved automatically from the payment instruction. The fiat currency used for the withdrawal operation.

Available options:
USD,
EUR,
BRL,
ARS,
MXN,
COP,
CLP,
PEN,
PYG,
DOP,
UYU,
BOB,
CRC,
GTQ,
BWP,
CDF,
GHS,
KES,
MWK,
NGN,
RWF,
ZAR,
TZS,
UGX,
ZMW,
XOF,
XAF,
AUD,
BDT,
CAD,
INR,
JPY,
NPR,
PKR,
PHP,
SGD,
GBP,
CNY,
HKD,
IDR,
MYR,
KRW,
LKR,
THB,
TRY,
VND,
CZK,
DKK,
NOK,
PLN,
RON,
RSD,
SEK,
CHF,
AED,
SAR,
QAR,
ILS,
EGP,
JOD,
HNL,
JMD,
NZD,
DZD,
GMD,
GNF,
HTG,
MAD,
TND
​
country
enum<string>
deprecated

Deprecated: resolved automatically from the payment instruction. The country code for the region where the withdrawal is performed.

Available options:
AF,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CD,
CG,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
MK,
RO,
RU,
RW,
RE,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
UM,
US,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
AX

Response

Successfully created Withdrawal transaction data.

​
id
string
required
​
type
enum<string>
required
Available options:
Deposit,
Withdrawal,
Exchange
​
status
enum<string>
required
Available options:
Submitted,
Verifying,
Orchestrating,
Pending,
Processing,
Completed,
Failed,
Cancelled,
Refunded
​
pfiName
enum<string>
required
Available options:
Bridge,
Koywe,
Kotanipay,
Hercle,
Bitso,
Yellowcard,
TraceFinance,
HoneyCoin,
BlindPay,
Finity,
Infinia,
Walapay,
Abra,
Yativo,
Capa,
Bivo,
Cobre,
Avenia,
Brale,
BVNK,
CoinsPH,
Iron,
Enigma,
Juicyway,
Kira,
TripleA,
Onmeta
​
country
enum<string>
required
Available options:
AF,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CD,
CG,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
MK,
RO,
RU,
RW,
RE,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
UM,
US,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
AX
​
source
object
required
​
destination
object
required
​
instructions
object
required
deprecated

Deprecated. Use withdrawalOnchainInstruction or depositInstruction instead.

​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required
​
txHash
string[]
required
​
feeAmount
object
required
​
failureReason
object
required
Example:
{
  "details": [
    {
      "path": "paymentInstruction",
      "pfiErrorMessage": "bank.transitNumber must match /^([0-9]{3}-[0-9]{5}|[0-9]{5}-[0-9]{3})$/ regular expression"
    }
  ],
  "message": "Validation error from PFI"
}
​
depositInstruction
object
required
​
destinationPaymentInstruction
object
required
​
withdrawalOnchainInstruction
object
required
​
counterPartyIdentityId
string | null
required
​
virtualAccountId
string | null
required
​
reconciliationStatus
enum<string>
required
Available options:
Matched,
Mismatched,
Missing,
PfiError
​
rateGrade
enum<string>
required
Available options:
Competitive,
InLine,
OffMarket
​
rateStatus
enum<string>
required
Available options:
Classified,
Calibrating,
Stale,
NoRateProduced,
Syncing
​
rateConfidenceTier
enum<string>
required
Available options:
Strong,
Standard
​
developerFeeAmount
object
required