Payment proofs

Base URL: $BUSINESS_API

List proofs of payment, such as those waiting for review

Logs

GET /payment-proofs

Returns one cursor-paginated page (limit, after) of the proofs of payment that customers sent to the tenant or staff attached to payments, for review. Requires the payments:read permission.

Parameters

statusstring · query · optional

Optional review status filter: pending, approved or rejected.

one of pending, approved, rejected

account_idstring · query · optional

Optional account ID; only proofs for that customer account are returned.

invoice_idstring · query · optional

Optional invoice ID; only proofs that reference that invoice are returned.

payment_idstring · query · optional

Optional payment ID; only proofs linked to that recorded payment are returned.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

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

curl -X GET "$BUSINESS_API/payment-proofs" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Get a proof of payment

Logs

GET /payment-proofs/{id}

Returns a proof's details: account, amount, method, reference, payment date, file metadata, review status and, once approved, the payment it produced. Requires the payments:read permission, and returns 404 when the proof is not in the tenant.

Returns

200 OK

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

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

OK

Download the proof file

Logs

GET /payment-proofs/{id}/file

Streams the uploaded proof file (PDF, JPEG or PNG) inline with its original file name, using no-store caching and a sandboxing Content-Security-Policy. Requires the payments:read permission. Returns 404 when the proof is not in the tenant or its file is no longer in storage.

Returns

200 The stored PDF, JPEG or PNG

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

curl -X GET "$BUSINESS_API/payment-proofs/{id}/file" \
  -H "Authorization: Bearer sk_test_..."
Response 200

The stored PDF, JPEG or PNG

Approve a proof

Logs

POST /payment-proofs/{id}/approve

Approve a proof: records the payment, optionally with the amount or reference the bank shows

Records the payment the proof describes and marks the proof approved. It returns both the proof and the payment result. The optional body can correct amount_minor or reference and add a review note (up to 500 characters). The payment is recorded with an idempotency key derived from the proof, so a retry never records it twice. A proof that was already reviewed returns 409. Requires the payments:write permission.

Body application/json

amount_minorinteger (int64) · optional
referencestring · optional
notestring · optional

Returns

200 The approved proof and the recorded payment

Errors 409

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

curl -X POST "$BUSINESS_API/payment-proofs/{id}/approve" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount_minor": 125000,
  "reference": "REF-2026-000142",
  "note": "Leitura confirmada no local."
}'
Response 200

The approved proof and the recorded payment

Reject a proof with a reason the payer will read

Logs

POST /payment-proofs/{id}/reject

Marks a pending proof as rejected without recording any payment and returns the proof. The body must include a reason (up to 500 characters), which is shown to the payer. A proof that was already reviewed returns 409. Requires the payments:write permission.

Body application/json

reasonstring · required

Returns

200 OK

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

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

OK