This section outlines the most common payment_refused errors returned during payment processing via the Demand API. Each error includes its description, example response (if applicable), likely causes, and recommended actions.
This section covers generic payment refusal errors returned when the payment could not be processed successfully.
All payment refusal errors described in this guide return:
HTTP status code: 422 Unprocessable Content
Name: Payment refused
Description:
This is a generic error returned when the Payment Service Provider (PSP) declines the transaction without exposing a more specific reason.
Recommended action
- Contact the issuing bank for more information regarding the refusal.
If an explanatory message is included in the response, provide these details to the issuing bank when troubleshooting.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused",
"message": "Payment could not be processed: Payment collection failed."
}
]
}
Name: payment_refused_book_process_failed
Description: This error indicates that the booking process failed during payment processing. In Demand API v2, similar failures were sometimes surfaced as payment-related fraud errors.
This is usually returned when the PSP declines the transaction.
Possible causes:
- The PSP rejected the transaction based on internal validation or fraud detection systems.
- Incorrect payment or traveller details were submitted multiple times.
- Invalid or unsupported payment authentication data was provided.
- The email address provided in the booker payload is blocklisted (
email_blocklist) due to previous fraud prevention checks or suspicious activity. In this case, the fraud validation fails.
Recommended actions:
- Contact the PSP to identify the fraud trigger and obtain further details.
- Ensure that users enter accurate payment details.
- If incorrect data was submitted, wait before retrying the /orders/create request.
- If the email address may be blocklisted, retry the booking using a different email address in the booker payload.
Name: payment_refused_insufficient_funds
Description:
- Returned by the PSP when the card does not have enough available balance to cover the charge.
- Subsequent attempts at a later time may succeed.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused_insufficient_funds",
"message": "Payment could not be processed: There is insufficient funds on the credit card used to book."
}
]
}
Recommended action - Ask the user to ensure sufficient funds are available or use an alternative payment method.
Name: payment_refused_budget_overflow
Description:
- The transaction exceeds the budget or credit limit associated with the card.
Recommended action - Confirm the card’s spending limit and retry with a valid payment method.
Name: payment_refused_card_is_expired
Description:
- The provided credit card is no longer valid because it has expired.
Recommended action - Retry the payment using a card with a valid expiry date.
Name: payment_refused_card_lost
Description:
- The issuing bank or PSP rejected the transaction because the card has been reported as lost or stolen.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused_card_lost",
"message": "Payment could not be processed: Payment collection failed."
}
]
}Recommended action - Use a different card and contact the issuing bank for additional clarification if needed.
Name: payment_refused_invalid_card_number
Description:
- The provided credit card number is invalid.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused_invalid_card_number",
"message": "Payment could not be processed: The given credit card number is invalid."
}
]
}Recommended action - Double-check the card number for accuracy, ensuring it matches the correct format.
Name: payment_refused_invalid_amount
Description: This error is returned by Booking.com when the amount to be captured is invalid. It usually indicates:
- The authorised amount is lower than the amount that needs to be captured.
- In rare cases, the authorised amount may exceed the expected capture amount.
This error usually happens due to:
- Rounding issues or configuration bugs.
- A mismatch between the price shown in orders/preview and the final price sent in orders/create.
Example:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused_invalid_amount",
"message": "Payment could not be processed: The amount to be charged is invalid."
}
]
}Recommended action - Verify that the amount being charged matches the expected value and format.
Name: payment_refused_invalid_payment_method
Description:
- The provided payment method is invalid or unsupported.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": payment_refused_invalid_payment_method",
"message": "Parameter 'payment.method' is invalid."
}
]
}Recommended action - Review the payment methods documentation and ensure the specified method is supported.
Name: payment_refused_issuer_cvc_check_failed
Description:
- The Card Verification Code (CVC) provided with the payment is invalid, and the issuer rejected the transaction.
Recommended action - Verify that the correct CVC was entered and matches the card details.
Name: payment_refused_withdrawal_amount_exceeded
Description:
- The requested payment amount exceeds the limit allowed by the credit card.
Recommended action - Check the withdrawal or transaction limit associated with the card and retry with an adjusted amount or different card.
Name: payment_refused_withdrawal_count_exceeded
Description:
- The card has exceeded the allowable number of transactions or withdrawals within a given period.
Recommended action - Use a different card or contact the issuing bank regarding transaction limits.
Name: payment_refused_psp_card_is_blocked
Description:
- The Payment Service Provider (PSP) has blocked the credit card used for the transaction.
Recommended action - Contact the PSP or issuing bank to resolve the card restriction.
Name: payment_refused_sca_required
Description:
- Strong Customer Authentication (SCA) is required for the payment, but the provided authentication is either invalid or incomplete.
This error does not necessarily mean that SCA was omitted entirely. It may also occur if the provided SCA tokens are invalid or expired.
Recommended action
- Ensure that SCA data is provided correctly during the transaction process.
- If the issue persists, contact the PSP or payment provider.
For additional information on supported payment methods, use cases, and guidance on creating order requests, refer to:
For more generic, not-payment related errors refer to the Client error codes and examples.