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

# Status de Pagamento

> Cada status dispara um evento diferente nas plataformas de anúncios. Entenda o mapeamento.

O campo `status` que você envia à xTracky determina qual evento é reportado pra cada plataforma de anúncio.

## Tabela de mapeamento

| Status                                                                                               | Descrição                                        | Evento disparado   |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------ |
| <span style={{background:'#fef9c3',padding:'2px 8px',borderRadius:'4px'}}>`waiting_payment`</span>   | Venda gerada, aguardando pagamento (PIX, boleto) | `Add to Cart`      |
| <span style={{background:'#dcfce7',padding:'2px 8px',borderRadius:'4px'}}>`paid`</span>              | Pagamento confirmado                             | `Purchase`         |
| <span style={{background:'#dbeafe',padding:'2px 8px',borderRadius:'4px'}}>`initiate_checkout`</span> | Usuário iniciou o checkout (preencheu dados)     | `InitiateCheckout` |
| <span style={{background:'#fee2e2',padding:'2px 8px',borderRadius:'4px'}}>`failed`</span>            | Pagamento falhou ou foi recusado                 | —                  |
| <span style={{background:'#fee2e2',padding:'2px 8px',borderRadius:'4px'}}>`refunded`</span>          | Venda reembolsada                                | —                  |

<Info>
  **Nomenclatura por plataforma** — Os eventos são traduzidos conforme a rede:

  * Meta: `AddToCart`, `Purchase`, `InitiateCheckout`
  * TikTok: `AddToCart`, `CompletePayment`, `InitiateCheckout`
  * Kwai: `ADD_TO_CART`, `PURCHASE`, `START_CHECKOUT`
  * Google Ads: enviado como conversão com valor
</Info>

## Fluxo recomendado

Pra maximizar sinal enviado às plataformas:

<Steps>
  <Step title="No clique de 'Comprar'">
    Dispare `status=initiate_checkout` (ou use o [botão automático `data-xtracky-checkout`](/scripts/botao-checkout)).
  </Step>

  <Step title="Quando o gateway gera a cobrança">
    Envie `status=waiting_payment` com o `orderId` e o valor. Isso dispara `AddToCart` na plataforma.
  </Step>

  <Step title="Quando o pagamento é confirmado">
    Envie `status=paid` com o **mesmo `orderId`** do passo anterior. A xTracky reconhece que é a mesma venda e dispara `Purchase`.
  </Step>

  <Step title="Se o pagamento falhar ou for reembolsado">
    Envie `status=failed` ou `status=refunded` com o mesmo `orderId`. Isso é registrado no painel (mas não gera evento pra rede).
  </Step>
</Steps>

<Warning>
  **Sempre reutilize o mesmo `orderId`** ao longo do ciclo de vida da venda. É por ele que a xTracky evita disparar `Purchase` duplicado.
</Warning>

## E se eu enviar `status` inválido?

A requisição é rejeitada com HTTP `400`. Os únicos valores aceitos são os cinco listados acima.