# Ligar um conector de pagamento

Construa um conector de pagamento sobre a Connector API, desde o código de registo até ao registo, à reserva de cobranças, aos sinais de vida, ao resultado e aos pagamentos vistos fora de uma tarefa.


## O que vai construir

Um pequeno processo que corre junto de um prestador de pagamentos e faz o trabalho específico desse prestador, que o núcleo nunca faz. O núcleo não tem código de prestadores: quando um morador paga por M-Pesa, a API põe uma tarefa em fila, o conector reserva-a, pede a cobrança ao prestador e comunica o resultado. É sempre o conector que faz as chamadas, por isso não precisa de endereço público nem de regras de firewall para tráfego de entrada. Os conectores de mensagens em `$CONNECTOR_API/communications` seguem o mesmo ciclo de reserva, sinal de vida e conclusão; este guia usa pagamentos.

## Pré-requisitos

- Uma sandbox e uma chave de API de teste em `$API_KEY` com `payments:write`, usada apenas para criar o código de registo no passo 1. A Connector API nunca aceita chaves de API.
- Os métodos de pagamento que o conector consegue concluir, escritos como a API os designa, por exemplo `mpesa`.
- `curl` e `jq`, ou qualquer cliente HTTP na linguagem em que vai escrever o conector.

## 1. Criar um código de registo

```bash
curl -sS -X POST "$BUSINESS_API/payment-connectors/enrollment-tokens" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"mpesa-gateway-01","max_uses":1,"valid_duration_seconds":86400}'
```

```json
{
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "id": "etk_2pQ3hW7nKc1VxR8mTb5LzY4gJd6",
  "token": "enr_ebfe57417a5b4de21e99c034115da6ef066efcd4395071d0",
  "name": "mpesa-gateway-01",
  "max_uses": 1,
  "uses_count": 0,
  "expires_at": "2026-11-20T11:20:00Z",
  "created_at": "2026-11-19T11:20:00Z"
}
```

✓ Checkpoint: `token` começa por `enr_` e só aparece nesta resposta; a API guarda apenas o respectivo hash. `max_uses` igual a `0` significa sem limite, e sem `valid_duration_seconds` o código dura 30 dias. No painel, **Definições** > **Conectores de pagamento** > **Novo conector** e **Gerar código** produzem o mesmo código.

## 2. Registar o conector

```bash
curl -sS -X POST "$CONNECTOR_API/payments/registrations" \
  -H "Content-Type: application/json" \
  -d '{"token":"enr_ebfe57417a5b4de21e99c034115da6ef066efcd4395071d0","name":"mpesa-gateway-01","supported_methods":["mpesa"],"operational_methods":["mpesa"],"currency":"MZN","hostname":"pay-gw-01","agent_version":"1.4.0"}'
```

```json
{
  "connector_id": "pcn_2pQ3jB9sLf4XyT2nWc7MdZ1hKe8",
  "session_token": "ctok_da8a5c19db60f3dad4680661bdc6682dc3925ce67f6e9683",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF"
}
```

✓ Checkpoint: `201` com um `session_token` que começa por `ctok_`. Guarde-o como segredo; todas as chamadas seguintes o enviam em `Authorization: Bearer`, `Authorization: Token` ou `X-Connector-Token`. Um código expirado, esgotado ou desconhecido devolve `400`. `operational_methods` só mantém os métodos que também constam de `supported_methods`, e os moradores só vêem no pagamento os métodos que um conector activo declara.

## 3. Reservar a próxima tarefa

```bash
curl -sS -X POST "$CONNECTOR_API/payments/jobs/request" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wait_timeout_seconds":50,"operational_methods":["mpesa"]}'
```

```json
{
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "id": "pjb_2pQ4aN6vHt3ZkR9xLm1CwB5yFg7",
  "connector_id": "pcn_2pQ3jB9sLf4XyT2nWc7MdZ1hKe8",
  "action": "collect_push",
  "status": "leased",
  "amount_minor": 100000,
  "currency": "MZN",
  "payment_method": "mpesa",
  "payer_identifier": "+258841234567",
  "reference_id": "pss_2pQ4bR2wJk8YmT5nXc3DvL7zHa1",
  "lease_timeout_seconds": 60,
  "lease_expires_at": "2026-11-19T11:31:12Z",
  "created_at": "2026-11-19T11:30:09Z"
}
```

✓ Checkpoint: `200` com `status: "leased"`, ou `204` sem corpo quando nada chegou dentro de `wait_timeout_seconds` (no máximo 50). Repita esta chamada em ciclo. `action` vale `collect_push` numa cobrança e `refund` num reembolso.

## 4. Manter a reserva e comunicar o resultado

A reserva dura 60 segundos. Enquanto o prestador ainda estiver a processar, renove-a:

```bash
curl -sS -X POST "$CONNECTOR_API/payments/jobs/pjb_2pQ4aN6vHt3ZkR9xLm1CwB5yFg7/heartbeat" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

Quando o prestador responder, envie `status` com `succeeded` ou `failed`:

```bash
curl -sS -X POST "$CONNECTOR_API/payments/jobs/pjb_2pQ4aN6vHt3ZkR9xLm1CwB5yFg7/complete" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","provider_transaction_id":"QK71HX2P9D","fee_minor":0}'
```

✓ Checkpoint: o sinal de vida devolve `{"status":"ok"}` e a conclusão devolve `{"status":"completed"}`. Uma cobrança bem-sucedida regista o pagamento e o recibo e imputa-o à factura; uma falha marca como falhada a sessão que ainda estiver pendente. A liquidação é idempotente, por isso repetir a chamada depois de um erro de rede é seguro. Um sinal de vida para uma tarefa que este conector já não tem como `leased` devolve `404`. Concluir uma tarefa que já não está `leased` devolve `409`, e concluir uma tarefa reservada por outro conector devolve `401`.

## Testar

Em **Definições** > **Conectores de pagamento**, o conector aparece em **Conectores registados** como **Em linha** enquanto consulta a fila e **A processar** enquanto tem uma tarefa. O conector também comunica pagamentos que observa por conta própria, como um pagamento feito num agente, através de `POST $CONNECTOR_API/payments/events` com `provider_transaction_id`, um `amount_minor` positivo e o `account_number` de uma conta da sandbox. Ponha antes `gotactl webhooks listen --events payment.received --forward-to http://localhost:3000/hooks` à escuta e o pagamento lançado aparece como `--> payment.received`. Enviar o mesmo evento outra vez não lança o pagamento em duplicado.

## Próximos passos

- [Iniciar um pagamento que o conector vai cobrar](/docs/guides/receive-payments)
- [Reagir a payment.received no seu próprio sistema](/docs/guides/listen-webhooks)
- [Todas as operações da Connector API](/docs/api/connector)

