Statuses Errors
These guidelines exist to prevent financial losses when implementing payout cascading and transaction status handling. Failure to follow them may lead to losses that cannot be compensated.
The scenario to avoid
- A merchant sends a payout API request.
- A failure occurs.
- The failure is incorrectly interpreted as a failed transaction.
- The transaction is retried through the next gateway in the cascade.
- Both transactions succeed.
- The end user receives a double payout and does not return the extra amount.
- A financial loss occurs.
Safe-status guidelines
- Payouts — in uncertain situations, or cases not explicitly documented, set the financial status to
success. - Payments — dually, in uncertain situations set the financial status to
failure. - A payout or payment status may only change on:
3.1. Initial assignment of the safe value (success for payouts, failure for payments).
3.2. Receipt of the initial status during transaction creation.
3.3. Receipt of atransaction_status/payout_status.
Important considerations
- Assign a safe status (failure for payments, success for payouts) before attempting the API request.
- On a communication error, or if no status is received during transaction creation, the transaction status must remain unchanged.
- Likewise, on a communication error or missing status during a status request, keep the status unchanged.
- If callbacks are not received or lack the required value, keep the status unchanged.
- On undocumented error messages, or messages explicitly asking you to contact technical support, mark the transaction as requiring manual review. Its financial status is unknown, so it must not be retried through another provider.
Transaction status codes
Here is a list of transaction status codes and its description. Use these to understand current state of the transaction.
Card processing / Invoices
processing Transaction is processing.
failed (final) Transaction has been failed.
completed (final) Transaction has been completed successfully.
refunded (final) Transaction has been refunded.
chargeback (final) Chargeback.
p2p
waiting_payment Transaction awaiting payment.
processing Transaction is processing.
paid Transaction received a payment.
failed (final) Transaction has been failed.
completed (final) Transaction has been completed successfully.
refunded (final) Transaction has been refunded.
chargeback (final) Chargeback.
payout
payout_filled Payout has been filled.
payout_completed (final) Payout has been completed.
payout_failed (final) Payout has been failed.
Error types
Whenever a request is unsuccessful, the API will return an error response with an error code and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.
For better assistance, support your request to the tech team with the request ID you've received in the response.
API Error list
| Message | Code | HTTP Status Code |
|---|---|---|
| Transaction cannot be processed. Too many executed transactions. Try again in 12 hours | 104 | 401 |
| You've reached the limit of sum allowed per day. Try tomorrow, please. | 334 | 401 |
| Project's ID is missing. | 400001 | 403 |
| Amount/price is required. | 400002 | 401 |
| Signature is missing. | 400003 | 401 |
| Customer not found. | 400004 | 403 |
| Signature is invalid. | 400005 | 403 |
| Payment ID or Order ID is required. | 400006 | 401 |
| Description is required. | 400007 | 401 |
| IP is required. | 400008 | 401 |
| Token is required. | 400009 | 401 |
| CC number is required | 400010 | 401 |
| Expiration month is required. | 400011 | 401 |
| Expiration year is required. | 400012 | 401 |
| Security code is required. | 400013 | 401 |
| Payment ID is required. | 400015 | 401 |
| Refund ID is required. | 400016 | 401 |
| Payout amount is required. | 400017 | 401 |
| Destination card is required. | 400018 | 401 |
| Payout ID or Order ID is required. | 400019 | 401 |
| Start Date (YYYY-MM-DD HH:MM:SS) is required. | 400020 | 401 |
| End Date (YYYY-MM-DD HH:MM:SS) is required. | 400021 | 401 |
| User's email is missing. | 400023 | 401 |
| Currency is missing. | 400025 | 401 |
| Payout ID is required. | 400029 | 401 |
| Phone number is required. | 400031 | 401 |
| Token is invalid or expired. | 400036 | 401 |
| Invalid price/amount format. Valid is fixedpoint string, ex: 123.2 | 400039 | 401 |
| Order ID is missing | 400040 | 401 |
| Invalid payment ID type. Must be a string. | 400043 | 401 |
| Invalid order ID type. Must be a string. | 400044 | 401 |
| result_url is missing. | 400045 | 401 |
| birth_date is missing. ex 05.06.1987 | 400046 | 401 |
| expiration_month is required. ex 06 | 400047 | 401 |
| expiration_year is required. ex. 22 | 400048 | 401 |
| birth_place is missing. ex Moscow | 400049 | 401 |
| country_of_citizenship is missing. ex RU | 400050 | 401 |
| country_of_residence is missing. ex RU | 400051 | 401 |
| document_type is missing. ex passport or ID | 400052 | 401 |
| document_issuer is missing. ex MFA of Russia | 400053 | 401 |
| document_series is missing. ex P | 400054 | 401 |
| document_number is missing. ex 23 23456891 | 400055 | 401 |
| document_issued_at is missing. ex 05.06.2011 | 400056 | 401 |
| document_valid_until is missing. ex 05.06.2029 | 400057 | 401 |
| beneficiary_first_name is missing. ex Ivan | 400058 | 401 |
| beneficiary_last_name is missing. ex Ivanov | 400059 | 401 |
| phone is missing. ex 77777777777 | 400060 | 401 |
| Pan is in blacklist | 400061 | 401 |
| Pan is not in whitelist | 400062 | 401 |
| Website is not in whitelist | 400063 | 401 |
| IP does not match url | 400066 | 401 |
| Amount is invalid | 400067 | 401 |
| Card balance is exceeded | 400068 | 401 |
| Order ID must be unique | 400069 | 401 |
| Issuer declined the transaction | 400070 | 401 |
| Card limit has been exceeded | 400071 | 401 |
| Transaction has been declined by antufraud system | 400072 | 401 |
| Transaction with this order ID does not exist | 400074 | 401 |
| General processing error | 400075 | 401 |
| Partial amount retrieve not allowed | 400076 | 401 |
| Transaction declined by gateway | 400077 | 401 |
| Credit card info is invalid | 400078 | 401 |
| Credit card number is invalid | 400079 | 401 |
| Credit card holder name is invalid | 400080 | 401 |
| One or more request parameters are invalid | 400081 | 401 |
| Payment session timeout error | 400082 | 401 |
| Credit card is expired | 400084 | 401 |
| Partial refund is not allowed | 400094 | 401 |
| Multiple refunds are not supported | 400095 | 401 |
| Partial charge is not allowed | 400096 | 401 |
| Retrieve period has been expired | 400097 | 401 |
| CVC code is invalid | 400098 | 401 |
| Email provided is invalid | 400099 | 401 |
| Credit card is inactive | 400100 | 401 |
| Failed to get available payment gateways | 400101 | 401 |
| Failed to get payment status | 400102 | 401 |
| Failed to get initialize a payment | 400103 | 401 |
| Failed to create a token | 400104 | 401 |
| Failed to create refund | 400106 | 401 |
| Failed to get refund status | 400107 | 401 |
| Failed to create payout | 400108 | 401 |
| Failed to get payout status | 400109 | 401 |
| Failed to get refunds list | 400110 | 401 |
| Failed to get transactions list | 400111 | 401 |
| Failed to get payouts list | 400112 | 401 |
| Failed to process a payment | 400115 | 401 |
| Failed to reverse the transaction | 400120 | 401 |
| Failed to process the refund | 400121 | 401 |
| Failed to process callback | 400122 | 401 |
| Endpoint not implemented | 400124 | 401 |
| Failed to get balance. | 400126 | 401 |
| Failed to get payout history. | 400127 | 401 |
| Failed to execute cron job | 400131 | 401 |
| Invalid request headers. | 400135 | 401 |
| Failed to get rates | 400136 | 401 |
| Operation is not supported for this card | 400300 | 401 |
| Transaction has been declined by cardholder | 400301 | 401 |
| Card PIN code error | 400302 | 401 |
| Credit card is restricted | 400303 | 401 |
| Credit card status is invalid | 400304 | 401 |
| No transactions found for this order id | 400307 | 401 |
| The number of payment attempts exceeded | 400311 | 401 |
| New payment attempt already started | 400312 | 401 |
| Specified currency is not supported | 400317 | 401 |
| 3D-Secure authentication failed | 400319 | 401 |
| 3D-Secure authentication has been canceled | 400320 | 401 |
| 3D-Secure preprocess info is missing | 400321 | 401 |
| Credit card is not involved in 3DS | 400322 | 401 |
| Operation has been declined | 400325 | 401 |
| Temporal failure, try later please | 400326 | 401 |
| Credit card type is unsupported | 400327 | 401 |
| return url has not been set | 400332 | 401 |
| invalid credentials | 400333 | 401 |
| You have reached maximum sum for operation | 400334 | 401 |
| Unknown error. Contact technical support please | 400336 | 401 |
| QIWI account number is required | 400337 | 401 |
| Failure, try another card, please | 400338, 400339 | 401 |
| This currency is not supported | 400340 | 401 |
| Start Date (YYYY-MM-DD) or (YYYY-MM-DD HH:MM:SS) is required | 400341 | 401 |
| End Date (YYYY-MM-DD) or (YYYY-MM-DD HH:MM:SS) is required | 400342 | 401 |
| Include failed should be boolean | 400343 | 401 |
| Range is not valid | 400344 | 401 |
| Insufficient funds | 400345 | 401 |
| Wrong sandbox card | 400346 | 401 |
| Wrong sandbox card cvc | 400347 | 401 |
| Unexpected sandbox message | 400348 | 401 |
| Transaction with this payment id is not found | 400349 | 401 |
| Transaction with this refund id is not found | 400350 | 401 |