How to handle invoice payment errors
error
status on the invoice API, and to the
invoice.errored
webhook message.payment errored
state.
Following this, we will consider the subscription as inactive (as the customer failed to pay you) meaning that we won’t invoice the customer in the future nor collect payment.
Open
state will stay in this state for as long as the subscription is paused.errored
status on the subscription API, and to
the subscription.errored
webhook message. This state can be used to switch
off the access to your product or move your customer to a free product access.active
status on the subscription API, and to a
subscription.activated
webhook messageerror_type
if the status is failed
:authentication_required
: The card was declined as the transaction requires authentication (e.g.3-D Secure). The customer should go to their portal page and
authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information.
payment_method_authorization_error
: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn’t be reached, or the card requires a PIN.
payment_method_declined
: The payment method was declined for a variety of reasons such as a card reported as lost or stolen, insufficient funds or reaching the limit available on the method to complete the purchase, a payment method on a known block list, etc.
payment_method_expired
: The payment method is expired. The customer should go to their portal page and change their payment method.
payment_method_invalid
: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code).
payment_method_not_supported
: The payment method doesn’t support this type of purchase (e.g. currency, online payment).
declined
: The payment was declined for a variety of reasons such as security
violation, banking service not available, transaction not allowed, etc.
fraud
: The payment provider suspected the transaction was fraudulent and has
been blocked. Don’t report more detailed information to your customer,
and check on your provider account.
processing_error
: The payment couldn’t be processed by the issuer for an unknown reason.
provider_error
: An error occurred when contacting the payment provider to initiate the transaction.
unknown
: A generic error happened on the payment provider side.
invoice.errored
or subscription.errored
message. See more details on the using webhooks
page.