# Receber pagamentos

Registe pagamentos confirmados fora da plataforma contra uma factura e saiba de todos os pagamentos, venham de onde vierem, pelos eventos payment.received e invoice.paid.


## O que vai construir

Um pagamento pode chegar por três caminhos: o morador paga numa sessão de checkout aberta pela Consumer API, um conector de pagamento comunica a confirmação do seu fornecedor, ou alguém confirma o dinheiro fora da plataforma (balcão, transferência, um sistema de cobrança próprio). A sua integração não precisa de saber qual foi: todos terminam num pagamento `posted`, com recibo, aplicado às facturas.

Neste guia vai registar o terceiro caso pela API, com `POST /payments/confirm`, e montar a confirmação de que todos dependem: o evento `payment.received` quando o pagamento fica registado e `invoice.paid` quando o saldo da factura chega a zero.

## Pré-requisitos

- Uma sandbox com pelo menos uma factura no estado `open`; o passo 1 encontra-a e, se a lista vier vazia, `gotactl events trigger invoice.issued` emite uma.
- Uma chave de API de teste com `invoices:read`, `payments:read` e `payments:write`.
- Um endpoint de webhook ou `gotactl webhooks listen` a correr (veja [Ouvir eventos com webhooks](/docs/guides/listen-webhooks)).

## 1. Encontrar uma factura em aberto

```bash
curl -sS "$BUSINESS_API/invoices?status=open&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` começa por `inv_`; anote `account_id`, `balance_cents` (o valor em dívida, em unidades mínimas da moeda) e `currency`.

## 2. Ver os métodos que a empresa aceita

Só se registam pagamentos num método que a empresa configurou e tem activo. A lista resulta dos canais de cobrança configurados e dos métodos declarados pelos conectores instalados; nada está fixo no código. Lê-se com `payments:read` ou `payments:write`.

```bash
curl -sS "$BUSINESS_API/payment-methods" \
  -H "Authorization: Bearer $API_KEY"
```

Exemplo de resposta:

```json
{
  "payments_active": true,
  "data": [
    {
      "code": "bank_transfer",
      "channel": "bank_transfer",
      "source": "channel",
      "requires_reference": true,
      "requires_phone": false,
      "requires_shift": false,
      "available": true
    }
  ]
}
```

✓ Checkpoint: `payments_active` é `true` e há pelo menos um método com `"available": true`. Use o seu `code` no passo seguinte e respeite `requires_reference`.

## 3. Registar o pagamento contra a factura

`amount` vai em unidades mínimas (centavos) e `idempotency_key` garante que uma nova tentativa não cria um segundo pagamento. `provider_reference` é a referência do banco, da carteira móvel ou do talão.

```bash
curl -sS -X POST "$BUSINESS_API/payments/confirm" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"act_3eQrF3JmTj2ZXpkFlbdO36UPXGP","invoice_id":"inv_3z9cS8ItYBqz0D66bvqNC7QSn8E","amount":185000,"currency":"MZN","method":"bank_transfer","provider_reference":"TRF-20261119-004812","confirmed_at":"2026-11-19T10:05:00Z","idempotency_key":"erp-cobranca-004812"}'
```

Resposta `201 Created`, resumida:

```json
{
  "id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz",
  "account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
  "invoice_id": "inv_3z9cS8ItYBqz0D66bvqNC7QSn8E",
  "amount_cents": 185000,
  "currency": "MZN",
  "method": "bank_transfer",
  "provider_reference": "TRF-20261119-004812",
  "receipt_number": "RCP-000058",
  "status": "posted",
  "paid_at": "2026-11-19T10:05:00Z"
}
```

✓ Checkpoint: `status` é `posted` e `receipt_number` vem preenchido. Repetir o pedido com a mesma `idempotency_key` devolve `200` com o mesmo `id`, sem novo pagamento.

## 4. Confirmar pela recepção do webhook

Não trate o pagamento como concluído só pela resposta HTTP: o mesmo evento chega também quando o pagamento vem de um checkout de morador ou de um conector, e é isso que permite tratar os três caminhos num único sítio. Subscreva `payment.received` e `invoice.paid`. O corpo de `payment.received` tem esta forma:

```json
{
  "id": "wev_3x6bknQybCmscpyDKTJXSdTOBT7",
  "type": "payment.received",
  "api_version": "v1",
  "tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
  "created_at": "2026-11-19T10:05:01Z",
  "data": {
    "resource_type": "payment",
    "resource_id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz",
    "attributes": {
      "invoice_id": "inv_3z9cS8ItYBqz0D66bvqNC7QSn8E",
      "customer_id": "cus_3Byj2A4oNoD4aVDMGLeWCWY5CWP",
      "account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
      "amount_cents": 185000,
      "currency": "MZN",
      "method": "bank_transfer",
      "receipt_number": "RCP-000058"
    },
    "resource": { "type": "payment", "id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz", "sequence": 1 }
  }
}
```

✓ Checkpoint: o seu receptor regista `payment.received` com o `resource_id` do passo 3 e, se o valor cobriu o saldo, um `invoice.paid` com `"status": "paid"` e `"balance_cents": 0` nos atributos.

## Testar

Sem criar nada à mão, `gotactl events trigger payment.received` regista um pagamento confirmado pelo conector simulado da sandbox, e `gotactl events trigger invoice.paid` emite e paga uma factura. Para ver os pagamentos, use `gotactl payments get pay_3dvlZQUZFQkYsjGOtWm37jocuyz` ou `gotactl payments list --limit 10`, ou abra **Pagamentos** no painel e escolha o pagamento para ver o número do recibo.

Recusas habituais: `400` com `error_code` `payment.method_not_configured` quando o método não está configurado ou activo; `403` com `capability.inactive` enquanto os pagamentos da empresa não estão activos; `400` com `validation.must_be_positive` para um `amount` igual ou inferior a zero.

## Próximos passos

- [Construir uma app para moradores com checkout de pagamento](/docs/guides/resident-app)
- [Ligar um conector de pagamento](/docs/guides/connect-connector)
- [Verificar a assinatura das entregas](/docs/webhooks/verify)
- [Emitir facturas e notas de crédito](/docs/guides/issue-invoices)

