Confirm a payment
Settle an online booking when the patient comes back from the gateway.
POST /v1/appointments/confirm-paymentsThe other half of reserve-slot.
Medos reads the payment at the gateway and, if the money landed, stamps the
booking PAID — activating the pack, if the booking was a pack purchase.
It is not OTP-gated: the unguessable sessionRef is what scopes it to the
client that reserved the booking.
Read-only at the gateway
This verifies; it does not charge. Calling it repeatedly is safe, and is the intended way to poll a checkout you have redirected a patient to.
Body
| Field | Type | Required | Description |
|---|---|---|---|
sessionRef | string | Strongly preferred | The payment session from the reserve response. Globally unique, so it resolves the booking on its own. |
appointmentRef | string | No | The booking reference. A fallback when you do not hold a sessionRef. |
gatewayReferenceId | string | No | The gateway's own transaction id, when its return redirect gave you one. The last fallback, after sessionRef and appointmentRef. |
provider | string | No | The gateway, echoed back from the reserve response. |
Send at least one of sessionRef, appointmentRef or gatewayReferenceId.
Medos tries them in that order. A request with none is refused before it reaches
Medos.
Confirm queue tokens by sessionRef
A QMS appointmentRef is a token display such as P-014 — unique only within
one patient's open bookings, so Medos will not resolve it without a patient
scope and answers 403. This route does not carry a patient scope, so a queue
token must be confirmed by sessionRef. Persist it at reserve time.
Try it
/v1/appointments/confirm-paymentsSend at least one of sessionRef, appointmentRef or gatewayReferenceId. Not OTP-gated — the sessionRef is the scope.
Body
POST /v1/appointments/confirm-payments{}https://api.medos.oneUse a dedicated test key, and put your browser's address on its allowlist
A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.
Request
curl -sX POST "https://api.medos.one/v1/appointments/confirm-payments" \
-H "x-api-key: $MEDOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionRef": "ps_01J9Z6K2QF",
"appointmentRef": "MED-9182-AK",
"provider": "RAZORPAY"
}'Response
{
"status": "SUCCESS",
"appointmentRef": "MED-9182-AK",
"paymentStatus": "PAID",
"walletBalanceAfter": 4,
"message": "Payment verified"
}| Field | Meaning |
|---|---|
status | SUCCESS, FAILED or PENDING — the coarse outcome you branch on. |
paymentStatus | The booking's settlement state at Medos. |
walletBalanceAfter | Sessions left in the patient's pack, when the payment funded one. |
message | Human-readable detail from the payment rail. The only place a terminal reason is spelled out. |
What each status means
status | What to do |
|---|---|
SUCCESS | Done. The booking is PAID. Stop polling. |
FAILED | The payment failed or the session expired. Stop polling and offer a fresh attempt. |
PENDING | Not settled yet. Poll again. |
Bound your polling — PENDING is not always temporary
PENDING is the catch-all: it also covers a session that no longer maps to a
live booking, and a booking Medos already swept and refunded after the
checkout was abandoned. Neither will ever turn into SUCCESS.
Poll on a decaying interval for a few minutes, then stop and read message.
If it mentions the appointment being auto-cancelled, the slot is gone —
prompt the patient to rebook rather than to retry the payment.
Common failures
| Status | Cause |
|---|---|
400 | None of sessionRef, appointmentRef or gatewayReferenceId sent. The body lists fieldErrors — see Errors. |
403 | A queue appointmentRef sent without a sessionRef — see the callout above. |
404 | The reference does not belong to your workspace. |