Errors

Error response shape

{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251
}
Field Meaning
status_code 0 success, 1 error.
status_error_code PayMe's numeric error code. 0 on success.
status_error_details The error message, in the language you asked for.
status_additional_info Extra detail — usually the name of the field at fault. Alternatives are joined with /, for example seller_payme_id / seller_id.
payme_status success or error (on some responses and on the return-URL redirect).

Error bodies also include a session field.

HTTP status vs status_error_code

The two numbers are separate: status_error_code is never used as the HTTP status.

Situation HTTP status
Card declined (codes 20xxx / 21xxx) 200, with status_code: 1
Most request errors — for example missing parameter (1), unknown client key (200), unknown seller (251), wrong sale status (305) 500
Some access and input errors 400, 403 or 422
Too many requests, or a duplicate call still running (998) 429
Service temporarily read-only 503

Decide what happened from status_code and status_error_code, not from the HTTP status. A 200 can be a decline. A 500 with status_code: 1 and an error code is a refusal: your request usually needs fixing, and it doesn't mean PayMe is down.

In a few cases the outcome is unknown, and PayMe may have acted. Check the sale before repeating a call that moves money (how):

Getting messages in English

If you omit language, messages come back in Hebrew. Send "language": "en" on every call. he and en are fully supported; es, ru and ar are accepted, but messages and the payment page are then mostly in English. Values are case-insensitive. Any other value, or an empty string, returns error 51.

A few very early errors, such as a malformed key format, may still come back in Hebrew.

Common error codes

The tables below cover the codes integrators meet most often.

Request and credential errors

Code Meaning What to do
1 Required parameter is missing. status_additional_info names it. Also returned when no client key and no seller key are sent. Add the named field.
10 installments or market_fee is not numeric Send a number such as 1 or "1".
19 Please provide all required fields (some endpoints) Check the endpoint's required fields.
20 Validation error. Also "Merchant-Seller inconsistency" (HTTP 400): the seller belongs to a different partner from the payme_client_key sent. Also "<field> contains invalid data" (HTTP 400): on generate-sale, pay-sale, capture-buyer-token, POST /sales, pay-subscription and PATCH /subscriptions/{id}, a field other than the card fields, transaction_id and order_number contains a 14–19-digit number that passes the card checksum. Fix the fields listed in status_additional_info. Never put card-like numbers in descriptive fields.
51 Unsupported or empty language value Use he or en (es, ru and ar are accepted but mostly shown in English).
163 "Account settings problem - please contact Customer Support": the MPL exists but is inactive, or a test MPL was sent to production Check that seller_payme_id and the base URL are from the same environment; if they are, contact PayMe.
200 Merchant was not found (HTTP 500): the payme_client_key (or PayMe-Partner-Key) matches no partner, usually because a seller sent its own MPL there or a production key was sent to the sandbox. status_additional_info is payme_client_key. A seller removes the field and authenticates with seller_payme_id alone; a partner checks the key and the environment.
201 The partner is inactive Contact PayMe.
251 Seller was not found: the seller_payme_id / seller_id matches no seller. Also returned for an unknown public key during card tokenization. Check the MPL or public key and the environment.
252 Currency not allowed for this account Use a currency enabled on the account.
312 More than 1 installment in a non-ILS currency Installments are available for ILS sales only.
351 installments outside the accepted ranges, or more than one installment with a payment method other than credit-card, multi or pos Send 1–12, or 102–112 to let the buyer choose. Installments are for card payments only.
358 ILS price lower than the number of installments Raise the price or lower the installments.
352 sale_price is missing, not numeric or outside the allowed range. On capture-sale, also 0 or more than the authorization allows Send minor units within the allowed range.
353 product_name is missing Add product_name.
357 Invalid sale type: sale_type is not one of sale, authorize, token, seller-token, credit, template, multi-capture, or it can't be combined with the request (for example multi-capture with buyer_key). status_additional_info holds the value sent. Send a listed value. For recurring payments, create a subscription with generate-subscription (see Recurring Payments).
24 Unknown sale_payment_method value Use a value from Available Payment Methods.
320 The currency isn't supported for this payment method: BACS needs GBP, SEPA needs EUR, and an Israeli direct debit charge needs ILS Send the method's currency.
368 sale_payment_method was sent as an array (HTTP 400) Send one value, as a string.
601 / 602 / 606 buyer_key combined with capture_buyer (601), a token or seller-token sale type (602), or template (606) Charge a saved token with sale_type sale or authorize.
608 buyer_perform_validation: true without capture_buyer or a token sale Send it only when you capture a token.

