Connect a payment connector

Build a payment connector against the Connector API, from the enrollment code to registration, leasing collection jobs, heartbeats, reporting the outcome and posting payments seen outside a job.

What you will build#

A small process that runs next to a payment provider and does the provider-specific work the core never does. The core holds no provider code: when a resident pays by M-Pesa, the API queues a job, and your connector leases it, asks the provider to collect, and reports the result. The connector always makes the calls, so it needs no public address and no inbound firewall rule. Messaging connectors under $CONNECTOR_API/communications follow the same lease, heartbeat and complete cycle; this guide uses payments.

Prerequisites#

  • A sandbox and a test API key in $API_KEY with payments:write, used only to create the enrollment code in step 1. The Connector API itself never takes an API key.
  • The payment methods your connector can complete, written as the API names them, for example mpesa.
  • curl and jq, or any HTTP client in the language you will write the connector in.

1. Create an enrollment code#

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. Register the connector#

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. Lease the next job#

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. Keep the lease and report the outcome#

The lease lasts 60 seconds. While the provider is still working, renew it:

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

When the provider answers, send status succeeded or 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}'

Test it#

Under Settings > Payment connectors, the connector appears in Registered connectors as Online while it polls and Processing while it holds a job. A connector also reports payments it sees on its own, such as a payment made at an agent, through POST $CONNECTOR_API/payments/events with provider_transaction_id, a positive amount_minor and the account_number of a sandbox account. Run gotactl webhooks listen --events payment.received --forward-to http://localhost:3000/hooks first and the posted payment shows up as --> payment.received. Sending the same event again does not post it twice.

Next steps#