Commission pre-calculation

Overview

Commission pre-calculation allows you to estimate payout fees before creating a payout.

Use this method when you need to show the expected fee to the user, decide who pays the fee, or calculate the final payout amount before calling payout creation methods.

When to use this API

Use commission pre-calculation before creating:

• a single payout;
• a mass payout;
• a payout where the merchant wants to pass all or part of the fee to the user.

For payout fee calculation, use opType: WITHDRAWAL.

Fee types

feeType	Description
SERVICE	The full service fee is included in the user-paid part. In the response, use feeReceiver to see the amount after the full fee is deducted.
FIX	Only the fixed fee is included in the user-paid part. In the response, fixedFee shows the fixed fee amount.
PERCENT	Only the percentage fee is included in the user-paid part. In the response, percentFee shows the percentage fee amount.

Integration flow

1. Choose the payout amount, payout currency, and feeType that matches your fee logic.
2. Send a request to [POST] tariff/extended-fee with opType: WITHDRAWAL.
3. Use feeReceiver when the fee should be included in the payout amount or partially paid by the user.
4. Use feeSender when the fee should be calculated on top of the payout amount. To create the payout with the fee paid by the sender, use the calculated amount and fee values according to your business logic.

API methods

Calculate payout fee - [POST] tariff/extended-fee

Request fields

Field	Type	Required	Description
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with fee calculation request data.

Payload fields

Field	Type	Required	Description
items	array	Yes	List of items for fee calculation. Must contain at least one item.

items fields

Field	Type	Required	Description
baseAmount	number	Yes	Payout amount for fee calculation.
currency	string	Yes	Currency ticker of the payout.
opType	string	Yes	Operation type. For payout fee calculation, use WITHDRAWAL.
feeType	string	Yes	Fee type: SERVICE, FIX, or PERCENT.

Request example

{
  "timestamp": 1,
  "payload": {
    "items": [
      {
        "baseAmount": 1000,
        "currency": "USDT",
        "opType": "WITHDRAWAL",
        "feeType": "SERVICE"
      }
    ]
  }
}

Response fields

Field	Type	Description
items	array	List of calculated fee results.

items response fields

Field	Type	Description
amount	number	Initial transaction amount used for calculation.
currency	string	Currency ticker.
opType	string	Operation type used for calculation.
feeReceiver	object	Calculation where fee is deducted from the amount received by the recipient.
feeSender	object	Calculation where fee is added on top of the payout amount and paid by the sender.

feeReceiver and feeSender fields

Field	Type	Description
amount	number	Resulting transaction amount for the selected fee scenario.
fee	number	Total calculated fee amount.
fixedFee	number	Fixed fee amount.
percentFee	number	Percentage fee amount.

Response example 200 OK

{
  "items": [
    {
      "amount": 1000.00,
      "currency": "USDT",
      "opType": "WITHDRAWAL",
      "feeReceiver": {
        "amount": 934.58,
        "fee": 65.42,
        "fixedFee": 18.00,
        "percentFee": 47.42
      },
      "feeSender": {
        "amount": 1000.00,
        "fee": 70.00,
        "fixedFee": 18.00,
        "percentFee": 52.00
      }
    }
  ]
}

How to read the result

Scenario	Field to use	Description
Fee is included in the payout amount	feeReceiver	Shows how much the recipient receives after the selected fee is deducted.
Fee is paid on top of the payout amount	feeSender	Shows the payout amount and the fee calculated on top of it.
User pays only fixed fee	feeReceiver.fixedFee or feeSender.fixedFee	Use when feeType: FIX.
User pays only percentage fee	feeReceiver.percentFee or feeSender.percentFee	Use when feeType: PERCENT.
User pays full service fee	feeReceiver.fee or feeSender.fee	Use when feeType: SERVICE.

Errors and edge cases

Case	Description
Unsupported currency	The fee cannot be calculated if the currency is not available for payout operations.
Incorrect operation type	For payout fee calculation, opType must be WITHDRAWAL.
Incorrect fee type	feeType must be one of SERVICE, FIX, or PERCENT.
Fee calculation result	Use the calculation result when preparing the payout request and showing the fee to the user.

Related docs

Document	Link
Single payout API	How to create a single payout via API
Mass payout API	How to create a mass payout via API
Tariff API reference	Tariff API