Post multi-leg payment

Enables users to submit payments with multiple legs to the platform; the payments are processed asynchronously and must contain at least three legs but no more than twenty.

The payload contains debits and credits lists. These lists include legs that follow the requirements of credit and debit objects in the Post a payment endpoint.

See the Examples drop-down menu for a sample payload.

NOTES:

• A single tracking ID must be provided. This is referred to as the original tracking ID.
• A child tracking ID is generated for each leg; these tracking IDs are created by combining a control suffix with the original tracking ID. The authorization event generated by each leg includes the same corporate_metadata attribute that contains an original_tracking_id field. This field establishes the connection between the individual leg and the original tracking ID associated with the initial multi-leg payment request.
• If the account has any reason-based force payment restrictions, a force operation (force_post set to true) fails. The reasons that restrict force credit or debit operations are:
  • Credit Only - No Force Debit Allowed
  • Debit Only - No Force Credit Allowed
  • Any - No Force Allowed
  • Manual - No Force Allowed
• To get respective reason IDs, refer to the List account status reasons endpoint.
• This does not support forced transfers from earmark balance.

Error Handling for Multi-Leg Payments
The multi-leg payment endpoint is specifically designed to handle a list of payment legs. If any legs within the request encounter an issue during processing, the entire operation is rolled back to maintain data integrity.

The rollback is a resource-intensive operation and leaves a trace of reversal transactions to compensate for the legs that were executed successfully. Therefore, extensive validation is necessary before accepting the request to minimize rollback scenarios; it also provides the client with an early indication that the operation might fail due to an invalid input. Because of these considerations, this endpoint follows a unique error handling approach compared to other endpoints within the API.

Error Response Structure

When validation errors occur in one or more legs within the request, the API returns a structured error response to provide comprehensive information about the issues encountered. This response consists of two parts:

1. Generic Error Message:

• The generic error message is the WMLP0005 error code. It does not provide specific details about individual legs. This message is intended to give the client an immediate indication that the input is invalid.

2. List of Leg-Specific Errors:

• Following the generic error message, the endpoint returns the same leg payload with the addition of an errors attribute containing a detailed list of errors associated with each leg.

In addition to leg-specific errors, there might be errors related to the entire request. For instance, when a multi-leg payment request exceeds the maximum allowed number of legs, the standard error response that includes only code and message attributes is returned. Refer to the examples provided for different error types and their corresponding error codes.

Each leg generates the following events:

• Authorization created
• Account balance changed
• Account balance changed (Availables)
• Transaction created
• Accounting entry created
• If flex controls are configured, the event is triggered:
  • Flex control evaluated
    See the Data and reporting guide for more information on events and setting up event notifications.

Additionally, the following events are generated for the multi-leg payments:

• Multi-leg payment lifecycle created
• Multi-leg payment lifecycle status changed