Payment failure codes

Overview

When a payment reaches FAILED status, Reservepay attaches a failure_code that tells you why. These failure codes are canonical across payment methods: insufficient_funds means the same thing no matter how the customer paid. Underneath, each payment method's bank or provider returns its own response code or message, and Reservepay maps that raw response onto one of these shared codes.

This guide lists the failure codes Reservepay produces for card payments, split between the card authorization itself and the 3D Secure authentication step that precedes it.

Where to read the failure code

Failure codes live on the payment object as two fields:

Both fields are null unless the payment failed. Retrieve them with find-payment. The payment list and search endpoints such as list-payments and filter-payments return the same payment object, so the same two fields are available there.

The payment_completed webhook fires when a payment transitions to either SUCCESSFUL or FAILED, but its payload carries only status, not the failure code. When you receive payment_completed with a status of FAILED, call find-payment with the payment_id from the event to read failure_code.

Failure codes are separate from the API error triples returned when a request itself is rejected. See Error Handling for those. A failed payment is a successful API call describing a declined payment.

How to handle failure codes

Branch your logic on the machine-readable failure_code, not on the human-readable failure_message. Messages exist for surfacing to users, and codes are stable across bank wording changes. A few codes are worth handling distinctly from a plain decline:

• issuer_not_available means the card issuer couldn't be reached, so the payment was never authorized. This is often transient, so it's reasonable to let the customer retry immediately.
• generic_decline is Reservepay's catch-all for a raw response that doesn't map to anything more specific yet. Treat it the same as any other decline, and don't build logic that depends on it disappearing over time.
• Everything else, including insufficient_funds, invalid_cvv, expired_card, and limit_exceeded, is a terminal decline for that attempt. Show the customer the message and let them choose a different payment method or card.

Card

Card (3DS step)

These codes come from the 3D Secure authentication step, before the card network authorizes the payment itself.