# Introdução

Explore os nossos guias e exemplos de integração com o FaciConnect.

A **FaciConnect** é a plataforma que liga a sua aplicação ao **FaciPay**, o sistema de
pagamentos para Angola (moeda **AOA**). Com uma SDK de browser e uma API de parceiros,
aceita pagamentos por **Multicaixa Express**, **Referência EMIS** e **FaciPay**
(solicitação de pagamento) sem reconstruir o seu checkout.

<CardGroup cols={2}>
  <Card title="Início rápido" icon="rocket" href="/pt/get-started/quickstart">
    Do zero ao primeiro pagamento em sandbox em ~10 minutos.
  </Card>
  <Card title="FaciPay JS SDK" icon="js" href="/pt/sdk/overview">
    O botão de pagamento, callbacks e referência completa.
  </Card>
  <Card title="API Reference" icon="code" href="/pt/api-reference/introduction">
    Endpoints de token, ordens e webhooks.
  </Card>
  <Card title="Integração de referência" icon="store" href="/pt/get-started/sample-integration">
    Uma loja completa (Express + SQLite) ponta a ponta.
  </Card>
</CardGroup>

## Como funciona um pagamento

A FaciConnect combina três peças: a **SDK no frontend** (renderiza o botão e abre o popup),
a **sua API no backend** (cria a ordem e recebe o webhook) e a **FaciPay** (processa o pagamento).

```mermaid
sequenceDiagram
    participant U as Cliente
    participant F as Frontend (SDK)
    participant B as Backend (parceiro)
    participant P as FaciPay

    U->>F: Clica em "Pagar Agora"
    F->>B: createOrder()
    B->>P: POST /facipaypartner/createPaymentOrder
    P-->>B: referenceNumber
    B-->>F: referenceNumber
    F->>P: Abre popup de pagamento
    U->>P: Confirma o pagamento
    P-->>F: onApprove / onPending / onCancel
    P->>B: Webhook (fonte da verdade)
    B-->>B: Atualiza a ordem (CON/CAN)
```

<Note>
O **webhook é a fonte da verdade** do estado do pagamento — não os callbacks do frontend.
Os callbacks servem para a experiência do utilizador (redirecionar, mostrar referência);
a confirmação definitiva vem do webhook no seu backend.
</Note>

## Métodos de pagamento

| Método | Código | Notas |
|---|---|---|
| **Multicaixa Express** | `FPMCXEXPRSS` | Confirmação imediata na app Multicaixa Express → `onApprove`. |
| **Referência EMIS** | `FPSOLPGEXT` | Entidade + referência pagas no Multicaixa/homebanking → `onPending`. |
| **FaciPay** (solicitação de pagamento) | `FPSOLPG` | Carteira FaciPay — envia uma solicitação de pagamento à carteira do cliente → `onApprove`. |

No **FaciPay**, depois de o cliente informar o telemóvel associado à conta FaciPay, é
efetuada uma **solicitação de pagamento** na carteira, permitindo-lhe concluir o pagamento.

Na configuração `allowedPaymentMethods` pode esconder o Multicaixa Express e a Referência
EMIS, mas o **FaciPay direto** permanece sempre visível.

## Regras essenciais

<Warning>
- Moeda **AOA**, locale **pt-AO**. O `amount` é **inteiro, sem casas decimais** (ex.: `15000` = 15.000 Kz).
- O total é **sempre recalculado no servidor** — nunca confie no valor enviado pelo cliente.
- O `createOrder()` da SDK **tem** de devolver uma string não-vazia (o `referenceNumber`).
- Em produção, a SDK só funciona sobre **HTTPS**.
</Warning>

## Acesso e credenciais

<Note>
**Como obter as credenciais.** As chaves (`pk_…`, `clientId`, `clientSecret`, `webhookSecret`)
são emitidas pela FaciPay após abrir uma **conta de negócio** e assinar contrato com a
área comercial da **Faci-X**. Para começar, fale connosco: 📞 +244 923 168 670 · ✉️ [atendimento@faci-x.ao](mailto:atendimento@faci-x.ao).
</Note>

## Âmbito

Esta documentação cobre a integração **web** — frontend num browser (Next.js, React, Vue, HTML puro…)
mais um backend HTTP. Para outras plataformas há secções dedicadas: **[Android SDK](/pt/android/overview)**,
**[iOS SDK](/pt/ios/overview)** e **[WooCommerce](/pt/woocommerce/overview)**.

Ainda **não** cobrimos React Native, Flutter nem outros plugins de CMS/e-commerce (Shopify, WordPress sem
WooCommerce) — para esses, [fale com o suporte](mailto:atendimento@faci-x.ao).

<Card title="Próximo passo: Início rápido" icon="arrow-right" href="/pt/get-started/quickstart">
  Aceite o seu primeiro pagamento em sandbox.
</Card>