Skip to main content

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

Body

required

Details of the payout request to be created, including shop ID, payout specifics, purpose, and optional settings.

    shopId integerrequired

    The unique identifier of the shop initiating the payout. How to get your shopId

    payout objectrequired

    Details of the payout.

    cost objectrequired
    amount stringrequired

    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.

    currency stringrequired

    Possible values: >= 3 characters and <= 3 characters

    Specifies the currency in ISO 4217 alphabetic code format for fiat (e.g., USD) or the cryptocurrency code (e.g., BTC, ETH). If a cryptocurrency is specified, the cryptoTokenStandard field must also be provided to define the token's blockchain standard.

    payoutNumber stringrequired

    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.

    region stringnullable

    For some providers, it is mandatory to specify the payout region. The region should be specified in ISO 3166-1 alpha-2 code format.

    cryptoTokenStandard string

    The standard of the cryptocurrency token, required if the currency used is crypto.

    purpose stringnullable

    Possible values: <= 128 characters

    The purpose or reason for the payout request.

    providerCode stringrequired

    Determines which payment provider should be used to process the payout.

    acquirerCode stringrequired

    Identifies the specific acquirer responsible for processing payouts.

    instrumentType stringrequired

    Possible values: [card, bank_transfer, wallet, wallet, crypto_wallet, voucher]

    Specifies the instrument type. See available instrument types

    webhookUrl urinullable

    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.

    dataEntryMode stringnullable

    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.

    paymentSettingsAlias stringnullable

    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. Здесь указываются данные пользователя, который запросил выплату.

    customerId string

    A unique identifier for the customer. The customerId should be specific to the shopId and must be unique within each shopId.

    firstName stringrequired

    First name of the customer.

    lastName stringrequired

    Last name of the customer.

    middleName string

    Middle name of the customer, if applicable.

    phone string

    Customer's phone number, in international format.

    email email

    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.

    firstName stringnullable

    The first name.

    lastName stringnullable

    The last name.

    middleName stringnullable

    The middle name, if any.

    phone stringnullable

    The phone number, including the country code.

    email stringnullable

    The email address.

    birthDate string: dd.mm.yyyynullable

    The date of birth in the format DD-MM-YYYY.

    ipAddress stringnullable

    The IP address.

    beneficiaryName stringnullable

    The name of the beneficiary.

    beneficiarySurname stringnullable

    The surname of the beneficiary.

    addressData objectnullable

    Address information.

    countryCode stringnullable

    The ISO 3166-1 alpha-2 country code of the location.

    state stringnullable

    The state of the address.

    region stringnullable

    The ISO 3166-1 alpha-2 country code of the recipient's or sender's location.

    city stringnullable

    The city of the address.

    zipCode stringnullable

    The zip code of the address.

    address stringnullable

    The primary address.

    documentData objectnullable

    Document identification.

    identityDocumentId stringnullable

    The identification document number.

    TIN stringnullable

    The Individual Taxpayer Identification Number, applicable in some jurisdictions.

    RUT stringnullable

    Unique Taxpayer Identification Number (RUT), used primarily in Chile.

    cardData objectnullable

    Information required for processing a payout via credit card

    cardNumber stringnullable

    The card number.

    cardHolderName stringnullable

    Name printed on the card.

    expireMonth stringnullable

    Expiration month of the card.

    expireYear stringnullable

    Expiration year of the card.

    walletData objectnullable

    Information required for processing a payout via e-wallet.

    walletType stringnullable

    The type of e-wallet

    walletId stringnullable

    The e-wallet identifier.

    walletName stringnullable

    The e-wallet name.

    walletHolderName stringnullable

    The name of the e-wallet holder.

    bankTransferData objectnullable

    Information required for processing a payout via bank transfer.

    accountNumber stringnullable

    The bank account number.

    accountType stringnullable

    The type of bank account (e.g., Savings, Checking).

    accountName stringnullable

    The name associated with the bank account.

    bankName stringnullable

    The name of the bank.

    bankBranch stringnullable

    The branch of the bank where the account is held.

    bankCode stringnullable

    The specific code of the bank, often used in domestic transactions.

    bankCity stringnullable

    The city where the bank is located.

    bankAddress stringnullable

    The primary address of the bank.

    bankZipCode stringnullable

    The postal code of the bank's address.

    bankProvince stringnullable

    The province or state of the bank's location, if applicable.

    bankArea stringnullable

    Bank area

    routingNumber stringnullable

    The routing number of the bank, required for bank transfers in certain countries.

    bankBic stringnullable

    The Bank Identifier Code (BIC), used in international transactions.

    transitNumber stringnullable

    The transit number used to identify the bank branch.

    financialInstitutionNumber stringnullable

    The number that identifies the financial institution.

    transferType stringnullable

    The type of bank transfer to be processed.

    paymentData objectnullable

    Details about the payment channel used for the payout.

    channel stringnullable

    The payment channel used for the transaction

    payoutData objectnullable

    Details related to the payout, including fee responsibility and currency.

    feeBear stringnullable

    Indicates who bears the fee for the transaction.

    sourceCurrency stringnullable

    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.

    firstName stringnullable

    The first name.

    lastName stringnullable

    The last name.

    middleName stringnullable

    The middle name, if any.

    phone stringnullable

    The phone number, including the country code.

    email stringnullable

    The email address.

    birthDate string: dd.mm.yyyynullable

    The date of birth in the format DD-MM-YYYY.

    ipAddress stringnullable

    The IP address.

    beneficiaryName stringnullable

    The name of the beneficiary.

    beneficiarySurname stringnullable

    The surname of the beneficiary.

    addressData objectnullable

    Address information.

    countryCode stringnullable

    The ISO 3166-1 alpha-2 country code of the location.

    state stringnullable

    The state of the address.

    region stringnullable

    The ISO 3166-1 alpha-2 country code of the recipient's or sender's location.

    city stringnullable

    The city of the address.

    zipCode stringnullable

    The zip code of the address.

    address stringnullable

    The primary address.

    documentData objectnullable

    Document identification.

    identityDocumentId stringnullable

    The identification document number.

    TIN stringnullable

    The Individual Taxpayer Identification Number, applicable in some jurisdictions.

    RUT stringnullable

    Unique Taxpayer Identification Number (RUT), used primarily in Chile.

    cardData objectnullable

    Information required for processing a payout via credit card

    cardNumber stringnullable

    The card number.

    cardHolderName stringnullable

    Name printed on the card.

    expireMonth stringnullable

    Expiration month of the card.

    expireYear stringnullable

    Expiration year of the card.

    walletData objectnullable

    Information required for processing a payout via e-wallet.

    walletType stringnullable

    The type of e-wallet

    walletId stringnullable

    The e-wallet identifier.

    walletName stringnullable

    The e-wallet name.

    walletHolderName stringnullable

    The name of the e-wallet holder.

    bankTransferData objectnullable

    Information required for processing a payout via bank transfer.

    accountNumber stringnullable

    The bank account number.

    accountType stringnullable

    The type of bank account (e.g., Savings, Checking).

    accountName stringnullable

    The name associated with the bank account.

    bankName stringnullable

    The name of the bank.

    bankBranch stringnullable

    The branch of the bank where the account is held.

    bankCode stringnullable

    The specific code of the bank, often used in domestic transactions.

    bankCity stringnullable

    The city where the bank is located.

    bankAddress stringnullable

    The primary address of the bank.

    bankZipCode stringnullable

    The postal code of the bank's address.

    bankProvince stringnullable

    The province or state of the bank's location, if applicable.

    bankArea stringnullable

    Bank area

    routingNumber stringnullable

    The routing number of the bank, required for bank transfers in certain countries.

    bankBic stringnullable

    The Bank Identifier Code (BIC), used in international transactions.

    transitNumber stringnullable

    The transit number used to identify the bank branch.

    financialInstitutionNumber stringnullable

    The number that identifies the financial institution.

    transferType stringnullable

    The type of bank transfer to be processed.

    paymentData objectnullable

    Details about the payment channel used for the payout.

    channel stringnullable

    The payment channel used for the transaction

    payoutData objectnullable

    Details related to the payout, including fee responsibility and currency.

    feeBear stringnullable

    Indicates who bears the fee for the transaction.

    sourceCurrency stringnullable

    The source currency of the payout.

Responses

Successfully created a new payout request.

Schema
    data objectrequired
    payoutStatus string

    Possible values: [registered, in_progress, completed, failed, cancelled, rejected, need_action]

    The current status of the payout operation. See more info

    payoutNumber stringrequired

    Unique code identifying the specific payout.

Loading...