Direct Bank Transfer - Devdraft API Documentation

The Create Direct Bank Transfer endpoint enables you to initiate traditional bank-to-wallet transfers where the source funds come from an external bank account and are deposited directly into one of your Devdraft wallets. This endpoint creates a dynamic transfer that provides bank deposit instructions for the sender to follow.

Endpoint Details

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

Authentication

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 Body

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "paymentRail": "wire",
  "currency": "usd",
  "amount": 1000.50
}

Parameters

Parameter	Type	Required	Description
walletId	string	Yes	The ID of your wallet to receive the transfer
paymentRail	string	Yes	Bank payment method (wire, ach, sepa, spei)
currency	string	Yes	Fiat currency (usd, eur, mxn)
amount	number	No	Transfer amount (optional for flexible amount transfers)

Supported Payment Rails

Wire Transfer (wire) - International wire transfers
ACH (ach) - US Automated Clearing House transfers
SEPA (sepa) - European Single Euro Payments Area transfers
SPEI (spei) - Mexican electronic payment system

Supported Currencies

USD (usd) - Available with wire and ACH
EUR (eur) - Available with wire and SEPA
MXN (mxn) - Available with wire and SPEI

Response

Success Response (201 Created)

{
  "id": "tr_1234567890abcdef",
  "state": "awaiting_funds",
  "amount": "1000.50",
  "developer_fee": "8.00",
  "on_behalf_of": "cus_devdraft123abc",
  "source": {
    "payment_rail": "wire",
    "currency": "usd",
    "to_address": null,
    "external_account_id": null
  },
  "destination": {
    "payment_rail": "solana",
    "currency": "usdc",
    "to_address": "7xKXKRoBrJgCXVb2KhxZZzPHxYMJ4DpHWGQ8RvxS6JEq",
    "external_account_id": null
  },
  "source_deposit_instructions": {
    "payment_rail": "wire",
    "currency": "usd",
    "amount": "1000.50",
    "to_address": null,
    "bank_name": "JPMorgan Chase Bank, N.A.",
    "bank_address": "270 Park Avenue, New York, NY 10017",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890",
    "bank_beneficiary_name": "Devdraft Network Inc",
    "bank_beneficiary_address": "123 Devdraft Street, San Francisco, CA 94105",
    "deposit_message": "Transfer ID: tr_1234567890abcdef",
    "from_address": null
  },
  "receipt": null,
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}

Response Fields

Field	Type	Description
id	string	Unique transfer identifier
state	string	Transfer state (awaiting_funds, processing, completed, failed)
amount	string	Transfer amount (if fixed)
developer_fee	string	Developer fee amount (0.8% of transfer amount)
source	object	Source endpoint information
destination	object	Destination endpoint information
source_deposit_instructions	object	Critical: Bank instructions for the sender
receipt	object	Transfer receipt (available when completed)
created_at	string	Transfer creation timestamp
updated_at	string	Last update timestamp

Understanding Bank Deposit Instructions

The source_deposit_instructions object contains the exact bank information that the external sender needs to complete the wire transfer.

Wire Transfer Instructions

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

Key Fields for Wire Instructions

Field	Description	Usage
bank_name	Receiving bank name	For wire transfer forms
bank_routing_number	Bank routing/SWIFT code	Required for transfers
bank_account_number	Account number	Destination account
bank_beneficiary_name	Account holder name	Beneficiary information
deposit_message	Critical reference	Must be included in transfer memo

ACH Transfer Instructions

{
  "source_deposit_instructions": {
    "payment_rail": "ach",
    "currency": "usd",
    "amount": "1000.50",
    "bank_name": "Wells Fargo Bank",
    "bank_routing_number": "121000248",
    "bank_account_number": "9876543210",
    "bank_beneficiary_name": "Devdraft Network Inc",
    "deposit_message": "Transfer ID: tr_1234567890abcdef"
  }
}

SEPA Transfer Instructions

{
  "source_deposit_instructions": {
    "payment_rail": "sepa",
    "currency": "eur",
    "amount": "850.00",
    "bank_name": "Deutsche Bank AG",
    "bank_bic": "DEUTDEFF",
    "bank_iban": "DE89370400440532013000",
    "bank_beneficiary_name": "Devdraft Europe GmbH",
    "deposit_message": "Transfer ID: tr_1234567890abcdef"
  }
}

