GET https://api.fire.rest/api/v1/fire/external/payment-decline-reasons
x-api-key: <your_api_key>
{
"success": true,
"data": {
"groups": [
{
"code": "funds",
"label": { "en": "Funds", "es": "Fondos", "pt": "Fundos" },
"displayOrder": 1,
"reasons": [
{
"code": "INSUFFICIENT_FUNDS",
"groupCode": "funds",
"label": {
"en": "Insufficient funds",
"es": "Fondos insuficientes",
"pt": "Saldo insuficiente"
},
"displayOrder": 1
}
]
},
{
"code": "technical",
"label": { "en": "Technical", "es": "Técnico", "pt": "Técnico" },
"displayOrder": 4,
"reasons": [
{
"code": "ISSUER_UNAVAILABLE",
"groupCode": "technical",
"label": {
"en": "Issuer unavailable",
"es": "Emisor no disponible",
"pt": "Emissor indisponível"
},
"displayOrder": 1
}
]
}
]
}
}
{
"success": false,
"error": "UNAUTHORIZED",
"message": "Invalid or expired API key"
}
{
"success": false,
"error": "FORBIDDEN",
"message": "API key does not have the required scope: orders:read"
}
API
Decline reasons
Grouped catalog of payment decline reasons. Map your acquirer codes to these and send ours.
GET
/
api
/
v1
/
fire
/
external
/
payment-decline-reasons
GET https://api.fire.rest/api/v1/fire/external/payment-decline-reasons
x-api-key: <your_api_key>
{
"success": true,
"data": {
"groups": [
{
"code": "funds",
"label": { "en": "Funds", "es": "Fondos", "pt": "Fundos" },
"displayOrder": 1,
"reasons": [
{
"code": "INSUFFICIENT_FUNDS",
"groupCode": "funds",
"label": {
"en": "Insufficient funds",
"es": "Fondos insuficientes",
"pt": "Saldo insuficiente"
},
"displayOrder": 1
}
]
},
{
"code": "technical",
"label": { "en": "Technical", "es": "Técnico", "pt": "Técnico" },
"displayOrder": 4,
"reasons": [
{
"code": "ISSUER_UNAVAILABLE",
"groupCode": "technical",
"label": {
"en": "Issuer unavailable",
"es": "Emisor no disponible",
"pt": "Emissor indisponível"
},
"displayOrder": 1
}
]
}
]
}
}
{
"success": false,
"error": "UNAUTHORIZED",
"message": "Invalid or expired API key"
}
{
"success": false,
"error": "FORBIDDEN",
"message": "API key does not have the required scope: orders:read"
}
Returns the catalog Fire uses to classify the declined payments you send to
Confirm payment.
The catalog carries code, label and group. Nothing else. It does not tell you whether to retry or
who should act: that call is yours and your acquirer’s — you are the ones who see the transaction.
Available groups:
It is stored on write and never recomputed on read, so your historical metrics do not shift on their
own when the catalog grows.
How to use it
Your acquirer (Rede, Cielo, Stone…) returns its own code when a card is declined:51,
insufficient_funds, NSF. Each one spells it differently.
This catalog is Fire’s vocabulary. You do the mapping on your side, once, and send Fire’s code in
decline_reason:
your acquirer says "51" → you send "INSUFFICIENT_FUNDS"
It works like cancellation reasons: you download the catalog and send one of its codes. Fire does
not store each acquirer’s codes — you have the Rede or Cielo documentation, and keeping every
provider’s vocabulary for every country would not be sustainable.That is also why this endpoint does not hang off an order: it is the same for your whole account.
Authentication
string
required
Your Fire API key with the
orders:read scope.Request
GET https://api.fire.rest/api/v1/fire/external/payment-decline-reasons
x-api-key: <your_api_key>
Response
Ordered groups, each with its reasons. Groups with no active reasons are not returned.| field | what it means |
|---|---|
code | Fire’s code. This is the one you must send in decline_reason |
label | text in en, es and pt |
funds, card, security, technical, operational.
{
"success": true,
"data": {
"groups": [
{
"code": "funds",
"label": { "en": "Funds", "es": "Fondos", "pt": "Fundos" },
"displayOrder": 1,
"reasons": [
{
"code": "INSUFFICIENT_FUNDS",
"groupCode": "funds",
"label": {
"en": "Insufficient funds",
"es": "Fondos insuficientes",
"pt": "Saldo insuficiente"
},
"displayOrder": 1
}
]
},
{
"code": "technical",
"label": { "en": "Technical", "es": "Técnico", "pt": "Técnico" },
"displayOrder": 4,
"reasons": [
{
"code": "ISSUER_UNAVAILABLE",
"groupCode": "technical",
"label": {
"en": "Issuer unavailable",
"es": "Emisor no disponible",
"pt": "Emissor indisponível"
},
"displayOrder": 1
}
]
}
]
}
}
{
"success": false,
"error": "UNAUTHORIZED",
"message": "Invalid or expired API key"
}
{
"success": false,
"error": "FORBIDDEN",
"message": "API key does not have the required scope: orders:read"
}
What Fire stores
When you send a declined payment, Fire looks that code up in the catalog and stores the group and group alongside what you sent:"declineReason": "DO_NOT_HONOR", // what you sent
"declineReasonCode": "DO_NOT_HONOR", // found in the catalog
"declineGroup": "security"
A code that is not in the catalog does not fail the charge. It is stored as-is, with no group,
and those records fall outside anything grouped by reason.Confirm payment tells you in the response with
resolvedTo: null. Check it on your first integration: if your mapping has a typo, every
decline lands unclassified and nothing fails.Related
Confirm payment
Record the charge, with approved and declined tenders.
Get order
Check the order status and its total.