Direct Bank Transfer

The Create Direct Bank Transfer endpoint enables you to initiate fiat-to-stablecoin transfers where funds are sent from traditional bank accounts (via ACH, Wire, or SEPA) directly into one of your Devdraft wallets.

This endpoint creates bank transfer instructions that provide source deposit instructions for bank-based funding.

Endpoint DetailsCopied!

Method: POST
URL: /api/v0/transfers/direct-bank
Content-Type: application/json

AuthenticationCopied!

This endpoint requires API key authentication using both:

x-client-key: Your application's client key
x-client-secret: Your application's client secret

Request BodyCopied!

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "paymentRail": "ach",
  "destinationCurrency": "usdc",
  "sourceCurrency": "usd",
  "amount": 1000.50,
  "ach_reference": "PAY123456",
  "wire_message": "Payment for services",
  "sepa_reference": "INV-2024-001"
}

Parameters

Parameter	Type	Required	Description
`walletId`	string	Yes	The ID of your Bridge wallet to receive the transfer
`paymentRail`	string	Yes	Bank payment method (`ach`, `ach_push`, `ach_same_day`, `wire`, `sepa`)
`destinationCurrency`	string	Yes	Target stablecoin currency (`usdc`, `eurc`)
`sourceCurrency`	string	No	Source fiat currency (default: `usd`)
`amount`	number	Yes	Transfer amount in source currency
`wire_message`	string	No	Message for wire transfers (max 256 chars)
`ach_reference`	string	No	ACH reference code (alphanumeric + spaces, max 10 chars)
`sepa_reference`	string	No	SEPA reference (alphanumeric + special chars, 6-140 chars)

Supported Payment Rails

US-Based Payment Rails

ACH (ach) - Standard ACH transfer (1-3 business days)
ACH Push (ach_push) - ACH push payment (same day processing)
ACH Same Day (ach_same_day) - Same-day ACH transfer
Wire (wire) - Wire transfer (same day, higher fees)

European Payment Rails

SEPA (sepa) - Single Euro Payments Area transfer

Supported Currency Pairs

Source Currency	Destination Currency	Payment Rails
USD	USDC	`ach`, `ach_push`, `ach_same_day`, `wire`
USD	EURC	`ach`, `ach_push`, `ach_same_day`, `wire`
EUR	USDC	`sepa`
EUR	EURC	`sepa`

Reference Field Validation

ACH Reference (`ach_reference`)

Format: Alphanumeric characters and spaces only
Length: Maximum 10 characters
Pattern: ^[a-zA-Z0-9 ]+$
Example: PAY123456

SEPA Reference (`sepa_reference`)

Format: Letters, numbers, spaces, &, -, ., /
Length: 6-140 characters
Pattern: ^[a-zA-Z0-9&\-.\/ ]+$
Example: INV-2024-001/REF

Wire Message (`wire_message`)

Format: Free text
Length: Maximum 256 characters
Example: Payment for Invoice #12345

ResponseCopied!

Success Response (201 Created)

{
  "id": "tr_bank_1234567890abcdef",
  "state": "awaiting_funds",
  "amount": "1000.50",
  "developer_fee": "200.10",
  "on_behalf_of": "cus_bridge123abc",
  "source": {
    "payment_rail": "ach",
    "currency": "usd",
    "to_address": null,
    "external_account_id": null
  },
  "destination": {
    "payment_rail": "base",
    "currency": "usdc",
    "to_address": "0x742d35Cc6Ff82a8C2D8D1Da9da17c7eDfD5bE0a3",
    "external_account_id": null
  },
  "source_deposit_instructions": {
    "payment_rail": "ach",
    "currency": "usd",
    "amount": "1000.50",
    "deposit_message": "Transfer ID: tr_bank_1234567890abcdef",
    "bank_name": "JPMorgan Chase Bank, N.A.",
    "bank_address": "270 Park Avenue, New York, NY 10017, United States",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890123456",
    "bank_beneficiary_name": "Bridge Network Inc",
    "bank_beneficiary_address": "123 Bridge Street, San Francisco, CA 94105",
    "to_address": null,
    "from_address": null
  },
  "receipt": null,
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}

Response Fields

Main Transfer Object

Field	Type	Description
`id`	string	Unique transfer identifier
`state`	string	Transfer state (`awaiting_funds`, `processing`, `completed`, `failed`)
`amount`	string	Transfer amount in source currency
`developer_fee`	string	Developer fee amount (20% of transfer amount)
`on_behalf_of`	string	Bridge customer ID
`source`	object	Source payment rail information
`destination`	object	Destination wallet information
`source_deposit_instructions`	object	Critical: Bank deposit instructions
`receipt`	object	Transfer receipt (available when completed)
`created_at`	string	Transfer creation timestamp
`updated_at`	string	Last update timestamp

Understanding Source Deposit InstructionsCopied!

