# Eventos (postMessage)

Como o popup do checkout comunica com a sua página.

Internamente, a SDK comunica com o popup do checkout por `postMessage`. Na maioria dos
casos **não** precisa de ouvir estes eventos — use os [callbacks](/pt/sdk/callbacks).
Esta página é para integrações avançadas que querem reagir diretamente às mensagens.

## Ciclo do popup

```mermaid
sequenceDiagram
    participant Page as A sua página
    participant Popup as Popup (checkout)

    Page->>Popup: Abre popup
    Popup-->>Page: PAYMENT_COMPONENT_READY
    Page->>Popup: PAYMENT_PROPS (config + ordem)
    Note over Popup: Cliente paga
    Popup-->>Page: PAYMENT_SUCCESS / PENDING / CANCELED / ERROR
    Popup-->>Page: popup fecha
```

## Eventos

| Evento | Sentido | Significado |
|---|---|---|
| `PAYMENT_COMPONENT_READY` | popup → página | O popup carregou e está pronto. |
| `PAYMENT_PROPS` | página → popup | Resposta da página com a configuração e a ordem. |
| `PAYMENT_SUCCESS` | popup → página | Pagamento bem-sucedido. |
| `PAYMENT_PENDING` | popup → página | Pendente (referência EMIS). |
| `PAYMENT_CANCELED` | popup → página | Cancelado. |
| `PAYMENT_ERROR` | popup → página | Erro. |

## Domínio do checkout

O popup é servido a partir do domínio oficial do checkout FaciPay:

| Ambiente | Origem do checkout |
|---|---|
| Produção | `https://www1.facipay.co.ao` |
| Sandbox | `https://www31.facipay.co.ao` |

A SDK valida a origem internamente antes de processar cada mensagem.

## Ouvir mensagens (avançado)

Na prática **não** precisa disto — a SDK já trata do `postMessage` e chama os
[callbacks](/pt/sdk/callbacks). Use esta abordagem apenas para integrações que queiram
reagir diretamente.

<Warning>
**Valide sempre `event.origin`** contra o domínio oficial do checkout antes de confiar na
mensagem. Ignore qualquer mensagem de outra origem.
</Warning>

```js
const CHECKOUT_ORIGIN = 'https://www1.facipay.co.ao'; // sandbox: www31.facipay.co.ao

window.addEventListener('message', (event) => {
  if (event.origin !== CHECKOUT_ORIGIN) return; // ignora outras origens

  const { type } = event.data || {};
  switch (type) {
    case 'PAYMENT_SUCCESS':
      // pagamento concluído
      break;
    case 'PAYMENT_PENDING':
      // referência gerada
      break;
    case 'PAYMENT_CANCELED':
      // cancelado pelo utilizador
      break;
  }
});
```

<Card title="Próximo passo: Tipos & enums" icon="arrow-right" href="/pt/sdk/types">
  Referência de tipos, estados e métodos de pagamento.
</Card>