Records a payment that you already collected outside AgendaPro (for example, on your own card terminal) against a cart. AgendaPro creates the sale, or updates it for a partial payment, as for a payment at the front desk. The response is the recorded transaction, the same object GET /v3/sales/{id} lists in transactions[].

Important Notes

• Requires carts:write scope.
• Not processed by AgendaPro. The payment does not go through the AgendaPro checkout: there is no fee and no settlement.
• payment_method is { id, type }, copied from an element of GET /v3/payment_methods. It is the same shape as payment_method in GET /v3/sales/{id}. Ids differ between companies and between environments (staging and production): always read them from GET /v3/payment_methods, never write them into your code.
• external_reference is required. Send the reference of the payment in your system. Sending the same external_reference again for the same cart, with the same amount, tip and payment method, returns the payment already recorded with 200 and creates nothing.
• Retry after a timeout. If you get 502 upstream_unavailable, the payment may still have been recorded. Retry with the same external_reference: you get either the recorded payment (200) or a new one (201), never a duplicate.
• Partial payments. An amount below the pending amount leaves the sale partially_paid. Another call pays the rest, with any payment method.
• paid_at is optional and defaults to now. It must be an ISO 8601 timestamp with a time zone (Z or ±hh:mm).
• Pending online payment. If the cart has a pending payment request (for example, an online checkout from POST /v3/carts/{id}/payment_requests), this call returns 409 pending_payment_request, because the customer could be paying it. Cancel it first with PATCH /v3/payment_requests/{id}/cancel.
• On-demand bookings. Your terminal collects the payment before this call, so if a cart item books a service on the fly (reference_id: null), its time slot could be taken by then. To avoid that, create the booking first with POST /v3/bookings and add it to the cart by reference_id.
• Business errors proxied from platform-sales use legacy single-key codes (for example cart_not_found, amount_exceeds_pending), not the {error, detail} shape.
• No webhook is sent for these payments: the response of this call is the confirmation.

Errors Dictionary