The source_deposit_instructions object contains the complete bank information that the sender needs to initiate the bank transfer.

Bank Deposit Instructions Structure

{
  "source_deposit_instructions": {
    "payment_rail": "ach",
    "currency": "usd", 
    "amount": "1000.50",
    "deposit_message": "Transfer ID: tr_bank_1234567890abcdef",
    "bank_name": "JPMorgan Chase Bank, N.A.",
    "bank_address": "270 Park Avenue, New York, NY 10017, United States",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890123456",
    "bank_beneficiary_name": "Bridge Network Inc",
    "bank_beneficiary_address": "123 Bridge Street, San Francisco, CA 94105"
  }
}

Critical Bank Information Fields

Field	Description	Usage
`bank_name`	Receiving bank name	Primary bank identifier
`bank_routing_number`	ABA routing number (US) or SWIFT/BIC (International)	Required for all transfers
`bank_account_number`	Destination account number	Where funds must be sent
`bank_beneficiary_name`	Account holder name	Must match exactly on transfer
`bank_beneficiary_address`	Beneficiary address	Required for wire transfers
`deposit_message`	Transfer reference	CRITICAL: Must be included in transfer memo/reference
`amount`	Exact amount to send	Must send this exact amount
`currency`	Source currency	Currency to send from bank account

How Bank Deposit Instructions WorkCopied!

1. Transfer Setup

When you create a direct bank transfer:

System generates unique bank account details for this transfer
Creates detailed deposit instructions for the sender
Sets up monitoring for incoming bank transfers

2. Sender Bank Transfer Process

The sender must initiate a bank transfer with:

Recipient Bank: Use provided bank_name and bank_address
Routing Number: Use bank_routing_number for US transfers
Account Number: Send TO the provided bank_account_number
Beneficiary: Exact bank_beneficiary_name and address
Amount: Exact amount in specified currency
Reference/Memo: MUST include the deposit_message

3. Automatic Processing

Once the bank transfer is received:

System detects incoming funds using the reference ID
Automatically converts fiat to requested stablecoin
Transfers converted funds to your destination wallet
Updates transfer state to completed
Provides final receipt with conversion rates and fees

Transfer Processing TimelineCopied!

Payment Rail	Processing Time	Business Hours	Settlement
`ach`	1-3 business days	Mon-Fri 9AM-5PM ET	T+1 to T+3
`ach_push`	Same day	Mon-Fri by 2PM ET	Same day
`ach_same_day`	Same day	Mon-Fri by 5PM ET	Same day
`wire`	Same day	Mon-Fri 9AM-6PM ET	Same day
`sepa`	Same day	Mon-Fri 8AM-6PM CET	Same day

Transfer StatesCopied!

State	Description	Timeline	Next Action
`awaiting_funds`	Waiting for bank transfer	Immediate	Provide deposit instructions to sender
`funds_received`	Bank transfer detected	1-60 minutes	System processing conversion
`in_review`	Compliance review (if required)	2-24 hours	Wait for approval
`payment_submitted`	Converting to stablecoin	5-30 minutes	Wait for blockchain confirmation
`payment_processed`	Stablecoin transfer submitted	1-10 minutes	Wait for final confirmation
`completed`	Transfer successful	N/A	Check receipt for final amounts
`failed`	Transfer failed	N/A	Check failure reason

Example RequestsCopied!

ACH Transfer

curl -X POST "https://api.yourplatform.com/api/v0/transfers/direct-bank" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentRail": "ach",
    "destinationCurrency": "usdc",
    "sourceCurrency": "usd",
    "amount": 1000.50,
    "ach_reference": "PAY123456"
  }'

Wire Transfer

curl -X POST "https://api.yourplatform.com/api/v0/transfers/direct-bank" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentRail": "wire",
    "destinationCurrency": "usdc",
    "sourceCurrency": "usd",
    "amount": 5000.00,
    "wire_message": "Payment for Invoice #12345"
  }'

SEPA Transfer

curl -X POST "https://api.yourplatform.com/api/v0/transfers/direct-bank" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentRail": "sepa",
    "destinationCurrency": "eurc",
    "sourceCurrency": "eur",
    "amount": 2500.75,
    "sepa_reference": "INV-2024-001/REF"
  }'

JavaScript (Node.js)

const transferData = {
  walletId: '550e8400-e29b-41d4-a716-446655440000',
  paymentRail: 'ach',
  destinationCurrency: 'usdc',
  sourceCurrency: 'usd',
  amount: 1000.50,
  ach_reference: 'PAY123456'
};

const response = await fetch('https://api.yourplatform.com/api/v0/transfers/direct-bank', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-key': 'your_client_key_here',
    'x-client-secret': 'your_client_secret_here'
  },
  body: JSON.stringify(transferData)
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const transfer = await response.json();

// Extract bank instructions for the sender
const instructions = transfer.source_deposit_instructions;

