PT EN

Pagamentos

URL base: $BUSINESS_API

O objecto

idstring · opcional
tenant_idstring · opcional
customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · opcional
account_numberstring · opcional

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

account_holder_namestring · opcional

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

invoice_idstring · opcional
amount_centsinteger · opcional
currencystring · opcional
receipt_numberstring · opcional
statusstring · opcional
paid_atstring (date-time) · opcional
O objecto
{
  "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"
}

Listar pagamentos

Registos

GET /payments

Does not initiate or process payment instruments.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Recorded payments in the authenticated utility tenant

Mostrar atributos
dataarray of RecordedPayment · obrigatório
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · opcional
account_numberstring · opcional

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

account_holder_namestring · opcional

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

invoice_idstring · opcional
amount_centsinteger · opcional
currencystring · opcional
receipt_numberstring · opcional
statusstring · opcional
paid_atstring (date-time) · opcional
has_moreboolean · obrigatório
next_cursorstring · opcional

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/payments" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Registar um pagamento

Registos

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.

Corpo application/json

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

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: 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"
}'
Resposta 200

Success

Registar o pagamento de uma factura

Registos

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.

Corpo application/json

customer_idstring · opcional
account_idstring · obrigatório
invoice_idstring · opcional
payment_session_idstring · opcional
provider_referencestring · opcional
amountinteger · obrigatório

Amount in minor units

currencystring · obrigatório
methodstring · obrigatório
confirmed_atstring (date-time) · opcional
idempotency_keystring · obrigatório

Devolve

200 The payment already recorded with this idempotency key

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: 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"
}'
Resposta 200

The payment already recorded with this idempotency key

Obter os metadados de um pagamento

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the payment, up to 120 characters.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

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

Actualizar os metadados de um pagamento

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the payment, up to 120 characters.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

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

Estornar um pagamento

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the payment to reverse.

Corpo application/json

reasonstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: 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."
}'
Resposta 200

Success

Obter o recibo para impressora térmica

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the payment whose receipt is printed.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Success

Anexar um comprovativo a um pagamento

Registos

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.

Devolve

201 Created

Permissões payments:read, payments:write · Funções: admin, billing_clerk, finance, owner

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

Created

Obter um pagamento

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Payment

Mostrar atributos
idstring · opcional
tenant_idstring · opcional
customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · opcional
account_numberstring · opcional

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

account_holder_namestring · opcional

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

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

Erros 400 · 401 · 403 · 404

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/payments/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}