API error reference

Complete list of error codes returned by the payment gateway. Use Cmd/Ctrl-F to jump to a code or message. New entries are added as part of each release; see the changelog for the version they appeared in.

Where each code can show up

• Synchronous responses to API requests carry error_code and error_message fields, with HTTP 400.
• Callbacks carry the same fields on failed payments.
• Not-found responses since 6.7.0 follow a per-entity rule rather than a per-operation one. Operations whose underlying entity is a transaction or order (GET_TRANS_STATUS, GET_TRANS_STATUS_BY_ORDER, S2S CARD CAPTURE) return 101000 with a specific message. Operations against payment, schedule, or recurring entities (VOID, CREDITVOID, DELETE_SCHEDULE, UPDATE_SCHEDULE, RECURRING_SALE) continue to return 100000, also with specific messages. The per-action mapping lives in the changelog of the changelog and the table below.

---

Validation errors

These are returned synchronously when the request payload fails schema or business-rule validation. HTTP 400.

100000 and 101000: General validation

Error code	Error message	Sub-type	Possible reason	How to fix
100000	card_number: This value should not be blank.	Missing field	card_number not in the request payload.	Add card_number to the request.
100000	payer_card_exp_month: This value should not be blank.	Missing field	Expiry month not provided.	Send payer_card_exp_month (1-12).
100000	payer_card_exp_year: This value should not be blank.	Missing field	Expiry year not provided.	Send payer_card_exp_year (4-digit year).
100000	payer_card_cvv: This value should not be blank.	Missing field	CVV missing.	Include payer_card_cvv in the payload.
100000	order_id: This value should not be blank.	Missing field	Order identifier not sent.	Pass a unique order_id with each request.
100000	order_amount: This value should not be blank.	Missing field	Amount missing.	Include order_amount in the request.
100000	order_amount: This value should be greater than 0.	Invalid value	Amount is zero or negative.	Ensure order_amount > 0.
100000	order_currency: This value should not be blank.	Missing field	Currency code not sent.	Send a valid 3-letter ISO 4217 code.
100000	order_description: This value should not be blank.	Missing field	Description empty.	Provide a non-blank order_description.
100000	payee_card_number: This value should not be blank.	Missing field	Payee card number missing (payout).	Include payee_card_number for payout requests.
100000	term_url_3ds: This value should not be blank.	Missing field	3DS return URL not provided.	Set term_url_3ds to the cardholder redirect URL after 3DS.
100000	amount: Amount is not valid.	Invalid value	Amount format incorrect.	Send amount as a numeric value with up to 2 decimal places.
100000	card_exp_year: The date is expired and not valid.	Expired card	Expiry year in the past.	Use a valid, non-expired card.
100000	The expiration date of card is expired and not valid.	Expired card	Expiry date in the past.	Verify card expiry before sending the request.
100000	Request from this ip is not allowed.	IP restriction	Requesting IP not whitelisted.	Whitelist the IP in admin settings or send from an allowed IP.
100000	order_id: Duplicate payment.	Duplicate request	A payment with the same order_id already exists.	Use a unique order_id for every new attempt.
100000	merchant_key: Wrong merchant operation.	Auth / config	Merchant key is not permitted for this operation type.	Check that you are using the correct merchant key.
100000	Parameter is deprecated.	Retired parameter	S2S CARD CREATE_SCHEDULE or UPDATE_SCHEDULE still contains delays, which was retired in 6.7.0.	Remove delays and use delayed_first_payment with the matching first_payment_* parameters.
100000	schedule_id: Schedule is paused	Schedule state	The referenced schedule is paused.	Resume the schedule before sending recurring transactions.
100000	Schedule not found	Not found (schedule entity)	S2S CARD DELETE_SCHEDULE or UPDATE_SCHEDULE against an unknown schedule_id. The wording is Schedule not found (no is) as returned by the API.	Verify the schedule_id matches an existing schedule that has not already been deleted.
100000	schedule_id: Schedule cannot be used for non-recurring transaction	Schedule state	schedule_id passed for a one-time payment.	Remove schedule_id for non-recurring requests.
100000	Payment not found.	Not found (payment entity)	S2S CARD VOID or CREDITVOID against an unknown trans_id. Returned with HTTP 400.	Verify the trans_id matches an existing payment in a state that allows void / credit-void.
100000	Incorrect transaction	Not found (recurring init pair)	S2S CARD RECURRING_SALE whose recurring_first_trans_id + recurring_token pair does not match a valid recurring initial transaction. Surfaces only after schema validation passes.	Confirm the initial recurring transaction settled successfully and the recurring_token has not expired or been revoked.
100000	Void is not allowed	Operation restriction	Void is disabled for this merchant or payment.	Enable void in MID settings or contact support.
100000	Refund is not allowed	Operation restriction	Refund is disabled for this merchant or payment.	Enable refund in MID settings or contact support.
101000	Payment does not exist.	Status lookup	GET_TRANS_STATUS by payment_id with an unknown ID.	Verify the payment_id is correct and the payment was created successfully.
101000	Order does not exist.	Status lookup	GET_TRANS_STATUS by order_id with an unknown ID.	Verify the order_id.
101000	Transaction does not exist.	Status lookup	S2S CARD GET_TRANS_STATUS by trans_id with an unknown ID.	Verify the trans_id.
101000	Transaction does not exist.	Not found (CAPTURE)	S2S CARD CAPTURE against an unknown trans_id. Same wording as the status-lookup row above; client-side discrimination must use the request action field, not the message.	Verify the trans_id of the original authentication; ensure it has not already been captured or voided.

