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

# Acompanhar transações Pix

> Liste transações com paginação e filtros, consulte uma por ID ou externalId, use refresh=true e monte uma conciliação confiável com a NyxPag API.

Dois endpoints cobrem o acompanhamento: `GET /transactions` lista com filtros e `GET /transactions/{id}` consulta uma. Ambos exigem a permissão `transactions:read`.

<Tip>
  Para saber que um Pix foi pago em tempo real, use [webhooks](/guides/webhooks). Os endpoints desta página servem para painéis, relatórios e **conciliação**: conferir que o que você tem bate com o que a NyxPag tem.
</Tip>

## Listar transações

```http theme={"dark"}
GET https://api.nyxpag.com.br/v1/transactions
```

Retorna cobranças e transferências da conta, da mais recente para a mais antiga.

| Parâmetro | Tipo | Descrição |
| - | - | - |
| `page` | integer | Página, a partir de `1`. Padrão `1` |
| `limit` | integer | Itens por página, de `1` a `100`. Padrão `20` |
| `status` | string | `pending`, `approved`, `failed`, `cancelled` ou `refunded` |
| `type` | string | `payment` (cobrança) ou `withdrawal` (transferência) |

Os filtros se combinam (E lógico). Um valor fora da lista retorna `400` com `invalid_status` ou `invalid_type`.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://api.nyxpag.com.br/v1/transactions?status=approved&type=payment&limit=50" \
    -H "Authorization: Bearer $NYXPAG_API_KEY"
  ```

  ```javascript JavaScript theme={"dark"}
  const params = new URLSearchParams({ status: "approved", type: "payment", limit: "50" });

  const res = await fetch(`https://api.nyxpag.com.br/v1/transactions?${params}`, {
    headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` },
  });
  const { data, pagination } = await res.json();
  console.log(data.length, pagination);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.get(
      "https://api.nyxpag.com.br/v1/transactions",
      params={"status": "approved", "type": "payment", "limit": 50},
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      timeout=15,
  )
  body = res.json()
  print(len(body["data"]), body["pagination"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $query = http_build_query(['status' => 'approved', 'type' => 'payment', 'limit' => 50]);
  $ch = curl_init("https://api.nyxpag.com.br/v1/transactions?$query");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NYXPAG_API_KEY')],
  ]);
  $body = json_decode(curl_exec($ch), true);
  echo count($body['data']) . ' itens, ' . $body['pagination']['pages'] . ' páginas';
  ```
</CodeGroup>

### A resposta

Os valores são **reais decimais**, não centavos: `149.9` é R\$ 149,90.

```json theme={"dark"}
{
  "success": true,
  "data": [
    {
      "id": "txn_mabc123_0123456789abcdef",
      "externalId": "PEDIDO-1042",
      "direction": "in",
      "type": "payment",
      "method": "pix",
      "status": "approved",
      "amount": 149.9,
      "fee": 0.5,
      "netAmount": 149.4,
      "description": "Pedido #1042",
      "approvedAt": "2026-10-03T14:01:31.000Z",
      "createdAt": "2026-10-03T14:00:00.000Z",
      "updatedAt": "2026-10-03T14:01:31.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 47, "pages": 1 },
  "requestId": "req_01H..."
}
```

Cada item é o objeto transação, resumido aqui. Veja todos os campos em [Ciclo de vida](/guides/confiabilidade/ciclo-de-vida).

## Consultar uma transação

```http theme={"dark"}
GET https://api.nyxpag.com.br/v1/transactions/{id}
```

O `{id}` aceita **dois** identificadores:

* o `id` que a NyxPag devolveu (`txn_...`);
* o `externalId` que **você** enviou ao criar.

Por isso você não precisa guardar o ID da NyxPag: o número do seu pedido basta.

```bash theme={"dark"}
curl "https://api.nyxpag.com.br/v1/transactions/PEDIDO-1042" \
  -H "Authorization: Bearer $NYXPAG_API_KEY"
```

Se não existir, a resposta é `404` com `error.code: "not_found"`.

### refresh=true

Enquanto a transação está `pending`, `?refresh=true` pede à NyxPag que confira o estado mais recente na origem antes de responder.

```bash theme={"dark"}
curl "https://api.nyxpag.com.br/v1/transactions/PEDIDO-1042?refresh=true" \
  -H "Authorization: Bearer $NYXPAG_API_KEY"
```

<Warning>
  Cada chamada com `refresh=true` é mais lenta e gasta a cota de 100 requisições por 60 segundos da sua chave. Nunca faça polling agressivo com ele. Quem precisa do estado em tempo real usa webhook.
</Warning>

## Conciliação: um job que confere tudo

Webhooks podem falhar depois de 8 tentativas. Um job periódico que percorre as transações recentes fecha esse buraco.

<CodeGroup>
  ```javascript JavaScript theme={"dark"}
  async function reconcile() {
    let page = 1;
    let pages = 1;

    do {
      const res = await fetch(
        `https://api.nyxpag.com.br/v1/transactions?status=approved&type=payment&limit=100&page=${page}`,
        { headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` } },
      );
      const body = await res.json();
      pages = body.pagination.pages;

      for (const tx of body.data) {
        // marca como pago o pedido que o webhook não chegou a atualizar
        await orders.markPaidIfOpen(tx.externalId, tx.id);
      }
      page += 1;
    } while (page <= pages);
  }
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  def reconcile():
      page, pages = 1, 1
      while page <= pages:
          res = requests.get(
              "https://api.nyxpag.com.br/v1/transactions",
              params={"status": "approved", "type": "payment", "limit": 100, "page": page},
              headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
              timeout=15,
          )
          body = res.json()
          pages = body["pagination"]["pages"]
          for tx in body["data"]:
              # marca como pago o pedido que o webhook não chegou a atualizar
              orders.mark_paid_if_open(tx["externalId"], tx["id"])
          page += 1
  ```

  ```php PHP theme={"dark"}
  <?php
  function reconcile(): void
  {
      $page = 1;
      $pages = 1;

      while ($page <= $pages) {
          $ch = curl_init("https://api.nyxpag.com.br/v1/transactions?status=approved&type=payment&limit=100&page=$page");
          curl_setopt_array($ch, [
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NYXPAG_API_KEY')],
          ]);
          $body = json_decode(curl_exec($ch), true);
          $pages = $body['pagination']['pages'];

          foreach ($body['data'] as $tx) {
              // marca como pago o pedido que o webhook não chegou a atualizar
              orders_mark_paid_if_open($tx['externalId'], $tx['id']);
          }
          $page++;
      }
  }
  ```
</CodeGroup>

<Note>
  Respeite o limite: cada página é uma requisição, e as 100 por minuto são da chave inteira. Rode o job fora do horário de pico, com `limit=100`, e pare em `429` esperando o `Retry-After`.
</Note>

## Estados

| `status` | Significa |
| - | - |
| `pending` | Esperando pagamento ou processamento |
| `approved` | Concluída: Pix pago ou transferência enviada |
| `failed` | Falhou de forma definitiva |
| `cancelled` | Cancelada. `expired: true` indica que passou dos 15 minutos |
| `refunded` | Estornada |

<CardGroup cols={2}>
  <Card title="Ciclo de vida" icon="workflow" href="/guides/confiabilidade/ciclo-de-vida">
    Estados, transições e o objeto transação campo a campo.
  </Card>

  <Card title="Listar transações" icon="code" href="/api-reference/transações/listar-transações">
    Referência completa do endpoint.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.