> ## Documentation Index
> Fetch the complete documentation index at: https://devdraft.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Bank Transfer

> Initiate bank-to-wallet transfers from external bank accounts to your Devdraft wallets

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

<CodeGroup>
  ```json Request theme={null}
  {
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentRail": "wire",
    "currency": "usd",
    "amount": 1000.50
  }
  ```
</CodeGroup>

### 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)

<CodeGroup>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```json Wire Instructions theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

#### 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

<CodeGroup>
  ```json ACH Instructions theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

### SEPA Transfer Instructions

<CodeGroup>
  ```json SEPA Instructions theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## 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

<AccordionGroup>
  <Accordion title="Wire Transfers" icon="clock">
    * **Same Day**: If received before 5 PM EST
    * **Next Business Day**: If received after 5 PM EST
    * **Processing**: 2-4 hours after funds received
  </Accordion>

  <Accordion title="ACH Transfers" icon="calendar">
    * **Standard ACH**: 1-3 business days
    * **Same Day ACH**: If initiated before 4 PM EST
    * **Processing**: 1-2 hours after funds received
  </Accordion>

  <Accordion title="SEPA Transfers" icon="euro-sign">
    * **SEPA Instant**: Within minutes
    * **Standard SEPA**: 1 business day
    * **Processing**: 1-2 hours after funds received
  </Accordion>

  <Accordion title="SPEI Transfers" icon="peso-sign">
    * **SPEI**: Real-time (24/7)
    * **Processing**: 1-2 hours after funds received
  </Accordion>
</AccordionGroup>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const transferData = {
    walletId: '550e8400-e29b-41d4-a716-446655440000',
    paymentRail: 'wire',
    currency: 'usd',
    amount: 1000.50
  };

  const response = await fetch('https://api.devdraft.ai/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('Send bank transfer to:', instructions.bank_name);
  console.log('Account:', instructions.bank_account_number);
  console.log('Routing:', instructions.bank_routing_number);
  console.log('Reference:', instructions.deposit_message);
  ```

  ```python Python theme={null}
  import requests
  import json

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

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

  if response.status_code == 201:
      transfer = response.json()
      instructions = transfer['source_deposit_instructions']
      
      print(f"Send bank transfer to: {instructions['bank_name']}")
      print(f"Account: {instructions['bank_account_number']}")
      print(f"Routing: {instructions['bank_routing_number']}")
      print(f"Reference: {instructions['deposit_message']}")
  else:
      print(f"Error: {response.status_code}")
      print(response.text)
  ```

  ```php PHP theme={null}
  <?php
  $data = [
      'walletId' => '550e8400-e29b-41d4-a716-446655440000',
      'paymentRail' => 'wire',
      'currency' => 'usd',
      'amount' => 1000.50
  ];

  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://api.devdraft.ai/api/v0/transfers/direct-bank',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => json_encode($data),
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'x-client-key: your_client_key_here',
          'x-client-secret: your_client_secret_here'
      ],
  ]);

  $response = curl_exec($curl);
  $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);

  if ($httpCode === 201) {
      $transfer = json_decode($response, true);
      $instructions = $transfer['source_deposit_instructions'];
      
      echo "Send bank transfer to: {$instructions['bank_name']}\n";
      echo "Account: {$instructions['bank_account_number']}\n";
      echo "Routing: {$instructions['bank_routing_number']}\n";
      echo "Reference: {$instructions['deposit_message']}\n";
  } else {
      echo "Error: $httpCode\n";
      echo $response;
  }
  ?>
  ```
</CodeGroup>

## Error Responses

<CodeGroup>
  ```json 400 Bad Request theme={null}
  {
    "statusCode": 400,
    "message": "Invalid payment rail or currency combination",
    "error": "Bad Request"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "statusCode": 404,
    "message": "Devdraft wallet not found with ID: 550e8400-e29b-41d4-a716-446655440000",
    "error": "Not Found"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "statusCode": 422,
    "message": "SPEI is only supported with MXN currency",
    "error": "Unprocessable Entity"
  }
  ```
</CodeGroup>

## Important Notes

<AccordionGroup>
  <Accordion title="Developer Fees" icon="dollar-sign">
    * **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
  </Accordion>

  <Accordion title="Banking Hours" icon="clock">
    * **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
  </Accordion>

  <Accordion title="Transfer Limits" icon="scale-balanced">
    * **Minimum**: \$10 USD equivalent
    * **Maximum**: \$100,000 USD equivalent per transfer
    * **Daily limits**: Vary by payment rail and verification level
  </Accordion>

  <Accordion title="Compliance & Security" icon="shield">
    * All transfers comply with AML/KYC regulations
    * Bank instructions expire after 7 days
    * Failed transfers are automatically refunded
    * Full audit trail maintained for compliance
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Business Payments" icon="briefcase">
    Receive payments from clients via traditional banking
  </Card>

  <Card title="Fiat On-Ramp" icon="arrow-trend-up">
    Convert traditional bank funds to cryptocurrency
  </Card>

  <Card title="International Remittances" icon="globe">
    Accept international wire transfers for conversion
  </Card>

  <Card title="Enterprise Integration" icon="building">
    Integrate with existing accounting and ERP systems
  </Card>

  <Card title="Supplier Payments" icon="truck">
    Receive payments from suppliers and vendors
  </Card>
</CardGroup>

## Next Steps

After creating a direct bank transfer:

<Steps>
  <Step title="Provide Instructions">
    Share `source_deposit_instructions` with the sender
  </Step>

  <Step title="Monitor Status">
    Poll transfer status or use webhooks for updates
  </Step>

  <Step title="Handle Completion">
    Process successful transfers in your application
  </Step>

  <Step title="Compliance Management">
    Maintain records for regulatory compliance
  </Step>
</Steps>

## Related Endpoints

* `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