Payments

Base URL: $CONNECTOR_API

Register payment connector

Logs

POST /payments/registrations

Exchange a payment enrollment token for a connector session token

The token binds the session to one tenant. A request may assert tenant_id, and is refused when it differs from the token's tenant. operational_methods lists the supported methods the connector can actually complete; a skeleton provider declares none.

Body application/json

tokenstring · required

One-time payment connector enrollment token

namestring · optional
supported_methodsarray of string · optional
operational_methodsarray of string · optional
currencystring · optional
hostnamestring · optional
agent_versionstring · optional
tenant_idstring · optional

Returns

201 Connector registered

Errors 400

curl -X POST "$CONNECTOR_API/payments/registrations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "name": "Ana Matsinhe",
  "supported_methods": [
    "supported method"
  ],
  "operational_methods": [
    "operational method"
  ],
  "currency": "MZN",
  "hostname": "hostname",
  "agent_version": "agent version",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6"
}'
Response 201

Connector registered

Request payment job

Logs

POST /payments/jobs/request

Long-poll for the next payment job and refresh the operational_methods declaration

Leases the next pending payment job (a collection or a refund) for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered. Set wait_timeout_seconds (capped at 50) to long-poll: the call waits for a new job and returns 204 No Content when none arrives in time. A leased job is held for 60 seconds and must be kept alive with the heartbeat call; the body can also declare which registered methods are currently operational, which controls what consumers are offered at checkout.

Returns

200 A leased job for the connector's tenant

Errors 401

curl -X POST "$CONNECTOR_API/payments/jobs/request" \
  -H "Authorization: Bearer sk_test_..."
Response 200

A leased job for the connector's tenant

Renew a job lease

Logs

POST /payments/jobs/{id}/heartbeat

Extends the lease on a job the calling connector holds by another 60 seconds and marks the connector busy. Call it while a payment is still in progress so the job is not handed to another connector. Returns 404 when the job does not exist, is not leased by this connector or has already been completed.

Parameters

idstring · path · required

Identifier of the leased payment job (prefixed pjb_) whose lease should be extended.

Returns

200 Lease renewed

Errors 404

curl -X POST "$CONNECTOR_API/payments/jobs/{id}/heartbeat" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Lease renewed

Report a payment job outcome

Logs

POST /payments/jobs/{id}/complete

Reports the outcome of a job the calling connector holds; status must be succeeded or failed. For a collection, success confirms the payment against its payment session (recording the payment, receipt and invoice allocation) and failure marks a still-pending session as failed; a refund's outcome is only stored on the job. Settlement runs before the job closes and every step is idempotent, so retrying after an error is safe. Returns 404 for an unknown job, 401 when another connector holds it, and 409 when the job is no longer leased.

Parameters

idstring · path · required

Identifier of the leased payment job (prefixed pjb_) returned by the job request call.

Returns

200 Outcome recorded

Errors 409

curl -X POST "$CONNECTOR_API/payments/jobs/{id}/complete" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Outcome recorded

Report an unprompted customer payment

Logs

POST /payments/events

Records a settled payment that a payment connector observed on its own, such as a customer paying at an agent or from a phone menu, without a prior payment job. The connector authenticates with its connector token (Authorization Bearer or Token, or X-Connector-Token); provider_transaction_id and a positive amount_minor are required, and the payment is matched to the tenant's account by account_number, with settled_at defaulting to now. Confirmation is idempotent on the provider transaction and event_id, so a repeated event does not post the payment twice. Returns 401 for an unknown token and 403 when the tenant is suspended or closed.

Returns

200 Event ingested

Errors 400

curl -X POST "$CONNECTOR_API/payments/events" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Event ingested

Long-poll for the next payment job

Logs

POST /payments/request

Long-poll for the next payment job (older path)

Older path for the payment job request; it runs the same handler as $CONNECTOR_API/payments/jobs/request and behaves identically, so new connectors should call that path instead. Leases the next pending payment job for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered, and can refresh the connector's operational methods. Set wait_timeout_seconds (capped at 50) to long-poll; 204 means no job arrived in time. The connector session token is accepted as Authorization Bearer or Token, or in the X-Connector-Token header.

Body application/json

supported_methodsarray of string · optional

Methods to lease jobs for; defaults to the methods the connector registered.

operational_methodsarray of string · optional

When present, replaces the connector's declaration of which registered methods are operational now (methods it did not register are dropped). Absent leaves the declaration unchanged; an empty list declares none operational.

currencystring · optional

Currency to lease jobs for; defaults to the connector's registered currency.

wait_timeout_secondsinteger · optional

Seconds to wait for a job before answering 204; values above 50 are capped and negative values mean no wait.

Returns

200 A leased job for the connector's tenant

Errors 401 · 403

curl -X POST "$CONNECTOR_API/payments/request" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "supported_methods": [
    "supported method"
  ],
  "operational_methods": [
    "operational method"
  ],
  "currency": "MZN",
  "wait_timeout_seconds": 0
}'
Response 200

A leased job for the connector's tenant