Acompanhar transações Pix

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

Para saber que um Pix foi pago em tempo real, use 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.

Listar transações

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.

curl "https://api.nyxpag.com.br/v1/transactions?status=approved&type=payment&limit=50" \
  -H "Authorization: Bearer $NYXPAG_API_KEY"

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);

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
$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';

A resposta

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

{
  "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.

Consultar uma transação

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.

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.

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

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.

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.

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);
}

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
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++;
    }
}

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.

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

Ciclo de vida

Estados, transições e o objeto transação campo a campo.

Listar transações

Referência completa do endpoint.

Comece aqui

Receber

Dinheiro na conta

Disputas

Confiabilidade

Ajuda

Acompanhar transações Pix

Listar transações

A resposta

Consultar uma transação

refresh=true

Conciliação: um job que confere tudo

Estados

Ciclo de vida

Listar transações

​Listar transações

​A resposta

​Consultar uma transação

​refresh=true

​Conciliação: um job que confere tudo

​Estados

Ciclo de vida

Listar transações

Listar transações

A resposta

Consultar uma transação

refresh=true

Conciliação: um job que confere tudo

Estados