> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Cross-border payments
Enable customers to make cross-border payments to suppliers by creating a virtual account and wallet for each customer and an external account that stores a supplier’s bank details. Fiat deposits into the virtual account are converted to stablecoins and sent to the customer’s wallet. Use the Transfers API to convert the stablecoins to local currency and pay each supplier.
***
## Step 1: Generate your API Keys
Head over to [**dashboard.bridge.xyz**](https://dashboard.bridge.xyz/). Once logged in, click on the “API Keys” tab on the top menu bar and generate a new API key.
Bridge will make your **API key available only once**, so make sure to **immediately copy and save the key safely and securely**. \
\
Your key is used to authenticate into our APIs and is highly sensitive. If it ever gets compromised, you can immediately revoke key access from our dashboard and generate a new key.
## Step 2: Onboard a customer
Create a customer ID for each business that needs to pay suppliers. Customers will need to accept our terms of service and complete KYC.
Check out this [guide](/get-started/introduction/quick-start/create-your-first-customer) for a full in depth explanation on onboarding customers. The below example walks you through using a KYC link to onboard your customer.
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/kyc_links' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"full_name": "John Doe",
"email": "johndoe@example.com",
"type": "individual"
}'
```
```json Response theme={null}
{
"id": "uuid",
"full_name": "John Doe",
"email": "johndoe@example.com",
"type": "individual", // or "business"
"kyc_link": "https://bridge.withpersona.com/verify?",
"tos_link": "https://dashboard.bridge.xyz/accept-terms-of-service?",
"kyc_status": "not_started", // or "under_review", "incomplete", "approved" or "rejected"
"rejection_reasons": [],
"tos_status": "pending", // or "approved"
"created_at": "2025-07-16T18:28:25.970Z",
"customer_id": "customer_id",
"persona_inquiry_type": "gov_id_db"
}
```
Guide the user through:
1. Visiting the `tos_link` and accepting terms of service
2. Completing identity verification via the `kyc_link`
This process typically takes less than a minute and updates automatically once complete.
## Step 3: Create a wallet
Create a wallet for your customer to hold stablecoins and send supplier payments from.
The below example explains how to create a Bridge wallet associated with a customer object.
```bash Request theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/customers//wallets \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"chain": "solana"
}'
```
```json Response theme={null}
{
"id": "wallet_123",
"chain": "solana",
"address": "4oG1sWkP8vcrnhbkzZc1m9RTT2VUjZHKx92qiVFK7FuZ",
"created_at": "2025-07-15T18:00:00Z"
}
```
Use the `bridge_wallet_id` when referencing the wallet in other Bridge APIs.
Check out this [guide](/get-started/guides/wallets/overview) for more information on using Bridge wallets.
## Step 4: Create a virtual account
Create a USD or EUR account for the customer. Provide them with the bank instructions so they can deposit supplier payments. Deposits are converted to stablecoins and held in their wallet.
Use the [Virtual Accounts](/api-reference/virtual-accounts/create-a-virtual-account) API to provision permanent fiat deposit addresses for your customers. You define the `source` currency for the account and configure the `destination` to specify where Bridge should deliver the converted funds.
Bridge handles the fiat-to-crypto conversion and sends the funds on-chain automatically.
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
# The source object specifies a USD virtual account.
"source": {
"currency": "usd",
},
# The destination object instructs Bridge where to send the USD deposits to.
# Bridge will automatically handle converting and sending USD to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specifcy an optional developer fee to monetize on transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response theme={null}
{
"id": "1a400dae-f7fc-4f75-8105-212a14d4132d",
"status": "activated",
"developer_fee_percent": "1.0",
"customer_id": "23c2d200-4c00-4c5a-b31a-00d035d7e0ae",
"created_at": "2025-07-04T22:10:34.564Z",
"source_deposit_instructions": {
"currency": "usd",
"bank_name": "Lead Bank",
"bank_address": "1801 Main St., Kansas City, MO 64108",
"bank_routing_number": "101019644",
"bank_account_number": "215268120000",
"bank_beneficiary_name": "Ada Lovelace",
"bank_beneficiary_address": "923 Folsom Street, 302, San Francisco, California 941070000, US",
"payment_rail": "ach_push",
"payment_rails": [
"ach_push",
"wire"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be"
}
}
```
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
# The source object specifies a SEPA virtual IBAN.
"source": {
"currency": "eur",
},
# The destination object instructs Bridge where to send the EURO deposits to.
# Bridge will automatically handle converting and sending EURO to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specifcy an optional developer fee to monetize on transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response theme={null}
{
"id": "393c6358-4c19-4cb7-bbfa-d4a56be58309",
"status": "activated",
"developer_fee_percent": "1.0",
"customer_id": "23c2d200-4c00-4c5a-b31a-00d035d7e0ae",
"created_at": "2025-07-04T22:07:18.701Z",
"source_deposit_instructions": {
"currency": "eur",
"iban": "IE90MODR14035307970528",
"bic": "MODRIE00XXX",
"account_holder_name": "Bridge Building Sp.z.o.o.",
"bank_name": "Modulr Finance, Ireland Branch",
"bank_address": "Floor 6, 2 Grand Canal Square, Dublin, Ireland",
"payment_rail": "sepa",
"payment_rails": [
"sepa"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be"
}
}
```
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
# The source object specifies a MXN virtual account.
"source": {
"currency": "mxn",
},
# The destination object instructs Bridge where to send the MXN deposits to.
# Bridge will automatically handle converting and sending MXN to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specifcy an optional developer fee to monetize on transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response theme={null}
{
"id": "35334433-dcee-48e8-bdc8-90171234ad00",
"status": "activated",
"developer_fee_percent": "1.0",
"customer_id": "23c2d200-4c00-4c5a-b31a-00d035d7e0ae",
"created_at": "2025-07-04T22:13:29.481Z",
"source_deposit_instructions": {
"currency": "mxn",
"clabe": "568980546701071234",
"account_holder_name": "Ada Lovelace",
"payment_rails": [
"spei"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be"
}
}
```
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"source": {
"currency": "brl",
},
# The destination object instructs Bridge where to send the BRL deposits to.
# Bridge will automatically handle converting and sending USDC to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specify an optional developer fee to monetize transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response theme={null}
{
"id": "6e6ab621-6749-401f-b598-0c709c241696",
"status": "activated",
"developer_fee_percent": "0.0",
"customer_id": "eeafff4b-2dbe-41f2-9444-a6e228aee975",
"created_at": "2025-09-03T16:10:31.446Z",
"source_deposit_instructions": {
"currency": "brl",
"br_code": "00020126770014br.gov.bcb.pix01366e6ab621-6749-401f-b598-0c709c2416960215Edson_Arantes5204000053039865802BR5914Bridge_Example6009Sao_Paulo622905256beca3e77fdd489289aa1daeb630416E9",
"account_holder_name": "Edson Arantes do Nascimento",
"payment_rails": [
"pix"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
}
}
```
```bash Request theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"source": {
"currency": "gbp",
},
# The destination object instructs Bridge where to send the GBP deposits to.
# Bridge will automatically handle converting and sending USDC to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specify an optional developer fee to monetize transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response theme={null}
{
"id": "6e6ab621-6749-401f-b598-0c709c241696",
"status": "activated",
"developer_fee_percent": "0.0",
"customer_id": "485c2b50-949c-412b-928a-f56fce42330d",
"created_at": "2026-01-03T00:23:23.724Z",
"source_deposit_instructions": {
"currency": "brl",
"account_number": "12345678",
"sort_code": "123456",
"account_holder_name": "Bridge Building Sp. Z.o.o.",
"bank_name": "Banking Circle S.A.",
"bank_address": "2 Boulevard de la Foire, L-1528 Luxembourg",
"bank_beneficiary_name": "Bridge Building Sp. Z.o.o.",
"bank_beneficiary_address": "2 Boulevard de la Foire, L-1528 Luxembourg",
"payment_rails": [
"faster_payments"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
}
}
```
### Sharing Deposit Instructions
Once a Virtual Account is created, use the `source_deposit_instructions` object in the response to share the fiat deposit details with your customer. Funds sent to those details will be automatically converted and delivered to the crypto destination you specified.
## Step 5: Create an external account
Add and store a supplier's bank account details to send payments from the customer.
You can add external fiat accounts through our [External account API](/api-reference/external-accounts/create-a-new-external-account) using the following request.
```bash Request expandable theme={null}
curl --location 'https://api.bridge.xyz/v0/customers//external_accounts' \
--header 'Idempotency-Key: ea-7' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Api-Key: ' \
--data '{
"currency": "usd",
"account_type": "us",
"bank_name": "Lead Bank",
"account_name": "Ada Checking Account",
"first_name": "Ada",
"last_name": "Lovelace",
"account_owner_type": "individual", // specifies an individual account
"account_owner_name": "Ada Lovelace",
"account": {
"routing_number": "101019644",
"account_number": "215268129123",
"checking_or_savings": "checking"
},
"address": {
"street_line_1": "923 Folsom Street",
"country": "USA",
"state": "CA",
"city": "San Francisco",
"postal_code": "941070000"
}
}'
```
```json Response expandable theme={null}
{
"id": "external-account-123", // external account id
"customer_id": "23c2d462-4c69-4c5a-b31a-88d035d7e8ae",
"created_at": "2025-07-05T19:03:50.819Z",
"updated_at": "2025-07-05T19:03:51.251Z",
"bank_name": "Lead Bank",
"account_name": "Ada Checking Account",
"account_owner_name": "Ada Lovelace",
"active": true,
"currency": "usd",
"account_owner_type": "individual",
"account_type": "us",
"first_name": "Ada",
"last_name": "Lovelace",
"business_name": null,
"account": {
"last_4": "9123",
"routing_number": "101019644",
"checking_or_savings": "checking"
},
"beneficiary_address_valid": true,
"last_4": "9123"
}
```
```bash Request expandable theme={null}
curl --location 'https://api.bridge.xyz/v0/customers//external_accounts' \
--header 'Idempotency-Key: ea-7' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Api-Key: ' \
--data '{
"currency": "eur",
"account_type": "iban",
"bank_name": "Modulr Finance, Ireland Branch",
"account_name": "GGCF Corporate",
"first_name": "Ada",
"last_name": "Lovelace",
"iban": {
"account_number": "IE04MODR99035512826162",
"country": "IRL",
"bic": "MODRIE22XXX"
},
"address": {
"street_line_1": "Floor 6, 2 Grand Canal Square, Dublin, Ireland",
"country": "IRL",
"city": "Dublin",
"postal_code": "D02 A342"
}
}'
```
```curl Response theme={null}
{
"id": "c8948ce6-26ac-4d37-a336-742f961a76f3",
"customer_id": "23c2d400-4c69-4c5a-b31a-88d035d7e8ae",
"created_at": "2025-07-05T18:45:50.728Z",
"updated_at": "2025-07-05T18:45:51.373Z",
"bank_name": "Modulr Finance, Ireland Branch",
"account_name": "GGCF Corporate",
"account_owner_name": "Ada Lovelace",
"active": true,
"currency": "eur",
"account_owner_type": "individual",
"account_type": "iban",
"first_name": "Ada",
"last_name": "Lovelace",
"business_name": null,
"iban": {
"last_4": "6162",
"bic": "MODRIE22XXX",
"country": "IRL"
}
}
```
```bash Request expandable theme={null}
curl --location 'https://api.bridge.xyz/v0/customers/23c2d462-4c69-4c5a-b31a-88d035d7e8ae/external_accounts' \
--header 'Idempotency-Key: ea-6' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Api-Key: ' \
--data '{
"currency": "mxn",
"account_type": "clabe",
"account_owner_name": "Ada Lovelace",
"clabe": {
"account_number": "626899715090851234"
},
"account_name": "Ada Checking Account",
"bank_name": "BBVA Bancomer",
"first_name": "Ada",
"last_name": "Lovelace",
"account_owner_type": "individual",
"address": {
"street_line_1": "Av. Reforma",
"city": "Mexico City",
"state": "CDMX",
"postal_code": "06600",
"country": "MEX"
}
}'
```
```json Response expandable theme={null}
{
"id": "2bb5b814-0128-49a8-977a-77b1bc1cdee2",
"customer_id": "23c2d462-4c69-4c5a-b31a-88d035d7e8ae",
"created_at": "2025-07-05T18:59:42.163Z",
"updated_at": "2025-07-05T18:59:42.713Z",
"bank_name": "BBVA Bancomer",
"account_name": "Ada Checking Account",
"account_owner_name": "Ada Lovelace",
"active": true,
"currency": "mxn",
"account_owner_type": "individual",
"account_type": "clabe",
"first_name": "Ada",
"last_name": "Lovelace",
"business_name": null,
"clabe": {
"last_4": "1234"
}
}
```
## Step 5: Make a payment
Use the Transfers API to move funds from the customer’s wallet to a supplier’s bank account. You will need to call the API for each payment.
```bash Request expandable theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"amount": "10.0",
"on_behalf_of": "",
"developer_fee": "0.5",
"source": {
"payment_rail": "bridge_wallet",
"currency": "usdb",
"bridge_wallet_id": "wallet_123"
},
"destination": {
"payment_rail": "ach",
"currency": "usd",
"external_account_id": "external-account-123"
},
}'
```