Orders, Payouts, and P2P​

Request identifier in error responses:

• Error responses of the API now contain the requestId field; the same value is returned in the x-request-id response header. Include it when contacting technical support about a failed request — it speeds up the search for the request in the logs.

New Acquirer group in the Status Codes reference:

• The Status Codes reference now includes the new source 3 — status codes that originated on the acquirer side (bank, card issuer, payment system). The group contains the sections Bank Processing (3-01-XX), Card Processing (3-02-XX), Payment System Processing (3-03-XX), and Acquirer Processing Errors (3-04-XX).
• The codes 2-07-03, 2-07-06 – 2-07-08, 2-09-12, and 2-09-13 have been removed from the reference: these decline reasons are now reported with the 3-XX-XX codes.
• The code 2-05-28 has been removed; its meaning (Failed OTP verification) is now carried by 2-05-26.
• New codes 1-07-29 (the maximum number of allowed final status transitions has been reached), 2-07-22 (no payment methods available), and 2-11-08 (payout method temporary unavailable) have been added.
• The descriptions of several codes have been updated to match the production directory: 2-03-02, 2-05-04 – 2-05-07, 2-05-17, 2-05-18, 2-05-24, 2-11-06, and 2-11-07.

Release 29.09.2026​

Orders, Payouts, and P2P​

Removed statusReason from status responses and callbacks (Breaking):

• The statusReason field is no longer returned. It could contain internal system messages that did not reflect the actual reason for the status; use the statusCode and statusDescription fields instead — see the Status Codes reference.
• Affected endpoints:
  • GET /order/{shopId}/{orderNumber} — Retrieve Order Details — and the Order Status Callback.
  • GET /payouts/{shopId}/{payoutNumber} — Retrieve Payout Status — and the Payout Status Callback.
  • GET /p2p/{shopId}/{p2pNumber} — Retrieve P2P Transaction Status — and the P2P Status Callback.
• If your integration parses statusReason, remove the dependency on this field.

Status Codes reference synchronized with the production directory:

• The Status Codes reference now includes the provider codes introduced by payment integrations over the past months: 2-01-04, 2-02-23 – 2-02-42, the Payment Method Definition group (2-03-XX), 2-04-05, 2-05-10 – 2-05-28, 2-06-03/2-06-04, 2-07-14 – 2-07-21, 2-08-03/2-08-04, the Wallet Errors group (2-10-XX), and the Payout Processing group (2-11-XX), as well as the system code 1-07-28.
• The system behavior itself is unchanged; this update only documents the codes already returned in responses and callbacks.

Underscores allowed in order, payout, and p2p numbers:

• The orderNumber, payoutNumber, and p2pNumber fields now accept the underscore character (_) in addition to Latin letters, numbers, and hyphens. The validation is applied consistently in the Create Order, Create Payout Request, and Create P2P Transaction endpoints.

Release 15.09.2026​

Orders​

Payment settings alias in order details and callbacks:

• Each item of the payments array now contains the optional paymentSettingsAlias field — the alias of the payment configuration that processed the payment attempt. Use it to identify which configuration was used when several configurations differ only by alias.
• The field is returned only for configurations that have an alias.
• Affected endpoints:
  • GET /order/{shopId}/{orderNumber} — Retrieve Order Details.
  • Order Status Callback.
  • For payouts, the same field is returned in the payoutTransactions array items of Retrieve Payout Status and the Payout Status Callback.
• For details, see Alias Setup and Usage Guide.

Release 01.09.2026​

Orders and Payouts​

Provider fee in status responses and callbacks:

• A new optional providerFee field has been added to the payments array items (Retrieve Order Details, Order Status Callback) and to the payoutTransactions array items (Retrieve Payout Status, Payout Status Callback).
• The field contains the fee charged by the payment provider for the transaction (amount and currency) and is null when the provider did not report it.

Provider payment name for payout transactions:

• The providerPaymentName field (the name of the final payment provider that processed the transaction) is now also returned in the payoutTransactions array items of the payout status response and callback — previously it was available only for order payments.

Removed isDefault from the payment and payout methods responses:

• The isDefault field is no longer returned in the Retrieve Payment Methods and Retrieve Payout Methods responses.
• The default-method mechanics it referred to is no longer used: when the request does not identify a single payment method, the selection follows the shop's First attempt settings — see Payment Flow.

New walletType value company_extra:

• The walletType parameter now supports a third value, company_extra, used when a provider exposes more than one corporate processing flow for the same wallet. The value is accepted in Create Order, Create Payout Request, and Retrieve Required Payout Fields, and is returned in the walletTypes arrays of the payment/payout methods endpoints.
• For details, see Payment and Payout Methods — WalletType.

