Create Payout Request
POST/payouts
Initiates a new payout request for a specified shop, defining the payout amount, purpose, and optional payout and recipient settings. To fill out the body data of this endpoint, use the endpoints: Retrieve Payout Methods and Retrieve Required Payout Fields.
For all payouts, a Time-To-Live (TTL) of 1 week is set, starting from the moment the payout is created. If the payout process has not been successfully completed within 7 days after the TTL expires, the system will automatically change the payout's status to failed.
This automatic status change to failed indicates that the payout attempt was not completed within the required time frame. However, this status change does not stop the system from continuing to process updates or responses from the payment provider. For example, if after the status is marked as failed, the payment provider later confirms a successful or unsuccessful transaction, the payout status could still be updated based on this new information. The failed status simply reflects that the payout wasn't completed within the allowed timeframe, but it does not prevent further updates or changes to the status in the future.
Request
- application/json
Body
required
Details of the payout request to be created, including shop ID, payout specifics, purpose, and optional settings.
The unique identifier of the shop initiating the payout. How to get your shopId
payout objectrequired
Details of the payout.
cost objectrequired
Possible values: Value must match regular expression [0-9]*(\.[0-9]*)?
Defines the total payout amount, formatted as a decimal string with a period (.) as the decimal separator. For fiat currencies, the number of decimal places should comply with the ISO 4217 standard for the specified currency. If a cryptocurrency is used, specify the amount to match the token’s precision.
Possible values: >= 3 characters and <= 3 characters
Specifies the currency. For fiat currencies, use the ISO 4217 alphabetic code format consisting of 3 uppercase letters, such as 'USD' or 'EUR'. For cryptocurrencies, use their common symbols like 'BTC', 'ETH', 'USDT', etc. For a complete list of supported cryptocurrencies, please refer to Cryptocurrency Reference Guide.
A unique identifier for the payout that you must generate on your side. The payoutNumber should be specific to the shopId or your company (depending on your company's settings) and must be unique for every order and payout within each shopId or your company (depending on your company's settings).
The payoutNumber may contain only Latin letters (uppercase and lowercase), numbers, and hyphens. Hyphens cannot be at the beginning or end of the string.
For some providers, it is mandatory to specify the payout region. The region should be specified in ISO 3166-1 alpha-2 code format.
The standard of the cryptocurrency token, required if the currency used is crypto.
Possible values: <= 128 characters
The purpose or reason for the payout request.
Determines which payment provider should be used to process the payout.
Identifies the specific acquirer responsible for processing payouts.
Possible values: [card, bank_transfer, wallet, wallet, crypto_wallet, voucher]
Specifies the instrument type. See available instrument types
Possible values: Value must match regular expression ^https:\/\/.*
This parameter allows you to specify a webhook URL for receiving notifications about order status changes for this specific payout. If provided, notifications about the payout status changes will be sent to this URL instead of the general webhook URL set for the shop.
Possible values: [redirect, h2h, qr]
Method for data entry to process payout:
redirect - the entity making the payout enters payment information on the provider's (acquirer's) page via redirect;
h2h (host2host) - the entity making the payout enters payment information via our API;
qr - the entity making the payout scans a QR code and enters information on the aggregator's side.
Use this field to specify which alias should be applied for this payout. The alias ensures that the correct payment configuration is used.
This value is obtained from the paymentSettingsAlias field in the Retrieve Payout Methods endpoint.
For more detailed information about how to use aliases, refer to the Alias Documentation
customer objectnullable
Container for customer-specific information. Здесь указываются данные пользователя, который запросил выплату.
A unique identifier for the customer. The customerId should be specific to the shopId and must be unique within each shopId.
First name of the customer.
Last name of the customer.
Middle name of the customer, if applicable.
Customer's phone number, in international format.
Email address of the customer.
recipient object
Detailed information about the payout recipient. To know which fields need to be provided for each payout, first call the Retrieve Required Payout Fields endpoint. It will return the required fields for creating the payout.
personalData objectnullable
Personal identification and contact information.
The first name.
The last name.
The middle name, if any.
The phone number, including the country code.
The email address.
The date of birth in the format DD-MM-YYYY.
The IP address.
The name of the beneficiary.
The surname of the beneficiary.
addressData objectnullable
Address information.
The ISO 3166-1 alpha-2 country code of the location.
The state of the address.
The ISO 3166-1 alpha-2 country code of the recipient's or sender's location.
The city of the address.
The zip code of the address.
The primary address.
documentData objectnullable
Document identification.
The identification document number.
The Individual Taxpayer Identification Number, applicable in some jurisdictions.
Unique Taxpayer Identification Number (RUT), used primarily in Chile.
cardData objectnullable
Information required for processing a payout via credit card
The card number.
Name printed on the card.
Expiration month of the card.
Expiration year of the card.
walletData objectnullable
Information required for processing a payout via e-wallet.
The type of e-wallet
The e-wallet identifier.
The e-wallet name.
The name of the e-wallet holder.
bankTransferData objectnullable
Information required for processing a payout via bank transfer.
The bank account number.
The type of bank account (e.g., Savings, Checking).
The name associated with the bank account.
The name of the bank.
The branch of the bank where the account is held.
The specific code of the bank, often used in domestic transactions.
The city where the bank is located.
The primary address of the bank.
The postal code of the bank's address.
The province or state of the bank's location, if applicable.
Bank area
The routing number of the bank, required for bank transfers in certain countries.
The Bank Identifier Code (BIC), used in international transactions.
The transit number used to identify the bank branch.
The number that identifies the financial institution.
The type of bank transfer to be processed.
paymentData objectnullable
Details about the payment channel used for the payout.
The payment channel used for the transaction
payoutData objectnullable
Details related to the payout, including fee responsibility and currency.
Indicates who bears the fee for the transaction.
The source currency of the payout.
sender object
Details about the payout sender. For some providers, it is necessary to provide additional sender information for the payout. To know which fields need to be provided for each payout, first call the Retrieve Required Payout Fields endpoint. It will return the required fields for creating the payout.
personalData objectnullable
Personal identification and contact information.
The first name.
The last name.
The middle name, if any.
The phone number, including the country code.
The email address.
The date of birth in the format DD-MM-YYYY.
The IP address.
The name of the beneficiary.
The surname of the beneficiary.
addressData objectnullable
Address information.
The ISO 3166-1 alpha-2 country code of the location.
The state of the address.
The ISO 3166-1 alpha-2 country code of the recipient's or sender's location.
The city of the address.
The zip code of the address.
The primary address.
documentData objectnullable
Document identification.
The identification document number.
The Individual Taxpayer Identification Number, applicable in some jurisdictions.
Unique Taxpayer Identification Number (RUT), used primarily in Chile.
cardData objectnullable
Information required for processing a payout via credit card
The card number.
Name printed on the card.
Expiration month of the card.
Expiration year of the card.
walletData objectnullable
Information required for processing a payout via e-wallet.
The type of e-wallet
The e-wallet identifier.
The e-wallet name.
The name of the e-wallet holder.
bankTransferData objectnullable
Information required for processing a payout via bank transfer.
The bank account number.
The type of bank account (e.g., Savings, Checking).
The name associated with the bank account.
The name of the bank.
The branch of the bank where the account is held.
The specific code of the bank, often used in domestic transactions.
The city where the bank is located.
The primary address of the bank.
The postal code of the bank's address.
The province or state of the bank's location, if applicable.
Bank area
The routing number of the bank, required for bank transfers in certain countries.
The Bank Identifier Code (BIC), used in international transactions.
The transit number used to identify the bank branch.
The number that identifies the financial institution.
The type of bank transfer to be processed.
paymentData objectnullable
Details about the payment channel used for the payout.
The payment channel used for the transaction
payoutData objectnullable
Details related to the payout, including fee responsibility and currency.
Indicates who bears the fee for the transaction.
The source currency of the payout.
Responses
- 201
Successfully created a new payout request.
- application/json
- Schema
- Example (from schema)
Schema
data objectrequired
Possible values: [registered, in_progress, completed, failed, cancelled, rejected, need_action]
The current status of the payout operation. See more info
Unique code identifying the specific payout.
{
"data": {
"payoutStatus": "registered",
"payoutNumber": "payout-123456"
}
}