Breaking change in 6.7.0

101000 was added in changelog. Before 6.7.0, status-lookup not-found cases returned 100000 with the generic This value is not correct. message. If your integration matches on error_code to detect not-found state, update it to 101000.

101001 and 101002: Brand and connector

Error code	Error message	Possible reason	How to fix
101001	Brand not found	The card BIN could not be matched to a known brand, or the brand value sent with an APM request does not exist.	Check the brand value against the supported brand list; for cards, confirm the BIN range is covered.
101002	Bad connector request	The payment carries no connector name, or the resolved connector rejected the request as malformed.	Check that the MID is mapped to an existing connector; if it is, the connector rejected the payload - contact support with the payment_id.

---

Payment processing errors

Returned by the routing, builder, and flow stages after validation passes.

203xxx: Currency rates

Error code	Error message	Possible reason	How to fix
203001	Currency not found.	The rate provider (ECB, Bank-Ua, CurrencyScoop) has no entry for the requested currency.	Use a currency the configured rate provider publishes, or switch the provider.
203002	Base Currency not found in ECB XML.	ECB rate feed lacks the configured base currency.	Use a supported ECB base currency (e.g., EUR) or switch the rate provider.
203003	Base Currency not found in Bank-Ua XML.	Ukrainian bank rate feed missing the base currency.	Verify the base currency is available in the Bank-Ua feed.
203004	Currency rate not found.	Exchange rate for the currency pair is unavailable.	Check the currency pair is supported; update rate feed configuration.
203005	Currency not found.	Currency code does not exist in the system.	Use a valid ISO 4217 currency code.
203006	Base Currency not found in CurrencyScoop service.	CurrencyScoop feed lacks the base currency.	Verify CurrencyScoop config or change the base currency.
203007	Currency rate not retrieve.	The connector was asked for an exchange rate and answered unsuccessfully.	Retry the request; if it persists, check the connector's rate service configuration.

240001 and 204xxx: Traffic balancer / routing

Error code	Error message	Possible reason	How to fix
240001	Not available action. Check MID configuration.	Requested action is not enabled for the assigned MID.	Enable the action in MID configuration.
204001	Merchant mapping not found for current channel.	No merchant-to-channel mapping exists for this transaction.	Create a merchant mapping for the relevant channel in admin.
204002	Enabled merchant mappings or MIDs not found.	No active mappings / MIDs match transaction parameters.	Ensure at least one active merchant mapping or MID is configured.
204003	Payment type not supported.	Payment type (e.g., recurring) not enabled for the MID.	Enable the required payment type in MID settings.
204004	Payment method not supported.	Payment method not supported by the MID.	Add the required method to the MID configuration.
204005	Payment action not supported.	Action (capture, refund, etc.) is not enabled.	Enable the action in MID settings.
204006	Payment system/brand not supported.	Card scheme (Visa, MC, etc.) not accepted by this MID.	Configure the card brand in MID settings or route to a different MID.
204007	Day MID limit is not set or exceeded.	Daily limit missing or reached.	Set or increase the daily MID limit; or wait until the next day.
204008	Merchant mapping limit is not set or exceeded.	Merchant mapping limit missing or exceeded.	Update the merchant mapping limit configuration.
204009	Payment type not found.	Payment type ID does not exist.	Use a valid, configured payment type.
204010	Payment method not found.	Payment method ID does not exist.	Use a valid payment method; check configuration.
204011	Payment system/brand not found.	Card scheme identifier not recognised.	Verify the payment system / brand value in the request.
204012	Payment currency not found.	Currency not configured for this merchant / MID.	Add the currency to MID config or use a supported currency.
204013	Payment action not found.	Requested action code does not exist.	Use a valid action code.
204014	Month MID limit is exceeded.	Monthly processing limit reached.	Request a limit increase from the acquirer or wait for the new month.
204015	Week Merchant mapping limit is exceeded.	Weekly mapping limit reached.	Increase the weekly limit or wait for the new week.
204016	Payment currency not supported.	Currency not enabled for this MID.	Enable the currency in MID settings or use a supported currency.
204017	Payment amount after exchange equals 0.	Currency conversion results in zero (very small amount).	Increase the transaction amount or review conversion settings.
204018	Payment digital wallet not supported.	The MID does not accept the digital wallet used (Apple Pay, Google Pay).	Enable the wallet on the MID, or route the payment to a MID that supports it.
204019	Payment system/brand not supported for digital wallet.	The card brand inside the wallet token is not enabled for wallet traffic on this MID.	Enable that brand for wallet payments in MID settings.
204020	Exchange in payment not supported.	Routing needs a currency exchange the selected MID cannot perform.	Send the payment in a currency the MID supports, or configure exchange for it.
204021	MPI session response code is not authenticated.	The external MPI returned a not-authenticated 3DS result for this session.	Re-run 3DS authentication; do not retry with the same MPI session.
204022	Payment click to pay not supported.	Click to Pay is not enabled for the MID.	Enable Click to Pay in MID settings, or use a different payment method.