console.log('=== BANK TRANSFER INSTRUCTIONS ===');
console.log(`Send ${instructions.amount} ${instructions.currency.toUpperCase()}`);
console.log(`Bank Name: ${instructions.bank_name}`);
console.log(`Routing Number: ${instructions.bank_routing_number}`);
console.log(`Account Number: ${instructions.bank_account_number}`);
console.log(`Beneficiary: ${instructions.bank_beneficiary_name}`);
console.log(`CRITICAL - Include Reference: ${instructions.deposit_message}`);

Python

import requests
import json

url = "https://api.yourplatform.com/api/v0/transfers/direct-bank"
headers = {
    'Content-Type': 'application/json',
    'x-client-key': 'your_client_key_here',
    'x-client-secret': 'your_client_secret_here'
}

data = {
    'walletId': '550e8400-e29b-41d4-a716-446655440000',
    'paymentRail': 'wire',
    'destinationCurrency': 'usdc',
    'sourceCurrency': 'usd',
    'amount': 5000.00,
    'wire_message': 'Payment for Invoice #12345'
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 201:
    transfer = response.json()
    instructions = transfer['source_deposit_instructions']
    
    print("=== WIRE TRANSFER INSTRUCTIONS ===")
    print(f"Send: {instructions['amount']} {instructions['currency'].upper()}")
    print(f"Bank: {instructions['bank_name']}")
    print(f"Address: {instructions['bank_address']}")
    print(f"Routing: {instructions['bank_routing_number']}")
    print(f"Account: {instructions['bank_account_number']}")
    print(f"Beneficiary: {instructions['bank_beneficiary_name']}")
    print(f"CRITICAL Reference: {instructions['deposit_message']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Error ResponsesCopied!

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid payment rail for source currency",
  "error": "Bad Request"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Bridge wallet not found with ID: 550e8400-e29b-41d4-a716-446655440000",
  "error": "Not Found"
}

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "SEPA transfers require EUR source currency",
  "error": "Unprocessable Entity"
}

Validation Errors

{
  "statusCode": 400,
  "message": [
    "ach_reference can only contain A-Z, a-z, 0-9, and spaces",
    "sepa_reference must be at least 6 characters long"
  ],
  "error": "Bad Request"
}

Fee StructureCopied!

Developer Fees

0.6% developer fee applied to all transfers
Fee calculated on the total transfer amount
Example: $1000 transfer = $200 developer fee

Bank Processing Fees

Payment Rail	Typical Bank Fee	Processing Speed
ACH	$0-3	1-3 business days
ACH Same Day	$5-10	Same day
Wire (Domestic)	$15-30	Same day
Wire (International)	$40-80	Same day
SEPA	€0-5	Same day

Important NotesCopied!

Critical Reference Requirements

deposit_message is MANDATORY - Without this reference, funds cannot be matched to your transfer
Each transfer generates a unique reference ID
Bank transfers without proper reference will be rejected or delayed

Currency Conversion

Real-time exchange rates applied at time of processing
Rates include Bridge's conversion spread
Final amount may vary slightly from estimate due to rate fluctuations

Compliance & KYC

Large transfers may require additional compliance review
Business verification may be required for first transfers
Some transfers may be held for AML screening

Cut-off Times

Each payment rail has specific cut-off times:

ACH: Generally 5PM ET
ACH Same Day: 2PM ET
Wire: 6PM ET (varies by bank)
SEPA: 6PM CET

Use CasesCopied!

Business Payments: Receive payments from customers via bank transfer
Invoice Payments: Convert traditional invoicing to stablecoin settlement
Payroll Funding: Fund stablecoin payroll from company bank accounts
International Remittances: Cross-border transfers via stablecoins
Marketplace Settlements: Traditional bank to crypto settlement

Monitoring Transfer StatusCopied!

Webhook Events

Set up webhooks to receive real-time updates:

transfer.awaiting_funds
transfer.funds_received
transfer.completed
transfer.failed

Polling Status

// Check transfer status
const statusResponse = await fetch(`/api/v0/transfers/${transferId}`, {
  headers: {
    'x-client-key': 'your_client_key_here',
    'x-client-secret': 'your_client_secret_here'
  }
});

const currentTransfer = await statusResponse.json();
console.log('Current state:', currentTransfer.state);

Next StepsCopied!

After creating a direct bank transfer:

Provide Bank Instructions: Share complete source_deposit_instructions with sender
Monitor Transfer: Track status through webhooks or polling
Handle Completion: Process successful conversions in your application
Customer Communication: Keep sender informed of processing status
Receipt Processing: Use final receipt for accounting and reconciliation

GET /api/v0/wallets - List your Bridge wallets
GET /api/v0/transfers/{id} - Check transfer status
POST /api/v0/transfers/direct-wallet - Create wallet-to-wallet transfer
POST /api/v0/transfers/stablecoin-conversion - Convert between stablecoins