Authorization
Use a server-side API key with the listed grants and permitted resource access.
payments:recordRequest headers
X-Api-Keyrequired- Your server-side integration credential.
Idempotency-Keyrequired- Stable key for this intended action. Reuse it for retries of the same request.
Content-Typeapplication/json- Encode the request body as JSON.
Path parameters
idstring · required- Opaque identifier in the authorized resource scope. Nested identifiers must belong to their parent resource.
Request body
amountstring · required- Decimal amount, never a floating-point total.
currencystring · required- ISO currency matching the invoice.
methodstring · required- A supported external settlement method. Cannot be Stripe.
externalPaymentReferencestring · required- Stable reference used to deduplicate settlement.
settledAtstring · required- Timestamp of the external settlement.
Response
201Created
Returns the authorized resource or result for this operation. List results use items, nextCursor, and hasMore.
Behavior to account for
Requires a separately approved settlement grant. Validates the invoice balance and duplicate external payment references. Do not report a Stripe payment through this route.
Errors
Authentication failures return 401 or 403. Inaccessible resources return 404. Business and idempotency conflicts return 409. Rate limits return 429 with retry guidance.
Error handling guide