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.
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. The number of decimal places should comply with the ISO 4217 standard for the specified currency.
Possible values: >= 3 characters and <= 3 characters
Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters.
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).
For some providers, it is mandatory to specify the payout region. The region should be specified in ISO 3166-1 alpha-2 code format.
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]
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.
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.
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.
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.
Possible values: [bank_wire, sepa, swift, sbp, card2card, pix, online_banking, qris, promptpay, vietqr, vietnambanksqr, virtual_account, khipu, giropay, eps, open_finance]
Applicable only when instrumentType is bank_transfer. Specifies the type of bank transfer. See details about transferType. If instrumentType is bank_transfer and transferType is not provided, but there is only one possible transferType configured for the shop, it will be selected automatically by the system.
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.
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.
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.
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.
Possible values: [bank_wire, sepa, swift, sbp, card2card, pix, online_banking, qris, promptpay, vietqr, vietnambanksqr, virtual_account, khipu, giropay, eps, open_finance]
Applicable only when instrumentType is bank_transfer. Specifies the type of bank transfer. See details about transferType. If instrumentType is bank_transfer and transferType is not provided, but there is only one possible transferType configured for the shop, it will be selected automatically by the system.
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]
The current status of the payout operation. See more info
Unique code identifying the specific payout.
{
"data": {
"payoutStatus": "registered",
"payoutNumber": "payout-123456"
}
}