--- title: "Checkout Errors" source_url: https://docs.rapyd.net/en/checkout-errors.html lang: en --- # Checkout Errors The following error codes and messages appear in REST responses when an error prevents completion of the request. | Checkout Errors | | --- | | **Error code:** ERROR_ACCOUNT_FUNDING_TRANSACTION **Message:** The request tried to create an account funding transaction, but your organization is not configured for such transactions. The request was rejected. Corrective action: Contact Rapyd Client Support. **Explanation:** You attempted to process a transaction that moves money into a wallet (AFT), but this feature is not enabled for your account. Please contact Rapyd support to activate AFT capabilities. | | **Error code:** ERROR_CHECKOUT_AFT_MISSING_FIELDS_[] **Message:** The request tried to create a checkout page with a customer to customer AFT payment workflow, but one or more required fields were missing. The missing fields are listed at the end of the error code. The request was rejected. Corrective action: Rerun the request with all the required fields. **Explanation:** When creating an account funding checkout, specific fields required for the transfer are missing. Verify that you have provided all mandatory parameters for the AFT workflow. **Error Example:** `{"aft":true,"payment_method_type":"sg_grabpay_wallet"}` without required ewallet information. **Correct Example:** ```json post /v1/checkout { "amount": 100, "currency": "SGD", "aft": true, "ewallets": [ { "ewallet": "ewallet_12345abcd", "percentage": 100 } ] } ``` | | **Error code:** ERROR_CHECKOUT_AFT_WITH_MULTIPLE_WALLETS **Message:** The request tried to create a checkout page with `aft` set to **true**, but the request included more than one wallet. The request was rejected. Corrective action: Set `ewallets` to an array of one `ewallet` object. **Explanation:** Account Funding Transactions (AFT) only support a single destination wallet. You must remove additional wallets from the `ewallets` array. **Error Example:** `{"aft":true,"ewallets":[{"ewallet":"ewallet_12345aaaabbb"},{"ewallet":"ewallet_22222aaaabbb"}]}` **Correct Example:** ```json { "aft": true, "ewallets": [ { "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861", "percentage": 100 } ] } ``` | | **Error code:** ERROR_CHECKOUT_AFT_WITHOUT_PURPOSE_CODE **Message:** The request tried to create a checkout page with a customer to customer AFT payment workflow, but the request did not include the `purpose_code` parameter. The request was rejected. Corrective action: Rerun the request with a `purpose_code` parameter that includes a valid value. **Explanation:** An Account Funding Transaction (AFT) was initiated without specifying why the funds are being transferred. Include the required purpose code in the checkout request. **Error Example:** `post /v1/checkout {"account_funding_transaction":{"payment_method_types":["sg_grabpay_ewallet"]}}` **Correct Example:** ```json post /v1/checkout { "account_funding_transaction": { "payment_method_types": [ "sg_grabpay_ewallet" ], "purpose_code": "gifts" } } ``` | | **Error code:** ERROR_CHECKOUT_COUNTRY_CURRENCY_MISMATCH **Message:** The request tried to create a checkout page, but there is no payment method that is supported in the `country` for the `currency` provided. The request was rejected. Corrective action: Use a different currency or country. **Explanation:** The combination of the `country` and `currency` provided does not have any active payment methods available. Use 'List Payment Methods by Country' to find valid pairings. **Error Example:** `{"country":"US","currency":"SGD"}` **Correct Example:** ```json { "country": "SG", "currency": "SGD" } ``` | | **Error code:** ERROR_CHECKOUT_CURRENCY_COUNTRY_MISMATCH **Message:** The request tried to create a checkout page, but there is no payment method that is supported in the `country` for the `currency` provided. The request was rejected. Corrective action: Use a different currency or country. **Explanation:** No payment methods are available that support both the selected `currency` and `country`. Change one of these values to a supported combination. | | **Error code:** ERROR_CHECKOUT_CUSTOMER_MISSING_FOR_RECURRING_OR_INSTALLMENT_RECURRENCE_TYPE **Message:** The request tried to create a checkout page without a `customer` field while `recurrence_type` was set to **installment** or **recurring**. The request was rejected. Corrective action: Add a `customer` field to the request and rerun it. **Explanation:** To process installments or recurring payments, a customer object must exist to store the payment method. Provide a valid `customer` ID. **Error Example:** `{"amount":10,"recurrence_type":"recurring"}` **Correct Example:** ```json { "customer": "cus_4e25112ac20e144ad073a614dc46934b", "recurrence_type": "recurring" } ``` | | **Error code:** ERROR_CHECKOUT_PAGE_DELAYED_CAPTURE_NO_REMAINING_SUPPORTING_CARDS **Message:** The request tried to generate a checkout page for a card payment method with delayed capture, but the request filtered the list of payment methods and none of the remaining payment methods support delayed capture. The request was rejected. Corrective action: Set `capture` to **null**, or set `payment_method_type`, `payment_method_type_categories`, `payment_method_types_exclude` and `payment_method_types_include` such that one or more remaining payment method types are cards that support delayed capture. **Explanation:** You requested a "hold" transaction (`capture` is **false**), but your filters excluded all cards that support this feature. Expand your inclusion list or allow all cards. | | **Error code:** ERROR_CHECKOUT_PAGE_DELAYED_CAPTURE_NO_SUPPORTING_CARDS **Message:** The request tried to generate a checkout page for a card payment method with delayed capture, but there are no card payment methods in the country that support delayed capture. The request was rejected. Corrective action: Set `capture` to **null**. **Explanation:** The selected country does not support delayed capture for any available cards. You must use immediate capture for this transaction. **Error Example:** `{"country":"IS","capture":false}` **Correct Example:** ```json { "country": "IS", "capture": true } ``` | | **Error code:** ERROR_CHECKOUT_PAGE_PAYMENT_METHOD_TYPE_CATEGORIES_VALUE_NOT_VALID **Message:** The request tried to create a checkout page, but one or more of the values in `payment_method_type_categories` was set to **null**, an empty string or an unrecognized value. The request was rejected. Corrective action: Provide an array of strings that contain only the following values: **bank_redirect**, **bank_transfer**, **card**, **cash**, **ewallet**. **Explanation:** You provided an invalid category for filtering payment methods. Only the listed categories (card, cash, etc.) are allowed. | | **Error code:** ERROR_CHECKOUT_PAGE_REQUIRED_CUSTOMER_FIELDS_NOT_VALID **Message:** The request tried to create a checkout page, but one or more of the values in `required_customer_fields` is not valid. The request was rejected. Corrective action: Provide an array of strings that contain only the following valid values: **name**, **email**, **phone_number**, **address**. **Explanation:** You requested a customer field that Rapyd does not collect through the checkout page. Limit your `required_customer_fields` array to the supported values. | | **Error code:** ERROR_CHECKOUT_PAYMENT_METHOD_CATEGORY_CURRENCY_MISMATCH **Message:** The request tried to create a checkout page, but one of the payment method categories provided did not contain any payment methods that are supported in the `country` for the `currency` provided. The request was rejected. Corrective action: Remove the payment method category from the list. **Explanation:** A specific category (e.g., **cash**) was requested, but no methods in that category support the provided currency in that country. Remove the empty category from your filter. **Error Example:** `{"payment_method_type_categories":["card","cash"]}` **Correct Example:** ```json { "payment_method_type_categories": [ "card" ] } ``` | | **Error code:** ERROR_CHECKOUT_PAYMENT_METHOD_CURRENCY_MISMATCH **Message:** The request tried to create a checkout page, but the payment method was not recognized. The request was rejected. Corrective action: Specify a payment method that is valid for the country. Use 'List Payment Methods by Country'. **Explanation:** The specific `payment_method_type` you included cannot process the `currency` you provided. Check the documentation for currency support per method. **Error Example:** `{"payment_method_types_include":["bg_mastercard_card","bg_amex_card"]}` **Correct Example:** ```json { "payment_method_types_include": [ "bg_mastercard_card" ] } ``` | | **Error code:** ERROR_CREATE_CHECKOUT_AMOUNT_OUT_OF_RANGE **Message:** The request tried to create a checkout page, but the `amount` was out of range for all payment methods available to you in the country, or for all payment methods that you specified. The request was rejected. Corrective action: For `amount`, specify an amount that is between the minimum and the maximum for at least one payment method. **Explanation:** The transaction `amount` is either too small or too large for the available payment methods. Adjust the amount to fall within the `min_amount` and `max_amount` limits. Alternatively, expand the list of payment method types so that it includes a payment method type that supports the amount you want. **Error Example:** `{"amount":0.01,"currency":"USD"}` **Correct Example:** ```json { "amount": 100, "currency": "USD" } ``` | | **Error code:** ERROR_HOSTED_PAGE_AMOUNT_MISMATCH **Message:** The request tried to create a checkout page with a `cart_items` object, but the value of the `amount` parameter does not match the total amount of all items in the `cart_items` object. The request was rejected. Corrective action: Specify the `amount` parameter for each item in the cart, and omit it from the root of the request. **Explanation:** The sum of items in your `cart_items` array does not equal the top-level `amount`. Correct the calculation or omit `amount` from the root. **Error Example:** `{"amount":100,"cart_items":[{"amount":60},{"amount":30}]}` **Correct Example:** ```json { "currency": "USD", "cart_items": [ { "name": "Item 1", "amount": 60, "quantity": 1 }, { "name": "Item 2", "amount": 30, "quantity": 1 } ] } ``` | | **Error code:** ERROR_HOSTED_PAGE_CONFLICTING_PAYMENT_METHOD_TYPES **Message:** The request tried to create a checkout page, but the request specified multiple ways of determining available payment methods. The request was rejected. Corrective action: Specify a `payment_method_type`, a list of types in `payment_method_types_include`, a list of types in `payment_method_types_exclude` or a list of categories in `payment_method_type_categories`, or leave all of these parameters blank. **Explanation:** You mixed different filtering methods (e.g., trying to include specific IDs while also filtering by category). Use only one method for defining the payment options list. **Error Example:** `{"payment_method_types_include":["bg_mastercard_card","bg_visa_card"],"payment_method_types_exclude":["sg_grabpay_ewallet"]}` **Correct Example:** ```json { "payment_method_types_include": [ "bg_mastercard_card", "bg_visa_card" ] } ``` | | **Error code:** ERROR_HOSTED_PAGE_FX_FEE_VALUE_NOT_VALID **Message:** The request tried to create a payment, but the amount of the FX fee was incorrect. The request was rejected. Corrective action: In the `fx_fee` object, set `value` to a decimal number greater than 0 and less than 100. **Explanation:** The `fx_fee` value is invalid. Fees must be positive and cannot exceed the total transaction amount. Typically, this is a small percentage like **2.5**. **Error Example:** `{"payment_fees":{"transaction_fee":{"calc_type":"gross","fee_type":"percentage","value":-5}}}` **Correct Example:** ```json { "payment_fees": { "transaction_fee": { "calc_type": "gross", "fee_type": "percentage", "value": 5 } } } ``` | | **Error code:** ERROR_HOSTED_PAGE_GET_CUSTOMER **Message:** The request tried to create a checkout page, but the customer was not found. The request was rejected. Corrective action: For `customer`, provide a valid customer ID, a string starting with **cus_**. **Explanation:** The `customer` ID provided does not exist in the system. Verify the ID or create a new customer first. **Error Example:** `{"customer":"cus_12345aaaabbb"}` **Correct Example:** ```json get /v1/customers/cus_4e25112ac20e144ad073a614dc46934b ``` | | **Error code:** ERROR_HOSTED_PAGE_INVALID_COUNTRY **Message:** The request tried to create a checkout page, but the country was not recognized. The request was rejected. Corrective action: For the `country` field, use the 2-letter ISO 3166-1 ALPHA-2 code in uppercase letters. **Explanation:** The `country` code provided is either misspelled or not in the standard ISO 2-letter format. **Error Example:** `{"country":"UK"}` **Correct Example:** ```json { "country": "GB" } ``` | | **Error code:** ERROR_HOSTED_PAGE_INVALID_EXPORT_TYPE **Message:** The request tried to create a follow-up message after a payment via checkout page, but the `type` parameter was not recognized. The request was rejected. Corrective action: Set `type` to **email** or **text**. **Explanation:** You requested an invalid notification type. Notifications must be sent via **email** or **text** (SMS). | | **Error code:** ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE **Message:** The request tried to create a checkout page, but the payment method was not recognized. The request was rejected. Corrective action: Specify a payment method that is valid for the country. Use 'List Payment Methods by Country'. **Explanation:** The `payment_method_type` provided does not exist or is not active in the specified country. Ensure that the country and payment method type match. **Error Example:** `{"country":"GB","payment_method_types_include":["sg_grabpay_ewallet"]}` **Correct Example:** ```json { "country": "SG", "payment_method_types_include": [ "sg_grabpay_ewallet" ] } ``` | | **Error code:** ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE_AND_PAYMENT_METHOD_TYPE_CATEGORIES **Message:** The request tried to create a checkout page, but the request specified both a payment method type and a set of payment method type categories. The request was rejected. Corrective action: Specify `payment_method_type` or a set of types in `payment_method_type_categories`, or leave both parameters blank. **Explanation:** You provided conflicting ways to define payment methods. Choose either a specific type or a broad category filter, not both. **Error Example:** `{"payment_method_types_include":["sg_grabpay_ewallet"],"payment_method_type":"sg_grabpay_ewallet"}` **Correct Example:** ```json { "payment_method_type": "sg_grabpay_ewallet" } ``` | | **Error code:** ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE_CATEGORIES **Message:** The request tried to create a checkout page, but one or more of the values in `payment_method_type_categories` was set to **null**, an empty string or an unrecognized value. The request was rejected. Corrective action: Provide an array of strings that contain only the following values: **bank_redirect**, **bank_transfer**, **card**, **cash**, **ewallet**. **Explanation:** The list of categories in your request contains invalid or empty values. Ensure all strings in the array match supported Rapyd categories. **Error Example:** `{"payment_method_type_categories":["credit","cash"]}` **Correct Example:** ```json { "payment_method_type_categories": [ "card", "cash" ] } ``` | | **Error code:** ERROR_HOSTED_PAGE_INVALID_STATUS **Message:** The request tried to create a payment for a checkout page, but the checkout page was already paid. The request was rejected. Corrective action: Determine why there were multiple attempts to pay the same checkout page. **Explanation:** A transaction attempt was made using a Checkout ID that has already reached a final status (**CLO**). A checkout page can only be paid once. | | **Error code:** ERROR_HOSTED_PAGE_PAYMENT_METHOD_TYPE_CATEGORIES_NOT_ENABLED **Message:** The request tried to create a checkout page, but one or more of the payment method type categories was not enabled. The request was rejected. Corrective action: Use the Client Portal to enable the payment method type categories you want to appear in the checkout page. **Explanation:** You are trying to show payment methods from a category (like **e-wallets**) that you haven't activated in your Rapyd account settings. | | **Error code:** ERROR_HOSTED_PAGE_UNREADABLE_PAYMENT_METHOD_TYPES_EXCLUDE_LIST **Message:** The request tried to create a checkout page with a list of payment method types to exclude, but the data was not recognized. The request was rejected. Corrective action: In `payment_method_types_exclude`, specify a list of strings, each of which is a payment method type. **Explanation:** The format of your exclusion list is incorrect. It must be a simple array of strings containing valid Rapyd payment method IDs. **Error Example:** `{ "payment_method_types_include": [ "at_mastercard_card", "at_credit_card" ] }` **Correct Example:** ```json { "payment_method_types_include": [ "at_mastercard_card", "at_visa_card" ] } ``` | | **Error code:** ERROR_HOSTED_PAGE_UNREADABLE_PAYMENT_METHOD_TYPES_INCLUDE_LIST **Message:** The request tried to create a checkout page with a list of payment method types to include, but the data was not recognized. The request was rejected. Corrective action: In `payment_method_types_include`, specify a list of strings, each of which is a payment method type. **Explanation:** The inclusion list contains data that cannot be parsed. Ensure the `payment_method_types_include` field is a properly formatted JSON array. **Error Example:** `{}` **Correct Example:** ```json { v} ``` | | **Error code:** ERROR_HOSTED_PAGE_UNRECOGNIZED_PAYMENT_METHOD_TYPE **Message:** The request tried to create a checkout page, but the payment method type specified is not available or does not exist at all. The request was rejected. Corrective action: Specify payment method types that are valid for the country. Use ‘List Payment Methods by Country’. **Explanation:** You provided an ID for a payment method that is not supported by Rapyd or is not configured for your merchant account. | | **Error code:** ERROR_HOSTED_PAGE_UNRECOGNIZED_PAYMENT_METHOD_TYPES_TO_INCLUDE **Message:** The request tried to create a hosted page, but the payout method types in `payout_method_types_include` were not recognized. The request was rejected. Corrective action: Specify payout method types that are valid for the category, country and entity type. Use 'List Payout Method Types'. **Explanation:** One or more IDs in your payout inclusion list are invalid. Payout method IDs are specific to the country and entity type (individual vs. company). **Error Example:** `{"payment_method_types_include":["card"]}` **Correct Example:** ```json { "payment_method_types_include: [ "sg_debit_visa_card" ] } ``` | | **Error code:** ERROR_NOT_AFT_METHOD **Message:** The request attempted a hosted page operation for funding a wallet, but one of the payment methods does not support account-funding transactions (AFT) The request was rejected. Corrective action: In the `payment_method_types` array, list only payment methods that support AFT. **Explanation:** You are trying to fund a wallet using a payment method category (like **cash**) that does not support the AFT workflow. Only use payment method types that support AFT. | | **Error code:** INVALID_DISCOUNT_PERCENT_AND_AMOUNT_OFF **Message:** The request tried to apply a discount, but the type of discount could not be determined. The request was rejected. Corrective action: Set `percent_off` or set `amount_off`. **Explanation:** You must choose one method for the discount. You cannot specify both a percentage and a fixed amount for the same discount line item. **Error Example:** `{"amount_off":10,"percent_off":5}` **Correct Example:** ```json { "discount": { "amount_off": 10, "currency": "USD" } } ``` |