Waterfall transfers

Initiates a batch of internal fund transfers arranged in a waterfall sequence. Each payment in the batch is executed in priority order defined by its paymentIndex, where funds flow from the debtor to the creditor specified in each payment. The waterfall design allows funds to cascade through multiple accounts sequentially within the bank. Note: This API is restricted to use by authorized financial institutions only.

SecurityoAuth2
Request
header Parameters
Idempotent-Key
required
string <uuid>

Idempotency key to ensure the payment is processed only once.

Example: 123e4567-e89b-12d3-a456-426614174000
Request Body schema: application/json
required

Waterfall transfers Request fields

externalReferenceId
string <= 200 characters ^[a-zA-Z0-9 ]+$

This refers to batch number populated by the bank.

deliveryDate
required
string <date>

Requested date for transfer processing

required
Array of objects (WaterfallTransferRequest_payments)

List of individual payments in the batch

Responses
201

Waterfall transfers processed successfully

400

The request was invalid due to malformed syntax or failed validation rules. This may include missing required fields, incorrect data formats, or invalid account information within the payment batch.

401

Unauthorized – The request lacks valid authentication credentials. Make sure to include a valid access token or API key.

403

Forbidden – The client is authenticated but does not have the necessary permissions to access the resource.

404

Not Found – The requested resource could not be located. Verify the endpoint or resource identifier.

500

The server encountered an unexpected condition that prevented it from fulfilling the request. This could be due to a system error, database failure, or other internal issues.

503

Service Unavailable – The server is temporarily unable to handle the request due to maintenance or overload.

post/waterfall-payments/api/v1/transfers
Request samples
application/json
{
  • "externalReferenceId": "wf-20250716-279514",
  • "deliveryDate": "0015-02-15",
  • "payments": [
    ]
}
Response samples
application/json
{
  • "batchId": "wf-20250716-279514"
}