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>

The idempotency key ensures that a payment request is processed only once. It must be unique for each batch of payments to prevent duplicate processing.

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

Waterfall transfers Request fields

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

Unique identifier assigned to the payment request.

  • Populated as a batch number by the bank.
  • Provides traceability and prevents duplicate processing.
required
Array of objects (WaterfallTransferRequest_payments)

List of individual payments in the waterfall.

Responses
201

Waterfall transfers processed successfully

400

Bad Request

401

Unauthorized

403

Forbidden

404

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

405

Method Not Allowed – HTTP method used is not supported by the requested resource.

409

Conflict

500

Internal Server

503

Service Unavailable – The server is temporarily unable.

post/api/gateway/v1/payments/waterfall
Request samples
application/json
{
  • "externalReferenceId": "wf-20250716-279514",
  • "payments": [
    ]
}
Response samples
application/json
{
  • "waterfallId": "8f4eb852-972b-4568-9613-2a45f184d791"
}