205xxx: Payment builders

Error code	Error message	Possible reason	How to fix
205001	Merchant mappings not found.	No merchant mapping exists for the given parameters.	Create the required merchant mapping in admin.
205002	Recurring is not supported by specified initial payment.	Initial payment does not have recurring enabled.	Make the initial payment with recurring=true and ensure it is in a valid state.
205003	Merchant not found.	merchant_key does not correspond to an existing merchant.	Verify the merchant_key in your request credentials.
205004	Payment not found.	Referenced payment ID does not exist.	Check the payment_id; confirm it was created successfully.
205005	Card token is invalid or not found.	Token does not exist or is malformed.	Re-tokenize the card or verify the token value.
205006	Card token is expired.	Token has passed its expiry.	Generate a new card token.
205007	Card token is not accessible.	Merchant is not authorised to use this token.	Use a token belonging to this merchant, or re-tokenize.
205008	This order is scheduled already.	A schedule already exists for this order_id.	Use a different order_id or manage the existing schedule.
205009	This order uses active schedule	The order is already attached to a schedule that is running.	Pause or delete the running schedule before attaching a new one.

208xxx and 209xxx and 210xxx: Payment flow

Error code	Error message	Possible reason	How to fix
208002	Not acceptable to request the 3DS for payment not in 3DS status.	3DS requested for a payment not awaiting 3DS.	Only trigger 3DS for payments in 3DS-pending status.
208003	Not acceptable to request the capture for payment not in pending status.	Capture attempted on a non-pending payment.	Ensure the payment is authorised (pending) before capturing.
208004	Not acceptable to request the capture for amount bigger than auth amount.	Capture amount exceeds authorised amount.	Capture only up to the authorised amount.
208005	Not acceptable to request the refund for payment not in settled or pending status.	Refund on an unsettled payment.	Wait for the payment to reach settled status before refunding.
208006	Not acceptable to request the refund for amount bigger than payment amount.	Refund amount exceeds original payment.	Refund only up to the original payment amount.
208007	Not acceptable to request the reversal for payment not in pending status.	Reversal on a non-pending payment.	Reverse only pending / authorised payments.
208008	Not acceptable to request the reversal for amount bigger than payment amount.	Reversal amount exceeds payment amount.	Reversal must not exceed the original amount.
208009	Not acceptable to request the reversal for partial amount.	Partial reversal not supported.	Reverse the full amount or use a refund for partial amounts.
208010	Not acceptable to request the chargeback for amount bigger than payment's amount.	Chargeback amount exceeds original payment.	Chargeback amount must be less than or equal to the original payment amount.
208011	Not acceptable to request the chargeback for date less than payment's create date.	Chargeback date is before payment creation date.	Verify the chargeback date is after the payment date.
208012	Not acceptable to request the refund for partial amount.	Partial refund not enabled for this merchant.	Contact support to enable partial refunds, or refund the full amount.
208013	Not acceptable to request the check for payment not in prepare status.	Check requested on a non-prepare payment.	Only check payments in prepare status.
208014	Not acceptable to request the void for payment not in settled status.	Void on an unsettled payment.	Only void settled payments; use reversal for pending ones.
208015	Not acceptable to request the void for payment with already partial refunds.	Void blocked by existing partial refunds.	A payment that has been partially refunded cannot be voided.
208016	Not acceptable to request the capture for partial amount.	Partial capture is not allowed for this payment.	Capture the full authorised amount.
208017	Not acceptable to request the retry for payment not in decline status.	RETRY sent for a payment that was not declined.	Retry only declined payments.
208018	Not acceptable to request the retry for payment without failed transactions.	The payment carries no failed transaction to retry.	Check the payment's transaction list before retrying.
208019	Not acceptable to request the retry for payment not recurring secondary.	RETRY is only for a subsequent recurring charge, not for an initial or one-off payment.	Retry a recurring follow-up payment; start a new payment otherwise.
208020	Invalid refund amount. Adjust the refund amount so that for the next refund, the remaining balance after the exchange is at least one cent.	On an exchanged payment, the requested refund would leave a remainder that converts to zero.	Refund the full remaining balance, or lower the amount so the remainder still converts to at least one minor unit.
208021	Not acceptable to request the exchange to crypto payment.	Currency exchange was requested on a crypto payment.	Send the payment without exchange, or use a fiat currency pair.
208022	Not acceptable to request the zero amount capture for payment with non zero amount auth.	CAPTURE with amount 0 against an authorisation whose amount is greater than 0.	Capture a non-zero amount, up to the authorised amount.
208023	Not acceptable to request the refund for payment with crypto exchange.	The payment was settled through a crypto exchange, which cannot be refunded.	Return the funds outside the platform; refund is not available for this payment.
208024	Chargeback transaction not found	A chargeback reversal was requested for a payment with no chargeback on it.	Confirm the chargeback exists before requesting the reversal.
208025	Not acceptable to request the chargeback reversal for amount bigger than chargeback's amount.	Reversal amount exceeds the chargeback amount.	Reverse at most the chargeback amount.
208026	Not acceptable to request the chargeback reversal for date less than chargeback's create date.	Reversal date is earlier than the chargeback date.	Use a reversal date on or after the chargeback date.
208027	Allowed only one chargeback reversal for payment	A chargeback reversal already exists for this payment.	Check the payment history; a second reversal is not possible.
208028	Allowed only one chargeback for payment	A chargeback already exists for this payment.	Check the payment history; a second chargeback is not possible.
209001	Affected payment not found.	Referenced original payment does not exist.	Verify the payment ID used in the operation.
209002	Affected transaction not found.	Referenced transaction ID does not exist.	Check the transaction ID and confirm it was created.
210001	Payment already in process.	Concurrent request for the same payment is running.	Wait for the first request to complete before retrying.
210002	Refund via API is not supported. Only from the connector admin portal.	Connector does not support API-based refunds.	Issue refunds through the connector admin portal.

