> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Decline reasons

> Grouped catalog of payment decline reasons. Map your acquirer codes to these and send ours.

Returns the catalog Fire uses to classify the declined payments you send to
[Confirm payment](/en/api-reference/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"
```

<Note>
  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.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Fire API key with the `orders:read` scope.
</ParamField>

## Request

<RequestExample>
  ```http theme={null}
  GET https://api.fire.rest/api/v1/fire/external/payment-decline-reasons
  x-api-key: <your_api_key>
  ```
</RequestExample>

## 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`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
            }
          ]
        }
      ]
    }
  }
  ```

  ```json 401 — invalid API key theme={null}
  {
    "success": false,
    "error": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
  ```

  ```json 403 — the key lacks the scope theme={null}
  {
    "success": false,
    "error": "FORBIDDEN",
    "message": "API key does not have the required scope: orders:read"
  }
  ```
</ResponseExample>

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

```jsonc theme={null}
"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.

<Warning>
  **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](/en/api-reference/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.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Confirm payment" icon="credit-card" href="/en/api-reference/confirm-payment">
    Record the charge, with approved and declined tenders.
  </Card>

  <Card title="Get order" icon="receipt" href="/en/api-reference/get-order">
    Check the order status and its total.
  </Card>
</CardGroup>