Orders​

Decline notice on the retry form of the payment page:

• When a payment attempt fails and a new attempt requires the payer to enter additional data (for example, after a cascading retry to a method with different custom fields), the payment page now shows the data entry form together with a notice that the previous attempt was declined.
• For details, see Payment Flow — Automatic retries: cascading.

Release 04.08.2026​

Orders​

Renamed status code 1-01-07 and automatic assignment of system status codes:

• The description of status code 1-01-07 has been changed from Provider circuit breaker open to Payment gateway is temporarily unavailable.
• The system now automatically assigns codes 1-01-02, 1-01-06, and 1-01-07 in the transaction details instead of the generic 2-01-01 (General decline) when a payment fails on the system side — for example, when the provider did not respond within the timeout window.
• See the updated Status Codes reference.

Manual retries reuse the payment method of the failed attempt:

• When cascading is disabled and payment attempts remain, the payer can retry the payment with the Try Again button. The retry reuses the payment method determined for the previous attempt.
• A retry is offered only if the status code of the failed attempt allows it (see the Retry allowed column in the Status Codes reference); otherwise the order fails immediately with 1-07-26.
• Custom field values entered by the payer are reused for the retry where possible; sensitive data such as card details, wallet and bank account requisites is requested again.
• For details, see Payment Flow — Manual retries.

Payment page timer is reset on retries:

• When a new payment attempt is created for an order (a manual retry or a cascading retry), the payment page timeout is reset to 15 minutes from the start of that attempt — this applies even when timeLimit was specified in the Create Order request.

Release 21.07.2026​

Orders and Payouts​

Expanded Status Codes reference:

• The status code directory has been extended with new codes:
  • System codes 1-01-06 (DNS resolution failed) and 1-01-07.
  • General provider code 2-01-03 (payment amount does not match the required amount multiple).
  • Provider request validation codes 2-02-09 and 2-02-11 – 2-02-22 (invalid parameter format, merchant/terminal not found, IP not whitelisted, amount below/above limit, and others).
  • Provider 3DS codes 2-04-03 (3DS failed) and 2-04-04 (3DS authentication cancelled or abandoned).
  • Antifraud code 2-05-09 (Security violation) and limits code 2-06-02 (Merchant processing limit reached).
  • Payment processing codes 2-07-05 – 2-07-13.
  • A new Card Processing group 2-09-XX with detailed card decline reasons (invalid card number, expired card, unsupported BIN, issuer limits, and others).
• The description of code 2-02-06 has been fixed to Duplicate request.
• See the updated Status Codes reference for the full list with the Retry allowed flags.

Orders​

Clarified behavior of the Use request parameters only mode:

• When the first attempt mode is Use request parameters only and the selected payment method requires fields that were not passed in the request, the data is not collected on the payment page — the payment fails with status code 1-07-01 (Missing required parameters for the selected payment method).
• For details, see Payment Flow — Use request parameters only.

Payouts​

Unified bank directory:

• For payout methods that require selecting a bank, a unified bank directory can be enabled for your company: Retrieve Required Payout Fields then returns the platform's unified bank codes instead of provider-specific ones, so the same banks have the same codes regardless of the provider. The same codes are used for bank selection on the payment page in purchases.
• The platform maps the unified code to the provider's own code when sending the request, and the selected bank is reused on cascading retries through another provider.
• The feature is enabled per company on request and covers the providers for which the mapping has been configured; otherwise the provider's own codes are used as before.
• For details, see Payouts — Unified Bank Directory.

Release 07.07.2026​

Payouts​

New paymentPageDesign.alias parameter in payout creation:

• The Create Payout Request endpoint now accepts an optional paymentPageDesign object with an alias field, the same way as the Create Order endpoint.
• Use it when the payout data is collected on the payment page and several page designs are configured for your shop: the alias selects which design is applied. The alias values are set through technical support.

Changelog​

Orders​

New statusCode and statusDescription fields for individual payments:

• Each payment in the data.payments array now includes two new optional fields:
  • statusCode — status code that provides additional context for the current payment status.
  • statusDescription — human-readable description corresponding to statusCode.
• This complements the order-level statusCode and statusDescription fields, giving you the reason for the status of each individual payment attempt within an order.
• Affected endpoint:
  • Retrieve Order Details — GET /api/v1/order/{shopId}/{orderNumber}
• For the full list of status codes and their meaning, see the Status Codes reference.

Changelog​

Orders and Payouts​

New walletType parameter for wallet payments and payouts:

