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.issuedemite uma. - Uma chave de API de teste com
invoices:read,payments:readepayments:write. - Um endpoint de webhook ou
gotactl webhooks listena correr (veja Ouvir eventos com webhooks).
1. Encontrar uma factura em aberto#
curl -sS "$BUSINESS_API/invoices?status=open&limit=1" \
-H "Authorization: Bearer $API_KEY"
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.
curl -sS "$BUSINESS_API/payment-methods" \
-H "Authorization: Bearer $API_KEY"
Exemplo de resposta:
{
"payments_active": true,
"data": [
{
"code": "bank_transfer",
"channel": "bank_transfer",
"source": "channel",
"requires_reference": true,
"requires_phone": false,
"requires_shift": false,
"available": true
}
]
}
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.
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:
{
"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"
}
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:
{
"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 }
}
}
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.