How Bank Deposit Instructions Work

1. Dynamic Transfer Creation

When you create a direct bank transfer, the system:

Generates a unique temporary receiving bank account
Creates bank deposit instructions for the sender
Sets up monitoring for incoming funds

2. Sender Instructions

You provide the source_deposit_instructions to the external sender, who must:

Initiate a bank transfer using the provided bank details
Send the exact currency and amount (if specified)
Include the deposit_message as the transfer reference/memo

3. Automatic Processing

Once funds are received:

System detects the incoming bank deposit
Automatically converts fiat to stablecoin
Transfers to your destination wallet
Updates transfer state to completed
Provides final receipt with all fees and amounts

Transfer States

State	Description	Next Action
awaiting_funds	Waiting for sender to initiate bank transfer	Provide bank instructions to sender
funds_received	Bank transfer detected, processing conversion	Wait for completion
processing	Converting fiat to crypto and transferring	Monitor for completion
completed	Transfer successful	Check receipt for final amounts
failed	Transfer failed	Check failure reason, may need retry

Processing Times

Wire Transfers

Same Day: If received before 5 PM EST
Next Business Day: If received after 5 PM EST
Processing: 2-4 hours after funds received

ACH Transfers

Standard ACH: 1-3 business days
Same Day ACH: If initiated before 4 PM EST
Processing: 1-2 hours after funds received

SEPA Transfers

SEPA Instant: Within minutes
Standard SEPA: 1 business day
Processing: 1-2 hours after funds received

SPEI Transfers

SPEI: Real-time (24/7)
Processing: 1-2 hours after funds received

Example Requests

curl -X POST "https://api.devdraft.ai/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", 
    "currency": "usd",
    "amount": 1000.50
  }'

Error Responses

{
  "statusCode": 400,
  "message": "Invalid payment rail or currency combination",
  "error": "Bad Request"
}

Important Notes

Developer Fees

0.8% developer fee is automatically applied to all transfers
Fee is calculated on the total transfer amount
Fee is deducted from the final amount received

Banking Hours

Wire transfers: Processed during business hours (9 AM - 5 PM EST)
ACH transfers: Processed on business days
SEPA transfers: 24/7 processing available
Weekend processing: Limited to SEPA Instant and some wire transfers

Transfer Limits

Minimum: $10 USD equivalent
Maximum: $100,000 USD equivalent per transfer
Daily limits: Vary by payment rail and verification level

Compliance & Security

All transfers comply with AML/KYC regulations
Bank instructions expire after 7 days
Failed transfers are automatically refunded
Full audit trail maintained for compliance

Use Cases

Business Payments

Receive payments from clients via traditional banking

Fiat On-Ramp

Convert traditional bank funds to cryptocurrency

International Remittances

Accept international wire transfers for conversion

Enterprise Integration

Integrate with existing accounting and ERP systems

Supplier Payments

Receive payments from suppliers and vendors

Next Steps

After creating a direct bank transfer:

Provide Instructions

Share source_deposit_instructions with the sender

Monitor Status

Poll transfer status or use webhooks for updates

Handle Completion

Process successful transfers in your application

Compliance Management

Maintain records for regulatory compliance

GET /api/v0/wallets - List your Devdraft wallets
GET /api/v0/transfers/{id} - Check transfer status
POST /api/v0/transfers/direct-wallet - Create wallet-to-wallet transfer

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Request Body

​Parameters

​Supported Payment Rails

​Supported Currencies

​Response

​Success Response (201 Created)

​Response Fields

​Understanding Bank Deposit Instructions

​Wire Transfer Instructions

​Key Fields for Wire Instructions

​ACH Transfer Instructions

​SEPA Transfer Instructions

​How Bank Deposit Instructions Work

​1. Dynamic Transfer Creation

​2. Sender Instructions

​3. Automatic Processing

​Transfer States

​Processing Times

​Example Requests

​Error Responses

​Important Notes

​Use Cases