Server-to-server only. One endpoint for every payment you collect on your own
gateway instead of Oyster's: scans, appointment bookings, and any paid service added
later. You send the same request whatever the payment is for. The reference Oyster
issued tells it what was bought, and the response tells you what that was and what it
produced.
The widget hands the payment to your page's onCollectPayment handler with a
reference and a purpose. Collect however you like, then call this from your
server, from the hook that sees your order reach a paid state. This call is the
only thing that settles the payment: the browser can never admit a scan or book an
appointment by itself.
The flow:
- The widget receives
provider: vendor_gatewayand areference, and calls your
onCollectPayment. - Your page collects the payment.
- Your server calls this endpoint with that reference. A
successadmits the scan or
books the appointment immediately, whether or not the customer is still on the page. - The widget sees the change and continues.
Credentials. Your Oyster API key with the payments:collect scope. The WooCommerce
and Shopify connections carry it. A partner confirms for one of its businesses with its
partner API key and the business's slug in X-Vendor-Code. The widget's own session and
staff logins are refused with 403. The key is a payment credential: keep it on your
server.
Who collected. A partner whose businesses take some payments on their own gateway
says so with collected_by: business. Omit it, or send platform, when the payment
landed on the partner's gateway. For a booking the business collected, the business
holds the money and owes the commission: it is taken from the business's wallet or put
on its monthly invoice, as the partner chose, and the partner's share reaches the
partner's wallet once it is paid. A business that is not managed by a partner always
collects its own payments, and collected_by is ignored.
The amount is advisory. You charge whatever you charge. Oyster records what you
report and never validates it.
Retries are safe. Confirming a payment already settled returns replayed: true
with the existing outcome and changes nothing: one collection never becomes two scans
or two bookings. Treat replayed: true as success.
Failures matter. Send failed when the customer abandons or the charge declines,
so the widget tells them at once instead of waiting out its timeout. A booking's slot is
released straight away. A later success for the same reference still counts.
Migrating. This replaces POST /scan-payments/{reference}/external/confirm and
POST /consultation/appointments/reservations/{reference}/external/confirm. Point your
confirmation at this path and read data.status as success or failed; nothing else
about the request changes. Keys holding the old scans:collect or
appointments:collect scope were given payments:collect automatically.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||