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"
}

GET

api

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.

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`

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: 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"

It is stored on write and never recomputed on read, so your historical metrics do not shift on their own when the catalog grows.

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.

Confirm payment

Record the charge, with approved and declined tenders.

Get order

Check the order status and its total.

API

Partner APIs

PayBridge

How to use it

Authentication

Request

Response

What Fire stores

Confirm payment

Get order

​How to use it

​Authentication

​Request

​Response

​What Fire stores

​Related

Confirm payment

Get order

How to use it

Authentication

Request

Response

What Fire stores

Related