Confirm a booking payment collected on the vendor's own gateway

Deprecated. Use POST /payments/{reference}/external/confirm, which takes every
payment type with the same request. This endpoint answers unchanged until its sunset
date, sent in the Sunset response header, and then stops.

Server-to-server only. For clinics that collect widget booking payments through
their own gateway. Their reservation response carries provider: vendor_gateway
and an external_collection block, and the widget hands the payment to your page's
onCollectPayment handler with purpose: appointment.

This is the ONLY thing that books such an appointment. Call it from your server,
from the hook that sees your order reach a paid state. It needs your Oyster API key
with the payments:collect scope (the WooCommerce and Shopify connections carry
it). The widget's own session is refused, so nothing in the browser can book an
appointment without your confirmation.

The flow:

  1. The widget reserves the slot and receives provider: vendor_gateway, a
    reference, the total and its line_items.
  2. Your page collects payment however you like.
  3. Your server calls this endpoint with that reference. A success books the
    appointment immediately, whether or not the customer is still on the page.
  4. The widget, polling the reservation's status, sees confirmed and continues.

Billing. The appointment fee is yours and Oyster takes none of it. The scan
taken for the booking is invoiced to you at your scan rate.

The amount is advisory. You charge whatever you charge; Oyster records what you
report and never validates it.

Retries are safe. Confirming a booked reservation returns replayed: true with
the appointment it already made. Treat replayed: true as success.

Partners. When Oyster has switched on partner collection for your account, your
vendors' widget bookings come to your onCollectPayment handler. Confirm them with your
partner API key holding payments:collect, naming the vendor in X-Vendor-Code.
A partner staff login is refused. Oyster moves no money for these bookings: it records
the gross amount, both cuts stamped when the slot was reserved and your
external_reference, and they appear on your settlement statement
(GET /partner/settlements). Oyster's cut is added to your next invoice (the monthly one, or on a plan the invoice issued when each cycle starts). You pay
your vendors their net yourself. Exit-mode vendors always stay on Oyster collection.

Failures matter. Send failed when the customer abandons or the charge declines:
the slot is released at once and the widget stops waiting. A later success for the
same reference still books the appointment.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The reference returned by POST /consultation/appointments/reserve.

Body Params
string
enum
required
Allowed:
string | null

Your own identifier for the collection (order id, checkout id). Stored for reconciliation.

float | null

What you actually charged. Advisory; recorded, never validated.

string | null
string | null
enum

Only with status: failed. payment_method_not_accepted: the customer chose a pay-later method such as cash on delivery, so the order will never be paid. The widget asks them to pay online instead of showing a plain failure.

Allowed:
Headers
string

Partner keys only. The slug of the vendor whose booking you collected.

Responses

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json