PT EN

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"
}

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"
}

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"
}

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}'

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#