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

✓ Checkpoint: `token` starts with `enr_` and appears in this response only; the API keeps just its hash. `max_uses` of `0` means unlimited, and without `valid_duration_seconds` the code lasts 30 days. In the dashboard, **Settings** > **Payment connectors** > **New connector** and **Generate code** produce the same code.

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

✓ Checkpoint: `201` with a `session_token` that starts with `ctok_`. Store it as a secret; every later call sends it as `Authorization: Bearer`, `Authorization: Token` or `X-Connector-Token`. An expired, exhausted or unknown code returns `400`. `operational_methods` only keeps methods that are also in `supported_methods`, and checkouts are offered to residents only for methods a live connector declares.

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

✓ Checkpoint: `200` with `status: "leased"`, or `204` with no body when nothing arrived within `wait_timeout_seconds` (capped at 50). Loop on this call. `action` is `collect_push` for a collection or `refund` for a refund.

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

✓ Checkpoint: heartbeat returns `{"status":"ok"}` and complete returns `{"status":"completed"}`. A successful collection records the payment and its receipt and allocates it to the invoice; a failure marks a still-pending session as failed. Settlement is idempotent, so retrying after a network error is safe. A heartbeat for a job this connector no longer holds as `leased` returns `404`. Completing a job that is no longer `leased` returns `409`, and completing one leased to a different connector returns `401`.

## 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

- [Start a checkout that your connector will collect](/docs/guides/receive-payments)
- [React to payment.received in your own system](/docs/guides/listen-webhooks)
- [Every Connector API operation](/docs/api/connector)

