Automated Settlement in Batches

Overview

We are introducing Automated Settlement Batch, a feature that lets payin and gaming order types be settled automatically in batches, rather than requiring manual or per-order settlement.

As part of this feature, we are also introducing multi-currency holding balances: merchants can hold their payin balance in any currency and choose a separate currency to settle those funds into.

1. Automated Settlement Batch

Payin and gaming orders will be grouped and settled automatically in batches, instead of being settled individually. This reduces operational overhead and gives merchants predictable, periodic payouts of their accumulated balance.

Supported order types:

payin
gaming

2. Hold Balance in Any Currency

Merchants can now hold their payin balance in a currency of their choice, independent of the currency they ultimately want to be settled in. This is controlled via two fields on the order:

Field	Description
`destination.holdingCurrency`	The currency in which the payin balance is held.
`destination.currency`	The currency in which the held funds should be settled out to the merchant.

This decouples "what currency the balance sits in" from "what currency the merchant gets paid in."

3. Prerequisite: Settlement Account Setup

Before destination.currency can be used in an order, a settlement account must exist for that currency. This is a one-time setup per currency.

Step 1 — Check required fields for the payout method

Call List Payment Methods to determine which fields are required for the fiat payment method you intend to settle to:

GET /v3/config/payment-methods?direction=withdraw¤cy=&userType=business

Key query params:

Param	Required	Notes
`direction`	Yes	Must be `withdraw` for settlement/payout methods.
`currency`	No (but needed here)	The currency you want to settle in.
`userType`	No, defaults to `individual`	Must be `business` for merchant settlement accounts.
`limit`, `page`	No	Pagination, defaults to `limit=5`, `page=1`.
`headlessMode`	No, defaults to `false`	When `true`, response includes the `additionalDetails` field list needed for account setup.

The response's additionalDetails (per payment method) tells you exactly which fields must be supplied under accountDetails when creating the settlement account.

Step 2 — Create the settlement account

Call Create Settlement Account:

POST /v3/settlement-account

Header:

Header	Required	Description
`MID`	Yes	Merchant or sub-merchant MID

Body (for currencyType: fiat):

Field	Type	Required	Notes
`currencyType`	string (enum)	Yes	`fiat`
`currency`	string	Yes	ISO 4217, 3-letter code
`paymentType`	string (enum)	Yes	`bank_transfer`, `card`, or `local_wallet`
`paymentCode`	string	Yes	Obtained from the List Payment Methods response
`accountDetails`	object	Yes (per method)	Must include every field listed under the chosen payment method's `additionalDetails`
`accountAlias`	string	No	Optional friendly name

📘
Notes

The first settlement account created for a given currencyType becomes the default.

If a matching settlement account already exists, the existing one is returned rather than creating a duplicate.

A currencyType: crypto variant also exists, requiring walletAddress plus either cryptoTicker or both cryptoCurrency and cryptoNetwork — relevant if settling to a crypto destination instead of fiat.

Step 3 — Use it in the Order API

Once the settlement account for destination.currency exists, it can be referenced simply by passing settlementAccountId, destination.holdingCurrency and destination.currency on the order

End-to-End Flow

Merchant decides which currency to hold payin balance in, and which currency to settle to.
Merchant calls List Payment Methods (direction=withdraw, userType=business, currency=<settlement currency>) to identify the required accountDetails fields for the desired payout method.
Merchant calls Create Settlement Account with currency, paymentType, paymentCode, and the required accountDetails.
Merchant places payin / gaming orders passing settlementAccountId, destination.holdingCurrency and destination.currency.
Orders accumulate and are automatically settled in batches to the configured settlement account.