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

# Ciclo de vida das transações

> Os estados pending, approved, failed, cancelled e refunded, as transições, tipos e direções, e o objeto transação da NyxPag API campo a campo.

Toda cobrança e toda transferência nasce `pending` e termina em um estado final. Entender esse ciclo evita os dois erros mais caros de uma integração de pagamento: liberar um pedido que não foi pago e cobrar duas vezes o mesmo pedido.

## Estados

| `status` | O que significa | Final? |
| - | - | - |
| `pending` | Criada e esperando: o pagador ainda não pagou, ou a transferência ainda está sendo processada | Não |
| `approved` | Concluída. Cobrança: o Pix foi pago. Transferência: o dinheiro foi enviado | Sim |
| `failed` | Falhou de forma definitiva | Sim |
| `cancelled` | Cancelada antes de concluir, inclusive por expirar | Sim |
| `refunded` | Estornada | Sim |

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> pending
    pending --> approved: Pix pago / transferência enviada
    pending --> failed: falha definitiva
    pending --> cancelled: cancelada ou expirada
    approved --> refunded: estorno
```

<Note>
  Uma vez fora de `pending`, a transação não volta para ele. Os estados finais `failed` e `cancelled` não viram `approved`.
</Note>

### Expiração

Uma cobrança Pix vale **15 minutos** a partir da criação (`expiresAt`). Se não for paga, a NyxPag a cancela: `status: "cancelled"` e `expired: true`. Você recebe `transaction.cancelled`.

### refunded

`refunded` existe para transações estornadas pela NyxPag. A API pública **não tem endpoint de reembolso**, e esse estado **não dispara** webhook `transaction.*`. Se o seu negócio depende de detectar estornos, concilie com [`GET /transactions`](/guides/pix/acompanhar).

### 202 não é um estado

O código HTTP `202 Accepted` significa que a operação foi recebida e está sendo conferida automaticamente. A transação continua `pending`, com `processingState: "reconciling"`, até virar `approved` ou `failed`.

## O objeto transação

É o `data` de `POST /transactions`, `POST /transfers` e `GET /transactions/{id}`, e o `data` dos eventos `transaction.*`.

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID da NyxPag. `txn_...` para cobrança, `out_...` para transferência |
| `externalId` | string ou null | A sua chave: o `externalId` ou o `Idempotency-Key` que você enviou |
| `direction` | string | `in` (entrada) ou `out` (saída) |
| `type` | string | `payment`, `deposit`, `withdrawal` ou `internal_transfer` |
| `method` | string | `pix` ou `internal` |
| `status` | string | Um dos estados acima |
| `expired` | boolean | `true` quando foi cancelada por passar de 15 minutos |
| `processingState` | string | `monitoring`, `reconciling` ou `completed` |
| `amount` | number | Veja a nota abaixo |
| `fee` | number | Tarifa da operação, em reais |
| `netAmount` | number | Valor líquido |
| `debitedAmount` | number ou null | Transferência: o que saiu do seu saldo |
| `recipientAmount` | number ou null | Transferência: o que o destinatário recebe |
| `description` | string ou null | Descrição enviada |
| `splitAmount` | number | Total descontado por [split](/guides/pix/split) |
| `split` | array | Uma linha por recebedor: `origin`, `amount`, `description` |
| `payer` | object ou null | `name`, `document`, `email`, `bankName` e `state`, quando disponíveis |
| `counterparty` | object ou null | Só em `internal_transfer`: a outra conta, com dados mascarados |
| `pix` | object ou null | `copyPaste` e `qrCodeBase64` |
| `expiresAt` | string ou null | Fim da validade da cobrança |
| `approvedAt` | string ou null | Quando foi aprovada |
| `createdAt` | string | Criação, ISO 8601 UTC |
| `updatedAt` | string | Última mudança, ISO 8601 UTC |
| `acquirer` | string | Informativo. `nyxpag` ou `internal` |
| `providerTransactionId` | string ou null | Informativo. Não use como chave do seu negócio |

<Warning>
  O `amount` muda de significado conforme o sentido. Numa **cobrança**, é o valor que o **pagador paga** (maior que o enviado se você usou `coverFee: true`). Numa **transferência**, é o que o **destinatário recebe**. Sempre pareie `amount` com `direction`.
</Warning>

### processingState

| Valor | Quando |
| - | - |
| `monitoring` | `pending` e acompanhada normalmente |
| `reconciling` | `pending` e em reconciliação automática (o caso do `202`) |
| `completed` | Qualquer estado diferente de `pending` |

## Direção, tipo e método

| `direction` | `type` | Exemplo |
| - | - | - |
| `in` | `payment` | Cobrança Pix criada pela API |
| `in` | `deposit` | Crédito feito pelo dashboard |
| `out` | `withdrawal` | Transferência Pix |
| `in` e `out` | `internal_transfer` | Movimento entre contas NyxPag (`method: "internal"`) |

Combine `direction` e `type` para saber o efeito no saldo: `out` + `withdrawal` reduz o disponível, `in` + `payment` aumenta.

## Como acompanhar

<Steps>
  <Step title="Webhook primeiro">
    `transaction.approved`, `failed` e `cancelled` chegam assim que o estado muda. Veja [transaction.\*](/webhooks/transacoes).
  </Step>

  <Step title="Consulta pelo seu externalId">
    `GET /transactions/PEDIDO-1042` não exige guardar o ID da NyxPag.
  </Step>

  <Step title="refresh=true com moderação">
    Confere o estado mais recente de uma transação `pending`. Gasta a cota.
  </Step>

  <Step title="Conciliação periódica">
    Um job que lista as transações recentes cobre webhook perdido e estados sem webhook, como `refunded`.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Acompanhar transações" icon="search" href="/guides/pix/acompanhar">
    Listagem, filtros, paginação e conciliação.
  </Card>

  <Card title="Eventos de transação" icon="webhook" href="/webhooks/transacoes">
    O payload dos webhooks de cada estado.
  </Card>
</CardGroup>


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