Perform Internal Transfer

The Internal Transfer API allows you to move funds between accounts within your institution in the same currency. Internal transfers can be made between main accounts and sub-accounts and vice versa. The destination account must not have a settlement account configured

Endpoint

POST banking/v2/transfers/internal

Authentication

Requires a valid API key provided in the header: x-waza-api-key.

Request Body

Response

A successful request returns an HTTP 200 status code and a Transfer object.

The response includes all transfer details including:

• Transfer ID and status
• Source and destination account information
• Amount details (source amount, billing amount, destination amount)
• Timestamps and processing information
• Any fees applied (typically none for internal transfers)
• 
  

Examples

Example 1: Basic Internal Transfer

{
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "destination_account_id": "98765432-9876-9876-9876-987654321098",
  "amount": 250000
}

Example 2: Internal Transfer with Reference and Memo

{
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890", 
  "destination_account_id": "98765432-9876-9876-9876-987654321098",
  "amount": 150000,
  "client_reference": "INT-TRF-20230514-001",
  "memo": "Quarterly budget allocation to marketing department"
}

Example 3: Internal Transfer with Metadata

{
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "destination_account_id": "98765432-9876-9876-9876-987654321098", 
  "amount": 500000,
  "client_reference": "PAYROLL-2023-05-001",
  "memo": "Employee salary payment",
  "client_metadata": {
    "department": "finance",
    "payroll_batch_id": "BATCH-2023-05",
    "employee_count": 25
  }
}

Sample CURL Request

curl -X POST "https://api.waza.co/banking/v2/transfers/internal" \
  -H "x-waza-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
    "destination_account_id": "98765432-9876-9876-9876-987654321098",
    "amount": 250000,
    "client_reference": "INT-TRF-20230514-001",
    "memo": "Internal department transfer"
  }'

Important Considerations

Account Requirements

1. Account Type: Both accounts must be of type VIRTUAL_EXTERNAL
2. Settlement Account: Destination account must not have a settlement account configured

Transfer Characteristics

1. Instant Processing: Internal transfers are processed immediately
2. No Fees: No fees are charged for internal transfers
3. Same Currency: Transfers occur in the same currency as the accounts
4. Real-time Balance Updates: Account balances are updated instant

Idempotency

• Use the client_reference field to ensure idempotency

Error Scenarios

Common error scenarios include:

1. Insufficient Balance: Source account doesn't have enough funds
2. Invalid Account Type: Accounts are not of the supported type
3. Settlement Account Conflict: Destination account has a settlement account configured
4. Duplicate Reference: Client reference already used for another transfer

Each error will return an appropriate HTTP status code and error message detailing the specific issue.