• A new optional walletType parameter has been added for operations with instrumentType = wallet. It selects how the wallet operation is processed by the provider when an acquirer supports several wallet flows (for example, a personal vs. corporate account).
• Supported values:
  • personal — the operation is processed as a transfer to a personal account.
  • company — the operation is processed as a transfer to a corporate account.
• The parameter is optional.
• Affected endpoints:
  • POST /order — Create Order — paymentSettings.walletType in the request body.
  • POST /payouts — Create Payout Request — walletType at the top level of the request body.
  • POST /payouts/fields — Retrieve Required Payout Fields — walletType inside the payoutSettings object of the request body.
  • GET /shops/{shopId}/payment-methods — Retrieve Payment Methods — walletTypes array in the response. The field is returned only when the payment method has at least one walletType configured.
  • GET /payouts/payout-methods/{shopId} — Retrieve Payout Methods — walletTypes array in the response. The field is returned only when the payment method has at least one walletType configured.
• For details, see Payment and Payout Methods — WalletType.

Orders​

Clarified behavior for provider callbacks with a different payment amount or currency:

• The Order Status Model documentation now describes how the system handles callbacks where the provider returns a payment amount or currency that differs from the original order:
  • Amount changes can be accepted automatically within a per-shop allowed range configured by technical support. Outside the range, the order moves to need_action with status code 2-07-04.
  • Currency changes are never accepted automatically — the order always moves to need_action with status code 2-07-04.
• The system behavior itself is unchanged; this update only documents the existing logic.
• For details, see Order Status Model — Payment Amount and Currency Changes by the Provider.

Documented order processing timeout:

• The Order Status Model documentation now describes the processing timeout that moves a payment order to failed when no terminal response is received from the provider.
• The default timeout is 7 days from order creation. It can be increased per shop and payment setting by technical support for integrations where a longer wait is expected.
• The timeout applies to payment orders only and does not apply to payouts, P2P transactions, or crypto payments.
• The system behavior itself is unchanged; this update only documents the existing logic.
• For details, see Order Status Model — Order Processing Timeout.

New Retry allowed column in the Status Codes reference:

• The Status Codes reference now includes a Retry allowed column for each status code.

Changelog​

Crypto​

Renamed cryptocurrency asset_code values:

• The following asset_code values have been renamed to use blockchain-based suffixes instead of token standard suffixes. If you use the asset_code format in cost.currency, update your integration to the new values:
  • USDC_ERC20 → USDC_ETH
  • USDT_TRC20 → USDT_TRX
  • USDT_ERC20 → USDT_ETH
  • USDT_BEP20 → USDT_BSC
  • USDT_SPL → USDT_SOL
  • MATIC_ERC20 → MATIC_ETH
  • USDC_TRC20 → USDC_TRX
• Affected endpoints and callbacks:
  • POST /order — Create Order
  • POST /payouts — Create Payout Request
  • GET /order/{shopId}/{orderNumber} — Retrieve Order Details
  • GET /payouts/{shopId}/{payoutNumber} — Retrieve Payout Status
  • Order Status Callback
  • Payout Status Callback
• For the full list of supported cryptocurrencies and their formats, see the Cryptocurrency Reference Guide.

Orders​

Automatic finalization from need_action on payment amount mismatch:

• Orders moved to need_action with status code 2-07-04 due to a provider callback with a different payment amount can now be resolved automatically when a follow-up callback arrives with the correct amount.
• Automatic resolution requires the Automatic finalization of orders in the "Need action" status setting to be enabled for the shop. Otherwise, the order remains in need_action and must be resolved manually.
• For details, see Order Status Model — Need Action.

Orders, Payouts, and P2P​

New statusCode and statusDescription fields in responses and callbacks:

• Each response and callback payload now includes two new optional fields at the top level of the data object:
  • statusCode — status code that provides additional context for the current order, payout, or P2P status.
  • statusDescription — human-readable description corresponding to statusCode.
• Affected endpoints and callbacks:
  • Retrieve Order Details — GET /api/v1/order/{shopId}/{orderNumber}
  • Retrieve Payout Status — GET /api/v1/payouts/{shopId}/{payoutNumber}
  • Retrieve P2P Transaction Status — GET /api/v1/p2p/{shopId}/{p2pNumber}
  • Order Status Callback
  • Payout Status Callback
  • P2P Status Callback
• For the full list of status codes and their meaning, see the Status Codes reference.

Changelog​

Orders​

Added middleName to payer personal data:

• Added payer.personalData.middleName to the Create Order request.

Changelog​

Orders​

Cryptocurrency Payment Structure Unification (Breaking):

The cryptocurrency payment parameters in the Create Order request have been restructured for clarity and to group merchant-side data under a dedicated recipient object. See the updated Cryptocurrency Reference Guide for full details.

