Response Codes
Quick Reference
WhatAPI response codes
WhyUnderstand and handle every API response
A55 returns structured error codes that map acquirer-specific responses into a consistent set you can program against. Each code includes a description, suggested action, and troubleshooting guidance.
Find codes quickly
Use Ctrl+F (or Cmd+F on macOS) to search for a specific code on this page.
Response code reference
| Code | Description | Suggested action | Troubleshooting |
|---|---|---|---|
CARD_DECLINED | Issuer declined the transaction | Ask customer to use another card | Check if card has international or online restrictions |
INVALID_CARD | Card number fails Luhn check | Validate card number client-side | Ensure no typos in card entry |
EXPIRED_CARD | Expiration date is in the past | Prompt customer to update card | Verify MM/YY format in request |
INSUFFICIENT_FUNDS | Not enough balance on card | Suggest lower amount or different card | Consider offering installments |
INVALID_CVC | CVC/CVV does not match | Re-prompt for security code | Check field mapping in your integration |
3DS_REQUIRED | 3D Secure authentication needed | Redirect to 3DS challenge URL | Ensure return_url is set in request |
3DS_FAILED | Cardholder failed 3DS challenge | Do not retry, ask for another card | Check if card supports 3DS2 |
3DS_UNAVAILABLE | 3DS service temporarily down | Retry after 60 seconds | Verify acquirer 3DS enrollment |
PROCESSING_ERROR | Internal processing failure | Retry with exponential backoff | Include idempotency key on retry |
TIMEOUT | Acquirer did not respond in time | Retry once after 30 seconds | Check charge status before retrying |
DUPLICATE_REQUEST | Idempotency key already used | Use the original response | Generate unique keys per attempt |
FRAUD_SUSPECTED | Risk engine flagged transaction | Do not retry, review manually | Check antifraud score threshold |
CURRENCY_NOT_SUPPORTED | Currency not enabled for merchant | Use a supported currency | See provider capabilities |
AMOUNT_INVALID | Amount below minimum, above max, or wrong decimal precision | Validate amount before sending | CLP and COP are zero-decimal currencies — send integers. BRL, MXN, USD, PEN, ARS use 2 decimals. EUR uses 2 decimals (FX display only). See currency decimal rules |
amount_below_minimum | Amount is below the acquirer or method minimum (normalized code — same as amount_too_low) | Increase amount | Boleto minimum is R$5.00. OXXO, SPEI minimums vary by acquirer. See provider capabilities |
amount_exceeds_maximum | Amount exceeds the method or acquirer maximum (normalized code — same as amount_too_high) | Reduce amount or split into multiple charges | OXXO maximum is MXN $10,000 per transaction. See provider capabilities |
amount_too_low | Acquirer-native code for amount below minimum (alias of amount_below_minimum) | Increase the value to continue | Some acquirers return this instead of amount_below_minimum |
amount_too_high | Acquirer-native code for amount above maximum (alias of amount_exceeds_maximum) | Try a lower amount | Some acquirers return this instead of amount_exceeds_maximum |
MERCHANT_NOT_ALLOWED | Merchant not authorized for operation | Contact A55 support | Verify merchant profile settings |
ACQUIRER_ERROR | Acquirer returned unexpected error | Retry with backoff | Contact support with the charge ID |
Common errors and fixes
Category quick map
| Scenario | Codes |
|---|---|
| Card declined | CARD_DECLINED, INSUFFICIENT_FUNDS, FRAUD_SUSPECTED |
| Card data problems | INVALID_CARD, EXPIRED_CARD, INVALID_CVC |
| 3DS | 3DS_REQUIRED, 3DS_FAILED, 3DS_UNAVAILABLE |
| Infrastructure | PROCESSING_ERROR, TIMEOUT, ACQUIRER_ERROR, DUPLICATE_REQUEST |
| Amount / currency | AMOUNT_INVALID, amount_below_minimum, amount_exceeds_maximum, amount_too_low, amount_too_high, CURRENCY_NOT_SUPPORTED |
| Configuration | MERCHANT_NOT_ALLOWED |
Never log card data
Never log full card numbers, CVC values, or sensitive authentication data. This is a serious security risk and can result in data breaches.