# Callbacks

Assinaturas e shapes de dados de cada callback do botão.

Os callbacks recebem o resultado do pagamento. Cada um é `async`. Alguns recebem um objeto
`actions` para controlar o botão ou reagir ao fecho do popup.

<Note>
Esta referência segue a implementação **JavaScript** atual da SDK (`Button.js`), que é a
fonte autoritativa. As definições TypeScript no repositório estão desatualizadas.
</Note>

## createOrder

```ts
createOrder: () => Promise<string | null>
```

Chamado **antes** de abrir o popup. Cria a ordem no seu backend e devolve um identificador de
transação (o `merchantTransactionId`) — a SDK guarda-o como `paymentOrderId` e usa-o no fluxo.

<Warning>
**Tem** de devolver uma **string não-vazia**. Se devolver `null`, `undefined` ou `''`,
o popup não avança.
</Warning>

```js
async createOrder() {
  const r = await fetch('/api/facipay/create-order', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ items: cart }),
  });
  if (!r.ok) throw new Error('Falha ao criar ordem');
  const { referenceNumber } = await r.json();
  return referenceNumber; // usado como paymentOrderId
}
```

## onApprove

```ts
onApprove: (data, actions) => Promise<void>
```

Pagamento aprovado. `data` tem a forma `{ payment: { orderId, status, type, data } }`.
`actions` expõe **apenas** `onPopupWindowClosed`.

<ResponseField name="data.payment.orderId" type="string">
  O `paymentOrderId` (o valor devolvido por `createOrder`).
</ResponseField>
<ResponseField name="data.payment.status" type="string">
  Estado do pagamento (`paymentStatus`).
</ResponseField>
<ResponseField name="data.payment.type" type="string">
  Tipo de pagamento (`tpPayment`) — `dir` | `mcx` | `ref`.
</ResponseField>
<ResponseField name="data.payment.data" type="object">
  Dados do pagamento (`paymentData`): referência, entidade, valor, etc.
</ResponseField>
<ResponseField name="actions.onPopupWindowClosed(cb)" type="function">
  Regista uma função a correr quando o popup fecha — o sítio certo para redirecionar.
</ResponseField>

```js
async onApprove(data, actions) {
  actions.onPopupWindowClosed(() => {
    window.location.href = `/sucesso?orderId=${data.payment.orderId}`;
  });
}
```

## onPending

```ts
onPending: (data, actions) => Promise<void>
```

Pagamento pendente (Referência EMIS). Mesma forma de `onApprove`:
`{ payment: { orderId, status, type, data } }`. Os dados da referência estão em
`data.payment.data`.

<ResponseField name="data.payment.data.paymentReference" type="string">
  A referência a mostrar ao cliente.
</ResponseField>
<ResponseField name="data.payment.data.entity.number" type="string">
  Número da entidade.
</ResponseField>
<ResponseField name="data.payment.data.entity.name" type="string">
  Nome da entidade.
</ResponseField>
<ResponseField name="data.payment.data.amount" type="number">
  Valor a pagar.
</ResponseField>

```js
async onPending(data, actions) {
  actions.onPopupWindowClosed(() => {
    const ref = data.payment.data.paymentReference;
    const entity = data.payment.data.entity.number;
    window.location.href = `/pendente?ref=${ref}&entity=${entity}`;
  });
}
```

## onCancel

```ts
onCancel: (data) => Promise<void>
```

O utilizador cancelou (evento `PAYMENT_CANCELED`) ou fechou o popup sem concluir. Reabra o
carrinho ou mostre um CTA para tentar de novo.

```js
async onCancel(data) {
  window.location.href = '/cancelado';
}
```

## onError

```ts
onError: (data) => Promise<void>
```

Erro na transação (evento `PAYMENT_ERROR` ou falha ao abrir o popup).

```js
async onError(error) {
  console.error('FaciPay error:', error);
  showToast('Ocorreu um erro. Tente novamente.', 'error');
}
```

## onInit

```ts
onInit: (actions) => Promise<void>
```

Botão inicializado. `actions` expõe `enable()` e `disable()`.

```js
async onInit(actions) {
  if (!cartIsValid) actions.disable();
}
```

## onClick

```ts
onClick: (data, actions) => Promise<void>
```

Disparado no clique, **antes** do `createOrder()`. `actions` expõe `enable()`, `disable()`
e `reject()`. Chamar `actions.reject()` **interrompe** o fluxo (o popup não abre) — ideal
para validar formulários.

<ResponseField name="actions.reject()" type="function">
  Interrompe a sequência do botão (cancela este clique).
</ResponseField>

```js
async onClick(data, actions) {
  const customer = validateCustomerForm();
  if (!customer) {
    actions.reject();          // cancela o fluxo deste clique
    return;
  }
  facipay.button.addCustomerInfo({ name: customer.name, phone: customer.phone });
}
```

<Card title="Próximo passo: Objeto Button" icon="arrow-right" href="/pt/sdk/button-object">
  render, destroy, referências, cliente e actions.
</Card>