• Removed the cryptoPayment object. Its fields have been moved and renamed as described below.
• Added order.cost.tokenStandard — the token standard of the customer's wallet cryptocurrency (for example, TRC20, ERC20, BEP20). Replaces the former cryptoPayment.walletTokenStandard. Optional. Should be provided for token-based cryptocurrencies when using crypto_currency_code in order.cost.currency; not needed for native cryptocurrencies or when using asset_code format.
• Added recipient object with the nested merchantBalance object, which declares the currency of the merchant's balance. The merchant balance currency may be fiat or crypto and is independent from order.cost.currency (the currency the customer pays in).
  • recipient.merchantBalance.currency — the merchant balance currency code (replaces the former cryptoPayment.accountCurrency.currency). Required when the merchantBalance object is provided.
  • recipient.merchantBalance.tokenStandard — the token standard of the merchant balance currency (replaces the former cryptoPayment.accountCurrency.networkTokenStandard). Optional. Should be provided when merchantBalance.currency is a token-based cryptocurrency; ignored for fiat currencies.

Migration example:

Before:

{
  "order": {
    "cost": {
      "amount": "20",
      "currency": "USDT"
    }
  },
  "cryptoPayment": {
    "walletTokenStandard": "TRC20",
    "accountCurrency": {
      "currency": "USDC",
      "networkTokenStandard": "TRC20"
    }
  }
}

After:

{
  "order": {
    "cost": {
      "amount": "20",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "recipient": {
    "merchantBalance": {
      "currency": "USDC",
      "tokenStandard": "TRC20"
    }
  }
}

E-wallet Payer Data Support:

• Added walletData object to the payer field in the Create Order endpoint.
• Use this object to pass the payer's e-wallet details for providers that accept payments via digital wallets.
• Available fields (all optional): walletId, walletType, walletName, walletHolderName.

Added tokenStandard to cost for partial operations:

The tokenStandard field has been added to the cost object in the following endpoints, mirroring order.cost.tokenStandard for consistency across the order lifecycle:

• POST /order/capture — cost.tokenStandard
• POST /order/refund — cost.tokenStandard

P2P​

Added tokenStandard to cost:

• Added p2p.cost.tokenStandard to the Create P2P Transaction request. Optional.
• Should be provided for token-based cryptocurrencies when using crypto_currency_code in p2p.cost.currency; not needed for native cryptocurrencies or when using asset_code format.

Payouts​

Added tokenStandard to payout.cost:

• Added payout.cost.tokenStandard to the Create Payout Request endpoint. Optional. Should be provided for token-based cryptocurrencies when using crypto_currency_code in payout.cost.currency; not needed for native cryptocurrencies or when using asset_code format.
• The existing payout.cryptoTokenStandard field is unchanged.

Changelog​

Payment Methods​

New Instrument Type mobile_top_up:

• Added mobile_top_up to the list of supported values for instrumentType. This instrument type represents payments made by topping up a mobile phone number. See Payment and Payout Methods for details.
• Affected endpoints:
  • POST /order
  • GET /order/{shopId}/{orderNumber}
  • GET /shops/{shopId}/payment-methods
  • POST /payouts
  • GET /payouts/{shopId}/{payoutNumber}
  • GET /payouts/payout-methods/{shopId}
  • POST /payouts/fields

New Card Brands humo and uzcard:

• Added humo and uzcard to the list of supported card brands.
• Affected fields and endpoints:
  • paymentSystem in GET /order/{shopId}/{orderNumber} payment details
  • paymentSystem in GET /payouts/{shopId}/{payoutNumber} payout details

Changelog​

Orders​

Removed deprecated redirect entry mode:

• The redirect value was deprecated and has been removed from the entryMode enum.
• Affected endpoints:
  • POST /order
  • GET /order/{shopId}/{orderNumber}
  • GET /shops/{shopId}/payment-methods

Changelog​

Orders​

Bank Transfer Payer Data Support:

• Added bankTransferData object to the payer field in the Create Order endpoint.
• When creating an order with instrumentType = bank_transfer, merchants can now pass the payer's bank transfer details (such as bankCode, accountName, accountNumber, etc.) in payer.bankTransferData.
• This allows providing bank-related information for the payer upfront, reducing the need for manual entry on the payment page.
• Requires the company setting "Use customer data as payer information" to be enabled. This setting can be found in the Dashboard under Settings -> Company tab.

Need Action automatic resolution:

• Orders in need_action status caused by a provider response timeout can now be resolved automatically. If the provider's response is eventually received.
• See Order Status Model — Resolution.