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_KEYcompayments: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. curlejq, ou qualquer cliente HTTP na linguagem em que vai escrever o conector.
1. Criar um código de registo#
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}'
{
"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"
}
2. Registar o conector#
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"}'
{
"connector_id": "pcn_2pQ3jB9sLf4XyT2nWc7MdZ1hKe8",
"session_token": "ctok_da8a5c19db60f3dad4680661bdc6682dc3925ce67f6e9683",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF"
}
3. Reservar a próxima tarefa#
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"]}'
{
"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"
}
4. Manter a reserva e comunicar o resultado#
A reserva dura 60 segundos. Enquanto o prestador ainda estiver a processar, renove-a:
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:
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}'
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.