Payments

Base URL: $BUSINESS_API

The object

idstring · optional
tenant_idstring · optional
customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

invoice_idstring · optional
amount_centsinteger · optional
currencystring · optional
receipt_numberstring · optional
statusstring · optional
paid_atstring (date-time) · optional
The object
{
  "id": "rec_2J5AsFHUK5FY47ROaZ5MatNYqrz",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "amount_cents": 125000,
  "currency": "MZN",
  "receipt_number": "REC-2026-000142",
  "status": "active",
  "paid_at": "2026-11-19T09:30:00Z"
}

List recorded payment confirmations

Logs

GET /payments

Does not initiate or process payment instruments.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Recorded payments in the authenticated utility tenant

Show attributes
dataarray of RecordedPayment · required
Show child attributes
idstring · optional
tenant_idstring · optional
customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

invoice_idstring · optional
amount_centsinteger · optional
currencystring · optional
receipt_numberstring · optional
statusstring · optional
paid_atstring (date-time) · optional
has_moreboolean · required
next_cursorstring · optional

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

curl -X GET "$BUSINESS_API/payments" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "rec_2J5AsFHUK5FY47ROaZ5MatNYqrz",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
      "amount_cents": 125000,
      "currency": "MZN",
      "receipt_number": "REC-2026-000142",
      "status": "active",
      "paid_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Record payment

Logs

POST /payments

Record a payment and allocate it FIFO across unpaid invoices by due date; the remainder is held as unallocated credit

The method must be one the utility configured and has enabled (see GET $BUSINESS_API/payment-methods); any other is refused with 400 payment.method_not_configured.

Body application/json

account_idstring · optional
customer_idstring · optional
amount_minorinteger · optional
currencystring · optional
methodstring · optional
referencestring · optional
idempotency_keystring · optional
shift_idstring · optional
counter_idstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/payments" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "amount_minor": 125000,
  "currency": "MZN",
  "method": "method",
  "reference": "REF-2026-000142",
  "idempotency_key": "idempotency key",
  "shift_id": "shi_2YyDVSEZlsg7D4aHDGavnEgbPcU",
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk"
}'
Response 200

Success

Record a payment against a specific invoice

Logs

POST /payments/confirm

Records a payment confirmed outside the platform (counter, transfer, mobile money) and applies it to the invoice named in invoice_id. Repeating the same idempotency_key returns the original payment. The method must be one the utility configured and has enabled; any other is refused with payment.method_not_configured.

Body application/json

customer_idstring · optional
account_idstring · required
invoice_idstring · optional
payment_session_idstring · optional
provider_referencestring · optional
amountinteger · required

Amount in minor units

currencystring · required
methodstring · required
confirmed_atstring (date-time) · optional
idempotency_keystring · required

Returns

200 The payment already recorded with this idempotency key

Errors 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/payments/confirm" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "payment_session_id": "pay_2DxUipfYyfRuqNn2cZf00RTYqB3",
  "provider_reference": "PRO-2026-000142",
  "amount": 125000,
  "currency": "MZN",
  "method": "method",
  "confirmed_at": "2026-11-19T09:30:00Z",
  "idempotency_key": "idempotency key"
}'
Response 200

The payment already recorded with this idempotency key

Get the metadata of a payment

Logs

GET /payments/{id}/metadata

Returns the custom key/value metadata stored on a payment, as a metadata map that is empty when nothing is set. The payment must exist in the tenant (404 otherwise), and the caller needs the business:metadata:read permission.

Parameters

idstring · path · required

ID of the payment, up to 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/payments/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /payments/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the metadata map in the body into the payment's existing metadata and returns the full result. Keys not in the body are left alone, and a key sent with an empty string value is removed. At most 50 keys may be sent at once or stored in total. Keys can be up to 40 characters, with no square brackets or control characters, and values up to 500 characters; invalid fields return 400 with one entry per problem. Requires the business:metadata:write permission.

Parameters

idstring · path · required

ID of the payment, up to 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/payments/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Reverse a payment

Logs

POST /payments/{id}/reverse

Reverse a payment: restore invoice balances, undo allocations and mirror journal entries

Reverses a recorded payment, which needs a non-empty reason. Each invoice application is undone, the payment's allocations are reversed, a transition to reversed is recorded, and payment.reversed and allocation reversed events are emitted. When the payment came through a provider checkout, one refund job is queued for the connector. The call is idempotent: reversing an already reversed payment returns it unchanged, and a retry after a partial failure finishes the job. Requires the payments:write permission. Returns 409 when reversal is not configured and 503 when the refund cannot be queued.

Parameters

idstring · path · required

ID of the payment to reverse.

Body application/json

reasonstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/payments/{id}/reverse" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Success

80 mm ESC/POS thermal receipt

Logs

GET /payments/{id}/receipt/thermal

80 mm ESC/POS thermal receipt (application/vnd.escpos)

Returns the payment's receipt as ESC/POS printer commands for an 80 mm thermal printer. The response has content type application/vnd.escpos and is sent as an attachment named receipt-<id>.bin. The receipt uses the tenant's receipt profile and lists the invoices the payment was allocated to, plus any unallocated credit. Requires the payments:read permission.

Parameters

idstring · path · required

ID of the payment whose receipt is printed.

Returns

200 Success

Errors 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/payments/{id}/receipt/thermal" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Attach a proof file to a recorded payment

Logs

POST /payments/{id}/proof

Attach a proof file to a recorded payment (multipart: file)

Stores a staff-supplied file as evidence for a payment that has already been recorded, such as a slip a customer handed in at the office, and returns it with 201. Send it as multipart/form-data with a file field (PDF, JPEG or PNG, up to 5 MB by default). The proof copies the payment's account, amount, method and reference and is approved at once, because the payment already exists. Requires the payments:write permission, and an unknown payment returns 404.

Returns

201 Created

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

curl -X POST "$BUSINESS_API/payments/{id}/proof" \
  -H "Authorization: Bearer sk_test_..."
Response 201

Created

Get one recorded payment

Logs

GET /payments/{id}

Returns one payment recorded in the caller's tenant: amount in minor units, currency, method, the reference the payer or connector supplied, receipt number, status (posted, reconciled or reversed), payment time, the cashier shift and counter when it was taken at a counter, and reversal details when reversed. Account and customer references carry the holder's display name. Requires payments:read; an id that does not exist in the caller's tenant returns 404.

Parameters

idstring · path · required

Identifier of the payment, matched within the caller's tenant only.

Returns

200 Payment

Show attributes
idstring · optional
tenant_idstring · optional
customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

invoice_idstring · optional
amount_centsinteger · optional
currencystring · optional
receipt_numberstring · optional
statusstring · optional
paid_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/payments/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "rec_2J5AsFHUK5FY47ROaZ5MatNYqrz",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "amount_cents": 125000,
  "currency": "MZN",
  "receipt_number": "REC-2026-000142",
  "status": "active",
  "paid_at": "2026-11-19T09:30:00Z"
}