Create Transfer

Overview

The Create Transfer API allows you to initiate a new transfer for a business. Transfers can be either deposits (money coming into the business) or withdrawals (money going out of the business). The transfer will be processed according to the specified type (wire, ACH, or check) and direction.

Resource Access

• HTTP Method: POST
• Endpoint: /v1/businesses/{business_id}/transfers
• Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication

Request Body

The request body should contain a JSON object with the following structure:

{
  "amount": {
    "currency": "USD",
    "amount": "1.00"
  },
  "bank_account_id": "urn:uuid:bank-account-123",
  "direction": "withdrawal",
  "type": "wire",
  "idempotency_key": "urn:uuid:idempotency-123",
  "user_data": {
    "purpose": "Monthly withdrawal",
    "reference": "REF-001"
  }
}

Request Fields

Field	Type	Required	Description
amount	object	Yes	Transfer amount with currency
amount.currency	string	Yes	Currency code (USD, EUR, GBP)
amount.amount	string	Yes	Transfer amount as string (e.g., "1.00")
bank_account_id	string (UUID)	Yes	ID of the bank account to use
direction	string	Yes	Transfer direction: deposit or withdrawal
type	string	Yes	Transfer type: wire, ach, or check
idempotency_key	string (UUID)	Yes	Unique key to prevent duplicate transfers
user_data	object	No	Additional user-defined data (optional)

Response

Success Response (201 Created)

{
  "id": "urn:uuid:transfer-123",
  "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
  "amount": {
    "currency": "USD",
    "amount": "1.00"
  },
  "bank_account_id": "urn:uuid:bank-account-123",
  "direction": "withdrawal",
  "type": "wire",
  "status": "pending",
  "idempotency_key": "urn:uuid:idempotency-123",
  "user_data": {
    "purpose": "Monthly withdrawal",
    "reference": "REF-001"
  },
  "created_at": "2022-01-01T00:00:00.000Z",
  "updated_at": "2022-01-01T00:00:00.000Z"
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the transfer
business_id	string (UUID)	Business ID this transfer belongs to
amount	object	Transfer amount with currency
bank_account_id	string (UUID)	Bank account ID used for this transfer
direction	string	Transfer direction
type	string	Transfer method type
status	string	Current status of the transfer
idempotency_key	string (UUID)	Idempotency key used
user_data	object	Additional user-defined data
created_at	string (date-time)	Creation timestamp
updated_at	string (date-time)	Last update timestamp

Transfer Status Values

• pending: Transfer initiated but not yet processed
• processing: Transfer is being processed
• completed: Transfer successfully completed
• failed: Transfer failed to process
• cancelled: Transfer was cancelled

Transfer Direction Values

• deposit: Money coming into the business account
• withdrawal: Money going out of the business account

Transfer Type Values

• wire: Wire transfer (fastest, highest fees)
• ach: ACH transfer (slower, lower fees)
• check: Physical check (slowest, variable fees)

Error Responses

• 400 Bad Request: Invalid input data or insufficient funds
• 401 Unauthorized: Invalid or missing authentication token
• 404 Not Found: Business or bank account not found
• 409 Conflict: Idempotency key already used (duplicate transfer)
• 422 Unprocessable Entity: Business rules violation (unverified account, limits exceeded)

Code Examples

cURL

curl -X POST \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "amount": {
      "currency": "USD",
      "amount": "1.00"
    },
    "bank_account_id": "urn:uuid:bank-account-123",
    "direction": "withdrawal",
    "type": "wire",
    "idempotency_key": "urn:uuid:idempotency-123",
    "user_data": {
      "purpose": "Monthly withdrawal",
      "reference": "REF-001"
    }
  }'

Python

import requests

url = "https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
data = {
    "amount": {
        "currency": "USD",
        "amount": "1.00"
    },
    "bank_account_id": "urn:uuid:bank-account-123",
    "direction": "withdrawal",
    "type": "wire",
    "idempotency_key": "urn:uuid:idempotency-123",
    "user_data": {
        "purpose": "Monthly withdrawal",
        "reference": "REF-001"
    }
}

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

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const data = {
  amount: {
    currency: 'USD',
    amount: '1.00'
  },
  bank_account_id: 'urn:uuid:bank-account-123',
  direction: 'withdrawal',
  type: 'wire',
  idempotency_key: 'urn:uuid:idempotency-123',
  user_data: {
    purpose: 'Monthly withdrawal',
    reference: 'REF-001'
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Use a unique idempotency_key for each transfer to prevent duplicates
• Amount is specified as a string to avoid floating-point precision issues
• Bank account must be verified and active before transfers can be created
• Transfer limits and fees vary by type (wire > ACH > check)
• Status will change from pending to processing to completed or failed
• Failed transfers may be retried with a new idempotency key
• Deposits typically require additional verification steps
• Use the user_data field to store reference information or metadata

Interactive API Explorer