Failure causes

When a payment fails, the failure cause is added to the failure object of the Payment returned by the HUB2 API. The PaymentIntent also exposes the cause of the last failed attempt in lastPaymentFailure.

Important

These are application errors, unrelated to the HTTP protocol.The HTTP status codes returned by each HUB2 API endpoint are listed in the HUB2 API reference.

The failure causes on this page only concern errors encountered while a transaction is processed. The failure object contains a code, a message that is human-readable when a translation is available, and, for invalid parameters, the list of the parameters concerned (params). Map the code to your own customer-facing text rather than displaying message as is.

New failure causes may be added over time. Handle unknown codes gracefully, for example as a generic failure.

Code	Description
`internal_error`	Payment failed. Internal error. Our technical team has been notified.
`service_unavailable`	Payment failed. The provider is currently unavailable.
`service_temporarily_disabled`	Payment failed. The service is temporarily disabled because of an ongoing incident.
`unknown_reason`	Payment failed. The provider gave no reason.
`reconciliation_failure`	Payment failed. The payment could not be reconciled or confirmed with the provider.
`customer_account_locked`	Payment failed. The customer account is locked by the provider.
`customer_insufficient_funds`	Payment failed. The customer does not have enough funds.
`authentication_failed`	Payment failed. The customer failed to authenticate the payment.
`authentication_timeout`	Payment failed. The customer did not authenticate the payment in time.
`issuer_authentication_unavailable`	Payment failed. The authentication service of the card issuer could not be reached.
`timeout`	Payment failed. The waiting period for payment execution has expired.
`expired`	Payment failed. The payment has expired.
`bad_parameters`	Payment failed. Bad parameters.
`invalid_amount`	Payment failed. The amount is not valid for this operation.
`forbidden_by_provider`	Payment failed. The payment was refused by the provider.
`forbidden_by_provider_maximum_limit`	Payment failed. The payment exceeds a limit set by the provider.
`too_many_request`	Payment failed. The provider is receiving too many requests. Try again later.
`duplicate_request`	Payment failed. A similar operation has just been recorded. Try again later.
`canceled_by_customer`	Payment failed. Canceled by the customer.
`canceled`	Payment failed. Canceled by the provider.
`fraud_suspicion`	Payment failed. The provider detected a suspected fraud.
`unsupported_currency`	Payment failed. The currency is not supported by this provider.
`payer_quota_exceeded`	Payment failed. The customer quota is exceeded.
`invalid_payment_processor`	Payment failed. The selected provider does not allow this operation.
`rejected_by_hub2`	Payment failed. The bank transfer was rejected by HUB2.
`forbidden_by_hub2`	Payment failed. Forbidden by HUB2.
`unsupported_service`	Payment failed. The service is not supported by HUB2.
`invalid_msisdn`	Payment failed. Incorrect phone number (MSISDN).
`blacklisted_msisdn`	Payment failed. The MSISDN is temporarily banned.
`wave_payment_expired`	Payment expired. Do not use the corresponding Wave payment link anymore.
`card_expired`	Payment failed. The card expiry date has passed.
`card_declined`	Payment failed. The card was declined.
`card_stolen`	Payment failed. The card is reported as stolen.
`card_refused`	Payment failed. The card was refused.
`card_invalid`	Payment failed. Invalid card.
`card_cvn_invalid`	Payment failed. The card security code is invalid.
`address_verification_failed`	Payment failed. The address does not match the card.
`payment_limit_reached`	Payment failed. The card limit has been reached.

Getting started

Transfers

Payments

Webhooks

Processing Only

Payment Links

Submerchants

Other

Important