Lemonway provides its Partners with a complete solution for processing card payments.
At Lemonway, we offer several card payment options; you can find them here.
Card payments work in four key steps:
- Once the basket is confirmed, your customer clicks the payment button on your website or application.
- A card transaction with the status Pending is created in your Dashboard (Type = Incoming / Method = Card / Status = Pending).
- The payment page opens, where your customer enters their card details (network, number, expiry date, and CVC) and completes the payment.
- The transaction is updated with card information (first four and last two digits, issuing country, etc.). Its status changes and Lemonway deducts its fee.
| Network | Card type | Geographic area | Accepted currencies |
|---|
| CB (Carte Bancaire) | Debit and Credit | France | EUR |
| Visa | Debit and Credit | International | EUR, GBP, CHF |
| Mastercard | Debit and Credit | International | EUR, GBP, CHF |
Activation of some networks may depend on your contract and geographic area. Contact your Account Manager to find out which networks are available in your configuration.
Pay In and Pay Out transactions are always processed in the currency of your Lemonway payment environment. Exchange rates are provided by the card-issuing bank. Other currencies may be activated on request, depending on your volumes.
Depending on your contractual configuration, the following features are available:
| Feature | Description |
|---|
| One-shot payment | Single transaction without saving the card |
| One-click payment | Payment using a saved (tokenised) card, initiated by the customer without re-entering their details |
| Card pre-authorisation | Holds an amount on the card (for a deposit or when the final amount is unknown) for up to 6 days |
| Recurring payments (MIT) | Merchant-initiated transactions, such as subscriptions, recurring debits and deferred billing |
| Delayed capture | The actual debit takes place after the authorisation phase |
| Partial or full refund | Refund to the original card, through the Dashboard or API |
One-click and MIT features use secure card tokenisation. Lemonway stores card details in accordance with PCI DSS standards and returns a unique identifier (card_id) during the first payment with card registration. This identifier is used for subsequent transactions, so the customer does not need to enter their details again.
Recurring payments (MIT) are subject to specific regulatory requirements, including initial consent and informing the cardholder. Make sure your integration meets these obligations before activation.
| Status | Description |
|---|
| Success | The transaction has completed, and the amount is credited to the beneficiary's payment account. |
| Pending | The amount has not yet been credited, but the status may change to Success or Error. |
| Cancelled | The amount has not been credited. The customer did not complete the payment (for example, they closed the browser, did not enter the 3DS code, or the session timed out). |
In the sandbox environment, use the card numbers below to simulate different payment behaviours. For all test cards, use:
- Expiry date: any future date (for example,
12/26).
- CVC: any three-digit code (for example,
123).
These test cards are valid only in the sandbox environment and when you are using Lemonway's new card structure. Using a test card in production results in an automatic decline (card.test).
For more information, contact your Account Manager or Lemonway Support.
| Card number | Network | Behaviour |
|---|
4242 4242 4242 4242 | Visa | Successful payment |
5555 5555 5555 4444 | Mastercard | Successful payment |
| Card number | Country | Network |
|---|
4977 8300 0000 0001 | France | Visa |
4360 0000 0100 0005 | France | Visa / Carte Bancaire (CB) |
5130 2900 0000 0009 | France | Mastercard / Carte Bancaire (CB) |
4658 5800 0000 0008 | United Kingdom | Visa |
4023 6000 0000 0002 | Italy | Visa |
4571 7300 0000 0003 | Denmark | Visa |
4338 3000 0000 0009 | Argentina | Visa |
4835 9100 0000 0003 | China | Visa |
| Card number | 3DS Behaviour |
|---|
4000 0000 0000 0101 | 3DS required and supported (challenge) |
4000 0000 0000 0119 | 3DS not supported by the card |
4000 0000 0000 3055 | 3DS v2 - frictionless flow (without fingerprint) |
4000 0000 0000 3063 | 3DS v2 - frictionless flow (with fingerprint) |
4000 0000 0000 3253 | 3DS v2 required for SCA; no authentication for MITs |
4000 0000 0000 0259 | 3DS v2 supported; v1 not supported |
4000 0000 0000 3238 | 3DS v2 not supported; v1 supported |
4000 0000 0000 3220 | 3DS v2 - fingerprint fails |
4000 0000 0000 3246 | 3DS v1 required, but v2 not supported |
| Card number | Simulated Behaviour |
|---|
4000 0000 0000 0002 | Card declined |
4000 0000 0000 0010 | Authorisation succeeds, but every capture fails |
4000 0000 0000 2180 | Declined -card.do-not-honor |
4000 0000 0000 2198 | Declined - card.possible-fraud |
4000 0000 0000 2206 | Declined - card.no-money (insufficient funds) |
4000 0000 0000 2214 | Declined -card.expired |
4000 0000 0000 2222 | Declined - card.stolen (card reported stolen) |
4000 0000 0000 2230 | Declined - card.failed-cvc (invalid CVC) |
4000 0000 0000 2248 | Declined - card.failed-avs |
4000 0000 0000 2255 | Declined - card.not-authorized |
4000 0000 0000 2263 | Declined - card.inactive |
4000 0000 0000 2271 | Declined - card.lost |
4000 0000 0000 2289 | Declined - card.region-not-authorized |
4127 9694 2058 7632 | Declined - card.blacklisted |
| Card number | Simulated Behaviour |
|---|
4000 0000 0000 0028 | CVC verification fails |
4000 0000 0000 1216 | Verification succeeds, but every transaction fails |
4000 0000 0000 0069 | Payment succeeds, but a chargeback is initiated immediately |
4000 0000 0000 0200 | Payment succeeds, but a failed chargeback is initiated immediately |
4000 0000 0000 0309 | Payment succeeds, but a retrieval request is initiated immediately |
4000 0000 0000 0077 | Payment succeeds, but every refund is declined |
4000 0000 0000 4004 | Payment succeeds, but a fraud notification is sent |
4000 0000 0000 6223 | Payment succeeds, but every incremental capture fails |
4000 0000 0000 0531 | Authorisation succeeds, but every incremental authorisation fails |
4000 0000 0000 3303 | Authorisation succeeds, but every incremental authorisation fails with card.no-money |
4000 0000 0000 6009 | Verification succeeds, but new authorisations fail with card.no-money |
4000 0000 0000 4301 | Verification succeeds, but new authorisations fail with card.expired |
5337 4800 0000 7168 | The transaction fails with recommendation code do-not-retry |
When a card transaction is declined, an error code is visible in the Lemonway Dashboard. The tables below help identify the reason for the decline and the recommended corrective action.
These codes are not returned in the API response and are visible only when using Lemonway's new card structure. For more information, contact your Account Manager or Lemonway Support.
| Error code | Description | Recommended Action |
|---|
gateway.possible-fraud | Transaction flagged as potential fraud | Contact Lemonway Support |
card.possible-fraud | Payment blocked by the issuer for potential fraud | Contact the issuer |
card.blacklisted | Card is blacklisted — do not retry | Do not retry |
card.stolen | Card reported stolen — do not retry | Do not retry |
card.lost | Card reported lost — do not retry | Do not retry |
card.security-violation | Security threat detected — do not retry | Do not retry |
card.high-risk | Transaction flagged as high risk | Review before retrying |
card.possible-counterfeit | Card may be counterfeit | Review the transaction before retrying |
routing-rules.transaction-blocked | Transaction blocked by Lemonway rules | Contact Lemonway Support |
| Error code | Description |
|---|
card.invalid | Invalid card (number, expiry date or CVC) |
card.invalid-number | Invalid card number |
card.invalid-expiry-date | Invalid expiry date |
card.missing-cvc | Required CVC is missing |
card.invalid-brand | Invalid or unsupported card network |
card.invalid-merchant | Invalid merchant — contact Lemonway Support |
card.invalid-name | Invalid cardholder name |
card.invalid-expiry-month | Invalid expiry month |
card.invalid-expiry-year | Invalid expiry year |
card.missing-expiry | Expiry date is missing |
card.missing-number | Card number is missing |
card.missing-name | Cardholder name is missing |
card.missing-pin | PIN is missing |
card.bad-track-data | Invalid track data (expiry date or CVC) |
card.invalid-account | Invalid bank account |
card.invalid-amount | Invalid transaction amount |
card.invalid-scheme | Invalid or unsupported card scheme |
card.invalid-transaction | Invalid transaction |
card.formatting-error | Formatting error |
card.not-found | Card information not found |
| Error code | Description | Recommended Action |
|---|
card.issuer-failed | The issuing bank encountered an error | Retry later |
card.acquirer-failed | Processing failed on the acquirer side | Contact Lemonway Support |
card.issuer-down | The issuing bank is unavailable | Retry later |
card.network-failed | Unable to contact the card network | Contact Lemonway Support |
card.issuer-maintenance | The issuing bank is undergoing maintenance | Retry later |
card.processing-error | Processing failed on the acquirer/issuer side | Contact Lemonway Support |
card.issuer-not-found | Issuing bank not found | Contact Lemonway Support |
card.acquirer-not-found | Acquirer not found | Contact Lemonway Support |
card.issuer-malfunction | Issuing bank malfunction | Retry later |
| Error code | Description | Recommended Action |
|---|
card.declined | Payment declined; no additional information available | Ask the customer to contact their bank |
card.do-not-honor | Generic decline by the issuing bank (default code) | Ask the customer to contact their bank |
card.please-retry | Payment declined — retry is possible | Retry the transaction |
card.dont-retry | Payment declined — do not retry | Do not retry |
payment.declined | Payment declined; no additional information available | Ask the customer to contact their bank |
card.no-action-taken | No action taken — retry the transaction | Retry the transaction |
gateway.declined | Transaction not processed for technical reasons. The card may belong to a network not supported by Lemonway, such as American Express (AMEX). | Ask the cardholder to use a card from a network supported by Lemonway |
| Error code | Description | Recommended Action |
|---|
gateway.blocked | Technical issue | Contact Lemonway Support |
gateway.configuration-error | Technical issue | Contact Lemonway Support |
gateway.invalid-credentials | Technical issue | Contact Lemonway Support |
gateway.invalid-merchant | Technical issue | Contact Lemonway Support |
gateway.forbidden | Technical issue | Contact Lemonway Support |
gateway.not-allowed | Technical issue | Contact Lemonway Support |
gateway.internal-error | Technical issue | Contact Lemonway Support |
gateway.maintenance | Technical issue | Contact Lemonway Support |
gateway.network-error | Technical issue | Contact Lemonway Support |
gateway.timeout | Technical issue | Contact Lemonway Support |
gateway.unknown-error | Technical issue | Contact Lemonway Support |
gateway.duplicate | Transaction is a duplicate or has already been processed | Check whether the transaction has already been processed |
gateway.expired | Gateway expired | Contact Lemonway Support |
gateway.limit-exceeded | Gateway limit exceeded | Contact Lemonway Support |
gateway.rate-limit-exceeded | Gateway rate limit exceeded | Contact Lemonway Support |
gateway.validation-error | Technical issue | Contact Lemonway Support |
gateway.not-found | Gateway not found | Contact Lemonway Support |
gateway.transaction-not-found | Transaction not found | Contact Lemonway Support |
gateway.transaction-pending | Transaction pending | Wait for the status to update |
gateway.unsupported-country-code | Unsupported country code | Contact Lemonway Support |
gateway.unsupported-currency | Currency not supported by the gateway | Contact Lemonway Support |
gateway.invalid-billing-address | Invalid billing address | Check the billing address |
gateway.invalid-state | Invalid transaction state | Contact Lemonway Support |
gateway.invalid-repeat | Invalid repeated transaction | Contact Lemonway Support |
gateway.retry | Transaction should be retried | Retry the transaction |
| Error code | Description | Recommended action |
|---|
card.expired | Card expired | Ask the customer for a new card |
card.not-activated | Card not yet activated | Ask the customer to activate the card |
card.inactive | Inactive card | Ask the customer to contact their bank |
card.restricted | Restricted card | Ask the customer to contact their bank |
card.revoked | Card revoked — do not retry | Do not retry |
card.revoked-all | All of the cardholder's cards have been revoked | Do not retry |
card.exceeded-limits | Card limit reached | Ask the customer to contact their bank |
card.exceeded-withdrawal-limit | Withdrawal limit reached | Ask the customer to contact their bank |
card.exceeded-activity-limits | Activity limit reached | Ask the customer to contact their bank |
card.exceeded-maximum-amount | Maximum amount exceeded | Split the transaction or ask for another payment method |
card.no-money | Insufficient funds | Ask the customer to top up their account |
card.no-credit-account | No associated credit account | Ask for another payment method |
card.no-savings-account | No associated savings account | Ask for another payment method |
| Error code | Description | Recommended action |
|---|
card.needs-authentication | 3DS authentication required | Contact Lemonway Support |
card.missing-3ds | Required 3DS verification is missing | Contact Lemonway Support |
card.unsupported-3ds | Card does not support 3DS, although it is required | Ask the cardholder to contact their bank or use another card |
card.failed-3ds | 3DS verification failed | Ask the customer to try again |
card.expired-3ds | 3DS verification expired | Ask the customer to try again |
card.couldnt-3ds | Unable to perform 3DS authentication | Contact Lemonway Support |
card.failed-3ds-technical | Technical failure during 3DS | Retry later |
card.unsupported-3ds2 | Card does not support 3DS2 | Ask the cardholder to contact their bank or use another card |
card.invalid-eci | Invalid e-commerce indicator (ECI) | Contact Lemonway Support |
card.eci-conflict | ECI conflict | Contact Lemonway Support |
card.invalid-pares | Invalid Payment Authentication Response (PARes) | Contact Lemonway Support |
| Error code | Description | Recommended action |
|---|
card.failed-cvc | CVC verification failed | Ask the customer to check their CVC |
| Error code | Description | Recommended action |
|---|
card.duplicate | High probability of a duplicate | Check whether the transaction has already been processed |
card.maximum-attempts | Maximum number of attempts reached | Ask the customer to contact their bank |
card.not-supported | Card not supported | Ask for another payment method |
card.already-blocked | Card already blocked | Ask the customer to contact their bank |
card.already-captured | Transaction already captured | Do not retry |
card.already-refused | Transaction already declined | Do not retry |
card.pending | Transaction pending | Wait for the status to update |
card.timeout | Transaction timed out | Retry the transaction |
card.transaction-not-processed | Transaction not processed | Contact Lemonway Support |
card.contact-acquirer | Contact the acquirer | Contact Lemonway Support |
card.contact-bank | Customer must contact their bank | Ask the customer to contact their bank |
card.canceled-by-client | Transaction cancelled by the customer | No action required |
card.approve-after-identification | Additional identification required | Ask the customer to contact their bank |
card.currency-unsupported | Currency not supported by this card | Check the transaction currency |
card.type-not-supported | Card type not supported | Ask the cardholder to contact their bank or use another card |
card.terminal-not-found | Terminal not found | Contact Lemonway Support |
card.terminal-not-initialized | Terminal not initialised | Contact Lemonway Support |
card.physical-authentication-error | Physical authentication error | Contact Lemonway Support |
card.no-cheque-account | No associated current account | Ask for another payment method |
card.invalid-bank-country-code | Invalid bank country code | Contact Lemonway Support |
| Error code | Description | Recommended action |
|---|
request.transaction-blocked | Blocked for compliance reasons. This may happen when the issuing bank previously declined a transaction made with this card and indicated that subsequent attempts should also be declined. | Do not retry. Ask the customer to contact their bank |
card.keep-card | Card must be retained — do not retry | Do not retry |
card.not-authorized | Card not authorised for this payment | Ask the customer for another payment method |
card.region-not-authorized | Not authorised in this geographic region | Contact Lemonway Support |
card.authorization-revoked | Transaction authorisation revoked | Do not retry |
card.law-violation | Transaction violates legal provisions | Do not retry |
card.holder-not-authorized | Cardholder not authorised | Ask the customer to contact their bank |
card.not-registered | Card not yet registered | Ask the customer to register the card |
card.terminal-not-allowed | Card not authorised on this terminal | Contact Lemonway Support |
card.surcharge-not-allowed | Surcharge not allowed | Contact Lemonway Support |
card.surcharge-not-supported | Surcharge not supported by the card | Contact Lemonway Support |
card.exemption-declined | Exemption declined | Contact Lemonway Support |
card.reauthorization-not-allowed | Re-authorisation not allowed | Do not retry |
card.test | Test card used in production | Use a real card in production |
For any error code not listed here, or if further investigation is required, contact Lemonway Support and provide the transaction ID and error code.
