# BitPay

> BitPay é um gateway de pagamentos para Angola: uma API REST/JSON para receber por Multicaixa Express e Referências Multicaixa, com links de pagamento, checkout hospedado, QR e webhooks assinados. A BitPay ainda NÃO está em produção (aguarda a certificação da EMIS): hoje só existe o sandbox em https://api-sandbox.bitpay.ao/v1, onde nenhum pagamento é real.

Regras essenciais para integrar sem erros:

- Base URL: `https://api-sandbox.bitpay.ao/v1`. Autenticação: `Authorization: Bearer sk_test_…`.
- Chave imediata e sem autenticação: `POST /v1/sandbox/accounts` devolve `sk` e `pk`.
- Envia sempre `Content-Type: application/json` nos pedidos com corpo.
- `POST /payment_intents` e `POST /refunds` exigem o header `Idempotency-Key` (8–128 caracteres).
- `amount` é um inteiro em kwanzas (`currency: "AOA"`), com mínimo de 100.
- Números de teste Multicaixa Express:

  | Número | Resultado |
  |---|---|
  | 923000000 | aprovado |
  | 923000001 | rejeitado |
  | 923000002 | UNKNOWN → sucesso tardio |
  | 923000003 | saldo insuficiente |
  | 923000004 | operador indisponível |

- Entrega a encomenda no evento `payment.succeeded`, uma única vez por `data.id`. O `payment.reconciled` é informativo.
- Webhooks: `BitPay-Signature: t=<unix>,v1=<hex>`, com `v1 = HMAC-SHA256("<t>.<corpo cru>", whsec_…)`; rejeita se a diferença para `t` passar de 600 s.
- Limite: 120 pedidos/min por chave; em `429`, espera os segundos de `Retry-After`.

## Documentação

- [Guia completo para assistentes de IA](https://developers.bitpay.ao/llms-full.txt): tudo num ficheiro, com todos os endpoints, `curl` executáveis, estados, eventos, erros e verificação de webhooks em Node, PHP e Python.
- [Especificação OpenAPI 3.1 (YAML)](https://developers.bitpay.ao/openapi.yaml): contrato completo da API v1 do sandbox.
- [Especificação OpenAPI 3.1 (JSON)](https://developers.bitpay.ao/openapi.json): o mesmo contrato em JSON.
- [Referência da API](https://developers.bitpay.ao/api): referência navegável, com exemplos.
- [Portal de developers](https://developers.bitpay.ao): quickstart, sandbox e downloads.

## SDKs (zip, sem gestor de pacotes por agora)

- [Node.js 18+](https://developers.bitpay.ao/downloads/bitpay-sdk-node-0.1.1.zip): ESM, zero dependências.
- [Python 3.9+](https://developers.bitpay.ao/downloads/bitpay-sdk-python-0.1.1.zip): só stdlib.
- [PHP 8.0+](https://developers.bitpay.ao/downloads/bitpay-sdk-php-0.1.1.zip): ext-curl.
- [Java 17+](https://developers.bitpay.ao/downloads/bitpay-sdk-java-0.1.1.zip): java.net.http.
- [Dart/Flutter (backend)](https://developers.bitpay.ao/downloads/bitpay-sdk-flutter-0.1.1.zip): package crypto.
- [Plugin WooCommerce](https://developers.bitpay.ao/downloads/bitpay-for-woocommerce-0.1.1.zip): checkout hospedado e webhooks automáticos.

## Optional

- [Estado dos serviços](https://status.bitpay.ao)
- [Painel do comerciante](https://dashboard.bitpay.ao): criar conta com login, chaves, webhooks e logs.
- [Preços](https://bitpay.ao/precos)