Overview
This guide is designed for Level 1 (L1) support agents handling payment issues related to the FreedomPay integration in the Lunchbox platform. It covers the most common error codes, their plain-language meaning, recommended troubleshooting steps, and when to escalate to FreedomPay or internal engineering.
Support and Escallataion
Before the breakdown of the most common errors, we wanted to list at the very begining the two escallation channels.
Level 1: Lunchbox Internal Support (First point-of- contact)
All payment-related issues should be directed to Lunchbox Support as the first point of contact. Restaurant partners and their operators should reach the Lunchbox support team via email at [email protected] or through the live chat widget embedded directly in the Lunchbox Admin Dashboard.
The in-dashboard chatbot (accessible via the help icon in the bottom corner of the Admin dashboard) provides immediate assistance and can route urgent issues to a live support agent. The Lunchbox support team will triage the issue, gather relevant context, and attempt to resolve it before escalating further. |  |
Level 2: FreedomPay Technical Support (Escalation)
If an issue cannot be resolved at the Lunchbox support level and requires escalation to FreedomPay, the following details must be collected prior to escalation: StoreID, TerminalID, RequestID, and MerchantReferenceCode (along with any other relevant transaction details).
FreedomPay Technical Support can be reached through the following channels:
Phone: 888.495.2446 (US) / +44-2030148966 (UK)
Email: [email protected]
System Status: https://status.freedompay.com/
Online payments workflow
When a customer places an online order, their payment travels through multiple systems in a matter of milliseconds. Understanding this flow helps L1 agents quickly identify where a failure may have occurred
Customer submits payment details in the Lunchbox checkout
FreedomPay receives the request and runs initial validation and fraud checks
FreedomPay routes the request to the acquiring bank (merchant acquirer)
The acquiring bank forwards payment info to the card network (Visa, Mastercard, Amex, etc.)
The card network routes the request to the customer's issuing bank for approval
The issuing bank approves or declines and sends a response back through the chain
FreedomPay returns an error code to Lunchbox
code 100 = Approved;
anything else = Review required
Types of Payment Failures
Payment failures fall into four broad categories. Identifying the category quickly helps narrow down the cause.
Failure Type
| What It Means
| Common Examples
|
Customer-side error
| The customer provided incorrect or invalid information.
| Wrong card number, expired card, incorrect CVV, wrong OTP, insufficient funds
|
Merchant-side error
| A technology, configuration, or security issue on the Lunchbox/FreedomPay side.
| Invalid merchant credentials, card type not enabled, misconfigured payment processor
|
Data transfer error (ghost charge)
| The customer's card is charged but they receive a failure message. Payment went through on the bank side but failed to confirm back.
| Timeout mid-transaction, network interruption during response
|
True failure (not charged)
| The payment failed end-to-end and the customer's account was not debited.
| Bank declined, fraud block, card blocked
|
IMPORTANT NOTE: If a customer reports they were charged but the order did not go through, do NOT ask them to retry immediately. Check the order's event logs first to confirm whether a charge exists before advising on next steps.
Common Payment Issues & Troubleshooting Steps
The following are the most frequent payment failure scenarios reported by customers. Each scenario includes the FreedomPay error codes that indicate it, so your team can match what they see in logs to the right response.
When a payment fails, locate the errorCode in the transaction log or alert. Find the matching code in the 'FreedomPay Error Codes' callout for each scenario below, then follow the steps.
Here you can find a complete error code guide: https://t9010016731.p.clickup-attachments.com/t9010016731/066f4908-8319-44b1-976a-3d7659740af9/FreedomPay_Error_Codes_Guide-v7.0.pdf?view=open
Insufficient Funds
The customer's account does not have enough balance to cover the transaction. Some issuers return this code for over-limit credit cards as well.
Freedom Pay Error Codes:
204 - Insufficient funds
210 - Card over limit
204 - return for over-limit credit cards
Steps:
Ask the customer to check their account balance via their bank app or statement
If they believe funds are available, advise them to call their bank. Some holds or pending transactions may reduce the available balance without being visible
Suggest an alternative payment method if available
Do not retry more than once. Repeated attempts won't resolve a funds issue
Here's what the customer experience looks like when the card is declined after error 204 (Insufficient funds)
Invalid Card Number
The card number entered does not pass validation. This is usually a data entry error.
Freedom Pay Error Codes:
102 - One or more fields contain invalid data
106 - Invalid name on card field. These codes appear when card data fails format or validation checks
231 - Invalid account number
Steps:
Ask the customer to refresh the page and carefully re-enter their full card number
Confirm they are entering all 15 or 16 digits without spaces or dashes (even though for the card number, only the number input can be accepted)
Check that the cardholder name field matches the name on the card exactly
If the issue persists after re-entry, advise them to contact their card issuer to confirm the card is in good standing
Here's what the customer sees on the ordering platform when the card is declined after error 231 (Invalid account number )
Invalid or Expired Card
The expiration date entered does not match the card's actual expiry, or the card has expired or is inactive.
Freedom Pay Error Codes:
202 - Expired card (or mismatched expiry date); returned both for truly expired cards and for expiry dates that don't match what the issuer has on file
208 - Card not active or not eligible for this transaction type
248 - Authorization no longer valid
Steps:
Ask the customer to refresh and re-enter the expiry date carefully in MM/YY format.
If the card has expired, advise them to use a replacement or updated card.
If the card appears valid but still fails, the card may be inactive. Advise them to call their bank to confirm the card is active.
Invalid CVV / Card Security Code
The CVV (Visa/Mastercard), CVC, or CID (Amex) entered is incorrect.
Freedom Pay Error Codes:
211 - Incorrect card verification number (CVC)
287 - AVS/CVN validation code not whitelisted
Steps:
Ask the customer to locate the 3-digit security code on the back of their card (or the 4-digit code on the front for Amex).
Make sure they are not entering their CVV ( ensure they know the CVV and PIN are different types of codes).
Ask them to re-enter carefully. If repeated attempts fail, advise them to contact their bank
Here's what the customer sees on the ordering platform when the card is declined after error 287 (AVS/CVN validation code not whitelisted)
Card Declined by Bank (Unspecified)
The issuing bank declined the transaction without providing a specific reason. This can happen due to risk flags, account restrictions, or security policies.
Freedom Pay Error Codes:
201 - Call issuing bank for authorization (bank is specifically requesting the customer call in)
203 - Declined by issuing bank (unspecified, most common general decline)
220 - Generic account problem
233 - Processor rejected due to a request issue
254 - Process rejected, invalid data Code
Steps:
Advise the customer to try a different payment method
If they want to use the same card, ask them to call the phone number on the back of their card. For code 201 specifically, the bank is requiring a call before authorizing
Do not retry the same card repeatedly; multiple failed attempts can trigger additional fraud flags at the bank
Here's what the customer sees on the ordering platform when the card is declined after error 201 (Call issuing bank for authorization (bank is specifically requesting the customer call in)
And here's what the customer sees on the ordering platform when the card is declined after error 203 ( Declined by issuing bank (unspecified, most common general decline))
Suspected Fraud / Fraud Block
The transaction was flagged as potentially fraudulent by the card issuer or fraud detection system (e.g., SIFT).
Freedom Pay Error Codes:
205 - Lost Card
206 - Stolen Card
221 - Suspected Fraud
288 - Rejected due to fraud checking
Steps:
Do not retry the transaction.
For codes 205 or 206 (lost/stolen card): Advise the customer to contact their bank immediately (this one is tricky. Customer's card has been flagged as lost or stolen, and Lunchbox's internal system can not fully verify the customer's identity)
For codes 221 or 288: Advise the customer to contact their bank to clear any fraud holds before attempting again.
Collect transaction details (time, amount, errorCode, RequestID) for escalation if needed.
Here's what the customer experience looks like when the card is declined after error 288 (rejected due to fraud checking)
Debit Block / Card Not Enabled for Online Use
Some banks place restrictions on cards, blocking online or card-not-present transactions by default.
Freedom Pay Error Codes:
208 - Card not active or not eligible for this transaction type
213 - Card not valid at this location
253 - Merchant not allowed to perform this transaction. These codes often appear when a card has restrictions on card-not-present (online) transactions.
Steps:
Ask the customer if their card is enabled for online purchases (some debit cards are restricted by default).
Advise them to call their issuing bank to enable online or card-not-present transactions.
Suggest using a different card in the meantime
Authentication Required (3DS / SCA)
The transaction requires additional authentication (3D Secure / Strong Customer Authentication). This is common for online transactions in regions with SCA requirements, or for contactless transactions above a threshold.
Freedom Pay Error Codes:
217 - Additional authentication required / soft-decline.
Steps:
For online orders: The customer should watch for a bank authentication prompt (SMS one-time code, app push notification, or redirect to bank page) and complete it.
If the issue does not resolve, escalate to the engineers.
System / Processing Errors (Retry or Escalate)
These errors are not caused by the customer's card but by system-level issues between FreedomPay, the processor, or the network.
Freedom Pay Error Codes
149 - Unknown error (DO NOT retry, escalate)
150 - Fatal application error (DO NOT retry, escalate)
151 - Internal timeout (retry)
152 - Processor communication error (escalate)
153 - Unable to communicate with card processor (retry)
155/ 162 - Internal communication failure (retry)
156 - System busy / TOR deadline (wait, then retry)
Steps:
For codes 151, 153, 155, 162: Wait a few seconds and retry the transaction once
For code 156: The system is under load. Wait at least 1-2 minutes before retrying
For codes 149, 150, or 152: Do NOT retry. These are fatal or unknown errors. Immediately collect the RequestID and errorCode and escalate to FreedomPay.
If retryable errors persist beyond 2-3 attempts, escalate to internal support and then Freedom Pay if needed.
Here's what the customer experience looks like when the card is declined after error 150 (Fatal application error (DO NOT retry, escalate))
Here's what the customer experience looks like when the card is declined after error 152 (Processor communication error (escalate))
