Creating an Outbound Transfer

The Transfer API allows you to move funds from your account to a beneficiary. You can create transfers directly (with full details) or by using a previously generated quote.

Endpoint

POST banking/v2/transfers

Authentication

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

Request Body

You can create a transfer using two different methods:

1. Direct Transfer: Providing all transfer details including source account, amount, and beneficiary
2. Quote-based Transfer: Using a previously generated quote ID

Common Fields

Direct Transfer Instruction

Quote-based Transfer Instruction

Please see Quotes API for details on generating quotes for transfers

Response

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

Example 1: Direct Transfer

{
  "reason": "supplier_payment",
  "payment_reference": "INV-2023-05-14-001",
  "memo": "Monthly payment for office supplies",
  "client_reference": "CLIENT-TRF-20230514-001",
  "additional_info": [
    {
      "key": "purpose_code",
      "value": "SUPP"
    }
  ],
  "client_metadata": {
    "department": "procurement",
    "invoice_id": "INV-456"
  },
  "instruction": {
    "type": "direct",
    "amount": 150000,
    "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
    "beneficiary_id": "98765432-9876-9876-9876-987654321098"
  }
}

Example 2: Quote-based Transfer

{
  "reason": "vendor_payment",
  "payment_reference": "INV-2023-05-15-002",
  "client_reference": "CLIENT-TRF-20230515-002",
  "client_metadata": {
    "department": "finance",
    "project_id": "PRJ-2023-Q2"
  },
  "instruction": {
    "type": "quote",
    "quote_id": "fedcba98-7654-3210-fedc-ba9876543210"
  }
}

Example 3: Cross-Currency Direct Transfer

{
  "reason": "international_supplier",
  "payment_reference": "INTL-INV-2023-05-16-003",
  "client_reference": "CLIENT-TRF-20230516-003",
  "instruction": {
    "type": "direct",
    "amount": 100000,
    "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
    "beneficiary_id": "98765432-9876-9876-9876-987654321098",
    "destination_currency": "EUR",
    "fixed_side": "source"
  }
}

Sample CURL Request

curl -X POST "https://api.waza.co/banking/v2/transfers" \
  -H "x-waza-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "supplier_payment",
    "payment_reference": "INV-2023-05-14-001",
    "client_reference": "CLIENT-TRF-20230514-001",
    "instruction": {
      "type": "direct",
      "amount": 150000,
      "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
      "beneficiary_id": "98765432-9876-9876-9876-987654321098"
    }
  }'

Understanding Fixed Side in Cross-Currency Transfers

In cross-currency transfers, the "fixed side" parameter determines which amount remains constant during the transaction. This allows you to control whether you send a specific amount or ensure the recipient receives a specific amount, particularly important when transferring money across different currencies.

Fixed Side Options for Transfers

How Fixed Side Works in Transfers

Source Fixed

When fixed_side is set to source, the system will:

• Debit the exact amount specified from your source account
• Convert this amount to the destination currency based on the exchange rate
• The beneficiary will receive the calculated amount after conversion
• Useful when you have a specific budget for a transfer

Destination Fixed

When fixed_side is set to destination, the system will:

• Ensure the beneficiary receives exactly the specified amount
• Calculate how much to debit from your account based on the exchange rate
• Debit the calculated amount (plus fees) from your source account
• Useful when the recipient needs to receive a precise amount (e.g., for invoice payments)

Implementation in Transfer API Requests

Direct Transfer with Source Fixed

When you want to send a specific amount from your account:

{
  "reason": "supplier_payment",
  "instruction": {
    "type": "direct",
    "amount": 500000,
    "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
    "beneficiary_id": "98765432-9876-9876-9876-987654321098",
    "destination_currency": "EUR",
    "fixed_side": "source"
  }
}

In this example, exactly 5,000 USD will be debited from your account, and the beneficiary will receive the EUR equivalent based on the current exchange rate.

Direct Transfer with Destination Fixed

When your beneficiary needs to receive a specific amount:

{
  "reason": "invoice_payment",
  "instruction": {
    "type": "direct",
    "amount": 450000,  // 4,500 in minor units (e.g., EUR cents)
    "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890", 
    "beneficiary_id": "98765432-9876-9876-9876-987654321098",
    "destination_currency": "EUR",
    "fixed_side": "destination"
  }
}

In this example, the system will calculate how much USD to debit from your account to ensure the beneficiary receives exactly 4,500 EUR.

Important Considerations for Transfers

1. Default Behavior: If fixed_side is not specified in a transfer request, the system defaults to source.

2. Amount Interpretation in Transfers:

   • With fixed_side: "source", the amount is how much will leave your account in the source currency
   • With fixed_side: "destination", the amount is how much the beneficiary will receive in the destination currency

3. Transfer Fees:

   • When using destination as the fixed side, remember that transfer fees might be added to the calculated source amount
   • The total debited will be the calculated amount needed for the conversion plus all applicable fees

4. Required Fields for Cross-Currency Transfers:

   • destination_currency must be specified when the beneficiary's currency differs from the source account
   • fixed_side should be specified to control which amount remains constant

Example Transfer Scenarios

Scenario 1: Sending a budgeted amount overseas

A business has budgeted exactly 10,000 USD for an international vendor payment and have already have a USD account

• Uses fixed_side: "source" and amount: 1000000 (in cents)
• The beneficiary receives the equivalent in their local currency based on the exchange rate
• The business knows exactly how much (10,000 USD) will leave their account

Scenario 2: Paying an international invoice

A business needs to pay an invoice for exactly 8,500 EUR:

• Uses fixed_side: "destination" and amount: 850000 (in cents)
• Sets destination_currency: "EUR"
• The system calculates how much USD to debit to ensure the beneficiary receives exactly 8,500 EUR
• The invoice is paid with the exact amount required, regardless of exchange rate fluctuations

By correctly using the fixed side parameter in your cross-currency transfers, you can ensure either precise sending amounts or precise receiving amounts, depending on your business needs.