API Call Sequence

Overview

The Payouts feature facilitates the initiation and management of payout requests for specified shops. It allows for the definition of payout amounts and purposes.

API Call Sequence

1. Retrieve Payout Methods: Obtain the available payout methods for your shop.
2. Get Required Payout Fields: Based on the providerCode and InstrumentType, obtain the necessary fields required for executing a payout. The available options for these parameters can be acquired by contacting technical support. The available providerCode and InstrumentType for your shop can be obtained from technical support.
3. Create Payout Request: A payout request is created by specifying the necessary details obtained from the previous step.
4. Check Payout Status: After initiating a payout, its status can be tracked through the retrieval endpoint, providing transparency and updates on the payout process.

Unified Bank Directory

For payout methods that require selecting a bank, each provider normally returns its own list of bank codes, so the same bank may have different codes depending on the provider. For your company, a unified bank directory can be enabled instead:

• Get Required Payout Fields returns the platform's unified bank codes for the providers covered by the directory — the same banks have the same codes regardless of the provider. The same unified codes are used for bank selection on the payment page in purchases.
• Pass the bank code from the fields response when creating a payout — the platform maps it to the provider's own code when sending the request to the provider.
• When a retry goes through another provider (cascading), the selected bank is reused — the recipient is not asked to select it again.

The unified directory covers only the providers for which the mapping has been configured; for other providers, and for companies where the feature is not enabled, the provider's own bank codes are returned and accepted as before. To enable the unified bank directory for your company, contact technical support.

Payout Cascading

A failed payout attempt can be retried automatically through another provider, the same way as payments are — see Payment Flow — Automatic retries: cascading. Cascading runs when Enable cascading is turned on in the Payout attempts settings of the shop, the shop allows more than one payout attempt, and the shop has cascading rules of the Payout type; the settings and the rules are managed in the Merchant Account.

• A payout retry is created only when the status code of the failed attempt allows a payout retry — see the Retry allowed column of the Payout Processing (2-11-XX) group in the Status Codes reference. The typical scenario is 2-11-02 (insufficient funds on the merchant's account): the payout is retried through a provider whose account has sufficient funds.
• A cascading rule can match the failed attempt by its status code. When the payout request pins a specific provider and acquirer, create the rule with that payment method as the source; when the method is selected by routing, a rule with a status code condition alone is enough.
• The data submitted with the payout is reused for the retry; with the unified bank directory enabled, the selected bank is mapped to the new provider automatically.
• If no rule matches the failed attempt, or every matching rule points to a method that has already been tried, the payout fails with status code 1-03-03.

All attempts of a payout are returned in the payoutTransactions array of the payout status response and the Payout Status Callback.

Payout Life Cycle

Status	Description
registered	This is a technical status indicating that the payout has been registered in the system. Immediately after registration, the payout transitions to in_progress.
in_progress	The payout has been created and is in progress. It can transition to Failed if there is a problem on the provider's side, or to Completed if the payout is successfully processed.
completed	The payout has been successfully completed.
failed	The payout did not go through on the provider's side. Provider error.
cancelled	The payout was cancelled — for example, the recipient did not submit the required data on the payment page before the timeout window expired (1-01-03).
need_action	Payout requires merchant action to complete the transaction.

note

Every payout has a Time-To-Live (TTL) of 10 days from the moment it is created. If the payout is not successfully completed within this period, the system automatically moves it to failed. This status change does not block further updates: if the provider later confirms the final result of the transaction, the payout status can still be updated based on that information.