# generateButton()

Cria o botão de pagamento com callbacks e opções de aparência e pagamento.

`facipay.generateButton(params)` cria um botão de pagamento. Devolve um
[objeto Button](/pt/sdk/button-object) que renderiza com `.render()`.

```js
const button = facipay.generateButton({
  createOrder: async () => referenceNumber,
  onApprove: async (data, actions) => { /* ... */ },
  options: {
    style: { width: '100%', shape: 'pill' },
    config: { lang: 'pt', showAmount: true },
    paymentConfig: { theme: 'light', allowedPaymentMethods: ['FPMCXEXPRSS', 'FPSOLPG'] },
  },
});

button.render('#facipay-button-container');
```

## Callbacks

<ParamField path="createOrder" type="() => Promise<string>" required>
  Chamado antes de abrir o popup. Cria a ordem no seu backend e devolve o `referenceNumber`
  como **string não-vazia**. Detalhes em [Callbacks](/pt/sdk/callbacks).
</ParamField>

<ParamField path="onApprove" type="(data, actions) => Promise<void>">
  Pagamento aprovado (Multicaixa Express).
</ParamField>

<ParamField path="onPending" type="(data, actions) => Promise<void>">
  Pagamento pendente (Referência EMIS) — há uma referência a mostrar ao cliente.
</ParamField>

<ParamField path="onCancel" type="(data) => Promise<void>">
  Pagamento cancelado pelo utilizador.
</ParamField>

<ParamField path="onError" type="(error) => Promise<void>">
  Erro durante a transação.
</ParamField>

<ParamField path="onInit" type="(actions) => Promise<void>">
  O botão foi inicializado. `actions` permite `enable()` / `disable()`.
</ParamField>

<ParamField path="onClick" type="(data, actions) => Promise<void>">
  Clique no botão, antes do `createOrder()`. `actions` permite `enable()`, `disable()` e
  `reject()` (interrompe o fluxo). Útil para validar formulários.
</ParamField>

## options.style

<ParamField path="options.style.width" type="string | number">
  Largura do botão (ex.: `'100%'`, `320`). Default `'100%'`.
</ParamField>

<ParamField path="options.style.shape" type="'pill' | 'rect'">
  Forma do botão. Default `'pill'`.
</ParamField>

## options.config

<ParamField path="options.config.lang" type="'pt' | 'en'">
  Idioma do texto do botão e do checkout.
</ParamField>

<ParamField path="options.config.showAmount" type="boolean">
  Mostra o valor total no botão. Requer referências de pagamento (ver
  [Referências múltiplas](/pt/sdk/recipes/multiple-references)).
</ParamField>

## options.paymentConfig

<ParamField path="options.paymentConfig.theme" type="'light' | 'dark'">
  Tema do checkout.
</ParamField>

<ParamField path="options.paymentConfig.allowedPaymentMethods" type="string[]">
  Métodos visíveis no checkout. Default `['FPMCXEXPRSS', 'FPSOLPGEXT', 'FPSOLPG']`:
  - `FPMCXEXPRSS` — Multicaixa Express
  - `FPSOLPGEXT` — Referência EMIS
  - `FPSOLPG` — **Pagamento direto via FaciPay** (sempre disponível)

  <Note>
  O **pagamento direto via FaciPay** é sempre a opção padrão e **não pode ser desativado**.
  Ver [Métodos de pagamento](/pt/get-started/introduction#metodos-de-pagamento).
  </Note>
</ParamField>

<ParamField path="options.paymentConfig.defaultPaymentMethod" type="string">
  Método pré-selecionado no checkout. Default `'FPMCXEXPRSS'`.
</ParamField>

<ParamField path="options.paymentConfig.showUIOfProcessingInfo" type="boolean">
  Mostra a UI de progresso durante o processamento.
</ParamField>

<ParamField path="options.paymentConfig.referencePaymentLifeSpan" type="number">
  Validade da referência EMIS, em **minutos** (ex.: `1440` = 24h).
</ParamField>

<ParamField path="options.paymentConfig.customerInfo" type="object">
  Dados do cliente: `{ name, phone }`. Também pode defini-los em runtime com
  [`button.addCustomerInfo()`](/pt/sdk/button-object).
</ParamField>

## Exemplo completo

```js
facipay.generateButton({
  async createOrder() {
    const r = await fetch('/api/facipay/create-order', { method: 'POST' });
    const { referenceNumber } = await r.json();
    return referenceNumber;
  },
  async onApprove(data, actions) {
    actions.onPopupWindowClosed(() => {
      window.location.href = `/sucesso?orderId=${data.payment.orderId}`;
    });
  },
  async onPending(data, actions) {
    actions.onPopupWindowClosed(() => {
      const ref = data.payment.data.paymentReference;
      window.location.href = `/pendente?ref=${ref}`;
    });
  },
  async onCancel() { window.location.href = '/cancelado'; },
  async onError(e) { console.error(e); },
  options: {
    style: { width: '100%', shape: 'pill' },
    config: { lang: 'pt', showAmount: true },
    paymentConfig: {
      theme: 'light',
      allowedPaymentMethods: ['FPMCXEXPRSS', 'FPSOLPGEXT', 'FPSOLPG'],
      showUIOfProcessingInfo: true,
      referencePaymentLifeSpan: 1440,
    },
  },
}).render('#facipay-button-container');
```

<Card title="Próximo passo: Callbacks" icon="arrow-right" href="/pt/sdk/callbacks">
  Assinaturas e shapes de dados de cada callback.
</Card>