Sale-state, retry and rate-limit errors

Code Meaning What to do
305 Cannot perform action due to an incorrect status. status_additional_info holds the sale's current status. Returned, for example, when a paid sale is paid again or a fully refunded sale is refunded again. Check the sale with get-sales; do not retry.
517 The refund amount is bigger than the sale's price Refund no more than the sale's price, less what you already refunded.
991 A network problem, part-way through The outcome is unknown. Check the sale, and quote session to PayMe.
20002 A network problem reaching the card company The outcome is unknown. Check the sale, and quote session to PayMe.
999 No information provided The outcome is unknown. Check the sale, and quote session to PayMe.
998 HTTP 429. Either "Too Many Attempts." (rate limit) or "Duplicated action detected, please retry later" (the same action on the same sale is still running). Tell them apart by status_additional_info; status_error_details is "Operation is not permitted" in both. Wait (Retry-After header) and check the sale before retrying.

Codes PayMe support sees most often

The cases below come from PayMe's support knowledge base; the fix is what support will ask you to check first.

Code or message Usual cause What to do
251 / ERR-020 "seller not found" Wrong MPL, or a test key sent to the production URL (or the reverse) Copy the MPL from the dashboard (Admin → API & Integration) and check that key and base URL belong to the same environment.
130 "Seller is over sale limit, unable to create new sales" This sale would take the seller over its processing limit Complete any pending verification in the dashboard, then ask partners@payme.io to review the seller's processing limit (send seller_payme_id).
720 service not activated Apple Pay, Google Pay, Bit, B2B transfers or another value-added service is not enabled on the account A seller installs Apple Pay, Google Pay or Bit itself from the dashboard app store (חנות אפליקציות); the method is active as soon as it is installed. A partner enables it for its seller with vas-enable. For B2B transfers and other services, ask partners@payme.io (give your MPL).
603 from get-buyer-key You sent seller_payme_id to read an account-level token (one captured without buyer_is_private). Only get-buyer-key returns 603; charging an account-level token works for any seller of the same partner Call get-buyer-key with payme_client_key instead, or capture new tokens with "buyer_is_private": true. A sandbox token works only on the sandbox, with sandbox credentials.
357 "Invalid sale type: recurring" recurring isn't a sale type Recurring payments are subscriptions: create one with generate-subscription (see Recurring Payments).
401 / 403 Invalid credentials Check the key against the environment it belongs to. There is no self-service key regeneration; a correct key that is still refused points at the account — contact PayMe.
Garbled Hebrew or ? characters in responses Request not sent as UTF-8, or fields containing Hebrew quotation marks (for example בע"מ) Send UTF-8; test with an ASCII-only value to isolate the field.
"Merchant not allowed to use this buyer" The token was captured at account level, not for this seller Re-capture the card with "buyer_is_private": true on the capturing call (generate-sale with capture_buyer, or capture-buyer-token).
Callbacks not arriving URL, firewall, slow reply or signature problems Send sale_callback_url on every generate-sale (and sub_callback_url on generate-subscription); there is no dashboard callback setting for a seller; make the endpoint publicly reachable (no VPN or firewall); reply 200 within the timeout; verify the signature as described on Callbacks.

Card declines

Declines return HTTP 200 with status_code: 1. Codes 21xxx are card problems; 20xxx are refusals from the card company or gateway.

Code Message
20004 Refusal by credit company. Please try a different card
21001 The card is blocked
21002 The card is stolen
21004 The card is expired
21005 Incorrect card number
21006 The credit limit has been reached
21007 CVV/ID is required but was not entered
21008 Incorrect CVV or ID
21017 3D Secure authentication failed. The buyer didn't complete the challenge, or the issuer rejected it

The sandbox test cards that produce each one are on Test Cards and Payment Methods.

Bit

Bit requests end with their own codes. They are per-transaction outcomes, not account problems.

Code Meaning What to do
23001 The buyer rejected the Bit request Let the buyer retry or choose another method.
23002 The Bit request was canceled Retry.
23003 The Bit request expired before the buyer approved it Retry, and ask the buyer to approve it in the Bit app straight away.

Setup, seller and saved-card errors

Code Meaning What to do
21 A callback or return URL was refused, often a local address. The whole call fails Leave the field out when the address is local, or use a public one.
25 Phone number refused Send seller_phone in international format, such as +972501234567.
42 A value that must be whole has decimals, for example sale_price on capture-sale Send integer minor units.
114 Business type doesn't fit the seller's details Read the message. For sole proprietors, seller_inc_code must equal seller_social_id.
116 seller_birthdate is unreadable, or the person is under 16 Send dd/mm/yyyy.
118 seller_social_id_issued is unreadable or in the future Send dd/mm/yyyy.
121 seller_inc_code isn't numeric Send digits only.
174 Not supported for this seller type, usually a partner's own MPL used on generate-sale Use the seller's MPL.
303 "Could not access sale": the sale isn't this seller's or this partner's Check seller_payme_id, payme_client_key and the sale ID.
304 market_fee is negative (a non-numeric market_fee returns 10) Send a number from 0 to 60.
308 The fee is above 60% Keep it at 60% or below.
367 The sale has expired, after its sale_expiry_seconds Create a new sale.
420 No connected terminal accepts this payment If every card fails, no terminal is connected: ask PayMe. If only some payments fail, the account's terminals don't accept something in this one: the currency, the card brand, a foreign card, the amount, the number of installments, or the account's processing limit. Fewer installments or a currency the account allows can fix it; otherwise quote session to PayMe.
604 The saved-card token is inactive, often a single-use token charged again Capture the card again.
605 The token doesn't belong to this seller Charge it on a seller that can use it.
790 The plan requires or refuses the field named in status_additional_info, often seller_id Add or remove that field.
907 The seller is on an automatic withdrawal plan, so manual withdrawals aren't allowed PayMe pays out on the plan's schedule.

Answers for common errors

These codes each have a page with causes and fixes: 10, 21, 25, 42, 109, 114, 116, 118, 121, 130, 163, 174, 200, 201, 251, 252, 304, 305, 308, 352, 420, 516, 604, 605, 790, 998. Troubleshooting by Symptom helps when the code doesn't explain it. The address is predictable: /agents/errors/error- followed by the code.

Other codes

Other codes shown on endpoint pages: 356 invalid credit-card expiry (3D Secure initialize, capture-buyer-token); 600 buyer not found (get-buyer-key); 720 the service was not activated on the account, with the service name in status_additional_info (Apple Pay, Google Pay, B2B transfer); 901 invalid JSON (get-transactions); 906 withdrawal not found (credit-match).

Codes seen in real integrations (from PayMe support)

Code Meaning What to do
4 "Not implemented" (HTTP 500) on POST /sales: no payment block, or sale_type: credit on a non-card method Send a payment block; use credit only with cards.
109 Seller not validated or approved Complete the account verification.
516 Capture more than 7 days after the authorization The authorization can no longer be captured; it is not voided by this error. Release it with refund-sale, otherwise the card issuer releases it on its own schedule.
518 "Cannot find authorization transaction": the authorization is no longer open (already captured, voided or failed). A capture with sale_price: 0 returns 352, not 518 Check the sale with get-sales. A capture isn't a way to release a hold; use refund-sale on the authorized sale.
752 "Invoice document generation failed": the invoicing provider rejected the document, usually its credentials Check the invoicing service settings on the account.
20001 The acquirer declined a forwarded void or refund Contact PayMe with payme_sale_id and the time.

Israeli direct debit

When a bank authorization changes, the sale-il-direct-debit-update callback carries authorization_status and authorization_error_code.

authorization_status Meaning Effect
1 Success Authorization active
2 Failed Failed
3 Canceled Canceled
4 Unknown Failed
5 Moved from previous account Failed
6 Account changed Failed
13 Frozen authorization reactivated Authorization active
14 Sent to the bank Pending
15 Sent to the bank again Pending
16 Details missing Failed
17 Details incorrect Failed
18 Already processed (success) Authorization active

authorization_error_code is passed through unchanged from the bank side. Statuses 14 and 15 keep the authorization pending and normally send no callback.

Other APIs

Error formats of the other APIs are documented with them: B2B payment contracts, Keep, Products & Customers.

Not errors, but often needed when handling them: Sale Statuses, Transaction Statuses, Subscription Statuses.