Payment connectors

Base URL: $BUSINESS_API

The object

connectorsarray of object · required
Show child attributes
tenant_idstring · required
idstring · required
namestring · required
supported_methodsarray of string · required
operational_methodsarray of string · required
currencystring · required
hostnamestring · optional
agent_versionstring · optional
statusstring · required

one of online, busy, offline, decommissioned, revoked

modestring · optional

one of pull, push

last_heartbeat_atstring · optional · nullable
has_moreboolean · required
next_cursorstring · optional
The object
{
  "connectors": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
      "name": "Ana Matsinhe",
      "supported_methods": [
        "supported method"
      ],
      "operational_methods": [
        "operational method"
      ],
      "currency": "MZN",
      "hostname": "hostname",
      "agent_version": "agent version",
      "status": "online",
      "mode": "pull",
      "last_heartbeat_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create payment enrollment token

Logs

POST /payment-connectors/enrollment-tokens

Issue a payment connector enrollment token for the caller's tenant, returned once

Creates a one-time-visible enrollment token (prefixed enr_) that a payment connector exchanges to register itself with this tenant, and returns it with 201. The raw token is in the response only; just its hash is stored. The body takes an optional name (defaults to "default"), max_uses (0 means unlimited) and valid_duration_seconds (defaults to 30 days). Requires the payments:write permission.

Body application/json

namestring · optional
max_usesinteger · optional
valid_duration_secondsinteger · optional

Returns

201 Token issued

Show attributes
tenant_idstring · required
idstring · required
tokenstring · required

Returned once; store securely before closing the dialog

namestring · required
max_usesinteger · required
uses_countinteger · required
expires_atstring (date-time) · required
created_atstring (date-time) · required

Errors 400 · 403

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/payment-connectors/enrollment-tokens" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "max_uses": 1,
  "valid_duration_seconds": 1
}'
Response 201
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
  "token": "token",
  "name": "Ana Matsinhe",
  "max_uses": 1,
  "uses_count": 1,
  "expires_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

List payment connectors

Logs

GET /payment-connectors

List the tenant's payment connectors with their mode and operational_methods

Returns the payment connectors registered for the tenant, sorted by ID, in a response with connectors, has_more and next_cursor. Paging uses limit and an after cursor, and a malformed cursor returns 400. Requires the payments:read permission.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Connectors

Show attributes
connectorsarray of object · required
Show child attributes
tenant_idstring · required
idstring · required
namestring · required
supported_methodsarray of string · required
operational_methodsarray of string · required
currencystring · required
hostnamestring · optional
agent_versionstring · optional
statusstring · required

one of online, busy, offline, decommissioned, revoked

modestring · optional

one of pull, push

last_heartbeat_atstring · optional · nullable
has_moreboolean · required
next_cursorstring · optional

Errors 403

Permissions payments:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/payment-connectors" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "connectors": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
      "name": "Ana Matsinhe",
      "supported_methods": [
        "supported method"
      ],
      "operational_methods": [
        "operational method"
      ],
      "currency": "MZN",
      "hostname": "hostname",
      "agent_version": "agent version",
      "status": "online",
      "mode": "pull",
      "last_heartbeat_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Remove a payment connector

Logs

DELETE /payment-connectors/{id}

Removes the connector registration from the tenant, so it can no longer pick up payment jobs for this tenant, and returns 204. The delete is idempotent: an unknown ID also returns 204. Requires the payments:write permission.

Parameters

idstring · path · required

ID of the registered payment connector (prefixed pcn_).

Returns

204 Removed

Errors 403

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X DELETE "$BUSINESS_API/payment-connectors/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Removed