220xxx: Test transactions

Error code	Error message	Possible reason	How to fix
220002	Use merchant test key.	Live merchant key used in the sandbox environment.	Use the merchant test key for sandbox transactions.

230xxx: Payment commission

Error code	Error message	Possible reason	How to fix
230001	Invalid commission settings: total amount less than zero.	Commission config produces a negative total.	Fix commission settings so fees do not exceed the transaction amount.

250xxx: Digital wallet tokens

Error code	Error message	Possible reason	How to fix
250001	Not found GooglePay private key for decrypt token.	No Google Pay private key is configured for this merchant, so the payment token cannot be decrypted.	Upload the Google Pay private key in admin before sending wallet payments.
250002	The payment token expiration time has been exceeded.	The Google Pay payment token had already expired when it reached the platform.	Generate a fresh token on the client and send the payment immediately.
250003	The payment token signature has expired.	The Apple Pay payment token signature had already expired when it reached the platform.	Generate a fresh token on the client and send the payment immediately.

260xxx: Transfer limits

Returned for card-to-card transfer operations.

Error code	Error message	Possible reason	How to fix
260001	Amount of transfer more than specified limit.	The transfer amount is above the configured per-transaction maximum.	Split the transfer, or ask support to raise the maximum.
260002	Amount of transfer less than specified limit.	The transfer amount is below the configured per-transaction minimum.	Increase the amount to the configured minimum.
260003	Cards not from the specified issuing country.	Neither card in the transfer is issued in a country the transfer settings allow.	Use cards issued in an allowed country, or update the transfer settings.

Gateway errors (HTTP 400)

Code	Message	When	Fix
400	Duplicate request.	An identical request was processed recently.	Generate a new order.number for a new payment intent.
400	Previous payment not completed.	A prior payment for this order.number is still in flight.	Wait for the previous payment to reach a terminal state, or void it.

info

Gateway errors apply only for S2S Protocols.

---

See also

• Changelog for the release where each new code was introduced.
• Errors and validation for the Checkout-specific narrative version (same codes, in-context).