Debugging Payment Failures

When a payment attempt fails, the payment page remains UNPAID — it doesn't close. The customer can retry. This guide explains how to see what went wrong and what to do about it.

Step 1 — Enable PAYMENT_ATTEMPT_FAILED webhooks

By default, PAYMENT_ATTEMPT_FAILED is not sent. Without it, your server has no visibility into why attempts are failing.

Contact [email protected] to enable it for your account. Once enabled, every declined attempt sends a webhook with an errorCode field.

See Webhook Event Reference for the full payload shape.

Step 2 — Read the errorCode

The errorCode in the PAYMENT_ATTEMPT_FAILED payload is the merchantResultCode — the machine-readable decline reason. Use it to triage.

Issuer declines

The customer's bank rejected the transaction.

`errorCode`	Meaning	Action
`ISSUER_DECLINE`	Generic bank decline	Ask customer to try another card or contact their bank
`INSUFFICIENT_FUNDS`	Card balance too low	Ask customer to use another card
`EXPIRED_CARD`	Card past expiry date	Ask customer to update card details
`INCORRECT_CARD_DETAILS`	Wrong card number, expiry, or CVV	Ask customer to re-enter details
`INVALID_CARD`	Card number fails validation	Ask customer to try another card
`ISSUER_DECLINE_FRAUD`	Issuer flagged as suspected fraud	Customer must contact their bank
`ISSUER_DECLINE_LIMIT`	Issuer transaction limit exceeded	Customer must contact their bank
`ISSUER_DECLINE_RESTRICTED_CARD`	Card restricted by issuer	Customer must contact their bank
`ISSUER_DECLINE_TRANSACTION_NOT_PERMITTED`	Transaction type not permitted on this card	Ask customer to try another card
`FAILED_3DS`	3D Secure authentication failed	Ask customer to retry; if persistent, contact support

Retryability

`errorCode`	Can retry?
`GENERIC_DECLINE_RETRY`	Yes — ask customer to try again or use another card
`GENERIC_DECLINE_ONLY`	No — do not retry; ask customer to use a different card

Risk / fraud (Breeze-side)

These are declined by Breeze's risk engine, not the issuer. They indicate the transaction was blocked before it reached the bank.

`errorCode`	Meaning
`RISK_DECLINE`	General risk block
`RISK_SOFT`	Soft risk flag — page may still succeed on retry
`RISK_HARD`	Hard block — payment will not succeed
`RISK_HARD_RECEIVED_CHB`	Customer has prior chargeback history
`RISK_HARD_RECEIVED_FRAUD`	Customer has prior fraud history
`RISK_NAME_MISMATCH`	Name on card doesn't match customer name
`RISK_SHARED_CARD`	Card used across multiple accounts
`RISK_ONGOING_CHECK`	Risk review in progress

For RISK_HARD declines, the payment will not succeed regardless of retries. Contact [email protected] if you believe a block is incorrect.

Location / compliance

These fire when the payment originates from a geography Breeze doesn't support for your account.

`errorCode`	Meaning
`GEOLOCATION_COUNTRY_NOT_SUPPORTED`	Customer's detected location is not supported
`GEOLOCATION_STATE_NOT_SUPPORTED`	Customer's detected state is not supported
`RESTRICTED_LOCATION`	Location is on a restricted list
`CARD_COUNTRY_NOT_SUPPORTED`	Card issued in an unsupported country
`BILLING_COUNTRY_NOT_SUPPORTED`	Billing address country not supported
`COMPLIANCE_REASONS`	Blocked for regulatory compliance reasons

If you're seeing location errors unexpectedly, contact support to verify your account's geographic configuration.

Card type

`errorCode`	Meaning
`CARD_NOT_SUPPORTED`	Card network not accepted
`CARD_TYPE_NOT_SUPPORTED`	Card type (e.g. prepaid) not accepted
`RISK_CARD_TYPE_NOT_ALLOWED`	Card type blocked by risk rules

System / other

`errorCode`	Meaning
`PARTNER_ERROR`	Error from a downstream payment partner
`APPLICATION_ERROR`	Internal application error
`SYSTEM_ERROR`	System-level error
`DUPLICATE_PAYMENT`	Duplicate of a recent payment on this page
`DUPLICATE_CONCURRENT_PAYMENT`	Concurrent duplicate submission

For PARTNER_ERROR, APPLICATION_ERROR, or SYSTEM_ERROR, retry once. If the error persists, contact [email protected] with the pageId and timestamp.

Step 3 — Escalation

If you can't resolve the failure from the error code:

Collect the pageId, paymentId, and errorCode from the webhook payload
Note the timestamp (UTC)
Email [email protected] with those details

For RISK_HARD blocks that appear to be false positives, include the pageId and the customer's referenceId.