The payments API from GetMyHotels — 6 operation(s) for payments.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/getmyhotels-com:getmyhotels-com-payments-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: GetMyHotels REST Payments API
version: 1.0.0
description: REST surface for the native GetMyHotels apps. Every route is a thin transport over the shared tRPC routers — inputs are validated with the same Zod schemas the web client uses, and responses are returned verbatim. Authentication uses Better Auth bearer session tokens issued by the /api/auth/* endpoints (not part of this spec). Native clients send X-GMH-App-Version and X-GMH-Platform on every request; versions below the configured floor receive a typed 426 UpgradeRequiredError.
servers:
- url: https://api.getmyhotels.com
description: Production API
tags:
- name: Payments
paths:
/v1/payments/hotel-checkout-quote:
post:
tags:
- Payments
summary: Price a hotel checkout before payment
description: 'Runs `payment.getHotelCheckoutQuote`. Public by design — it is the price-on-load half of the guest-capable payment-first checkout (critical decision #4), and it is the same call the web checkout makes when its form mounts. Pure read: no PaymentIntent, no payment row, no booking. Call it as the checkout screen loads so the real supplier tax/fee split, add-ons, promo outcome and `rateValidUntil` are on screen BEFORE the customer commits to paying, then send the same pricing fields to `POST /v1/payments/hotel-checkout-intent`. POST rather than GET because the input carries a supplier room id up to 8 KB. Signed-in callers also get their saved cards; staff accounts get `simulated: true`.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
offerRef:
type: string
minLength: 1
maxLength: 20000
supplierCode:
type: string
minLength: 1
maxLength: 50
supplierHotelId:
type: string
minLength: 1
maxLength: 255
supplierRoomId:
type: string
minLength: 1
maxLength: 8192
checkIn:
type: string
format: date
checkOut:
type: string
format: date
rooms:
type: integer
minimum: 1
maximum: 9
default: 1
adults:
type: integer
minimum: 1
maximum: 10
default: 2
children:
type: integer
minimum: 0
maximum: 6
default: 0
childrenAges:
type: array
items:
type: integer
minimum: 0
maximum: 18
maxItems: 6
default: []
totalPrice:
type: number
exclusiveMinimum: 0
currency:
type: string
minLength: 3
maxLength: 3
promoCode:
type: string
maxLength: 50
addonIds:
type: array
items:
type: string
maxLength: 40
maxItems: 10
default: []
required:
- checkIn
- checkOut
- totalPrice
- currency
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `payment.getHotelCheckoutQuote` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: postV1PaymentsHotelCheckoutQuote
x-operation-id-source: derived
/v1/payments/hotel-checkout-intent:
post:
tags:
- Payments
summary: Create a payment-first hotel checkout intent
description: 'Runs `payment.createHotelCheckoutIntent`. Public by design — guests can complete a payment-first checkout without an account (critical decision #4). Guest calls must include a contact email on the lead guest.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
offerRef:
type: string
minLength: 1
maxLength: 20000
supplierCode:
type: string
minLength: 1
maxLength: 50
supplierHotelId:
type: string
minLength: 1
maxLength: 255
supplierRoomId:
type: string
minLength: 1
maxLength: 8192
hotelName:
type: string
minLength: 1
maxLength: 255
hotelStarRating:
type: number
minimum: 0
maximum: 5
hotelCity:
type: string
maxLength: 255
hotelCountry:
type:
- string
- 'null'
minLength: 3
maxLength: 3
roomName:
type: string
minLength: 1
maxLength: 255
roomMaxOccupancy:
type:
- number
- 'null'
minimum: 1
maximum: 20
roomBedType:
type: string
maxLength: 50
images:
type: array
items: {}
address:
type: string
property:
type: object
description: Rich supplier-mapped property snapshot; invalid values are dropped, never rejected.
checkIn:
type:
- string
- 'null'
checkOut:
type:
- string
- 'null'
rooms:
type: integer
minimum: 1
maximum: 9
default: 1
adults:
type: integer
minimum: 1
maximum: 10
default: 2
children:
type: integer
minimum: 0
maximum: 6
default: 0
childrenAges:
type: array
items:
type: integer
minimum: 0
maximum: 18
maxItems: 6
default: []
totalPrice:
type: number
exclusiveMinimum: 0
currency:
type: string
minLength: 3
maxLength: 3
baseRate:
type: number
minimum: 0
taxes:
type:
- number
- 'null'
minimum: 0
fees:
type:
- number
- 'null'
minimum: 0
expectedTotal:
type: object
properties:
amountMinor:
type: integer
minimum: 0
maximum: 9007199254740991
currency:
type: string
minLength: 3
maxLength: 3
required:
- amountMinor
- currency
guests:
type: array
items:
type: object
properties:
firstName:
type: string
minLength: 2
maxLength: 100
lastName:
type: string
minLength: 2
maxLength: 100
email:
type: string
maxLength: 255
format: email
phone:
anyOf:
- type: string
maxLength: 80
- type: string
minLength: 0
maxLength: 0
isLead:
type: boolean
default: false
nationality:
type: string
minLength: 2
maxLength: 3
dateOfBirth:
type: string
maxLength: 10
gender:
type: string
maxLength: 20
required:
- firstName
- lastName
minItems: 1
maxItems: 10
specialRequests:
type: string
maxLength: 2000
arrivalTime:
type: string
maxLength: 5
departureFlightNumber:
type: string
maxLength: 20
promoCode:
type: string
maxLength: 50
language:
type: string
enum:
- en
- es
- fr
- de
- zh
- hi
- pt
- it
- ja
- te
- gu
- ko
- bn
- ru
addonIds:
type: array
items:
type: string
maxLength: 40
maxItems: 10
default: []
cancellationSummary:
type: string
maxLength: 500
refundable:
type: boolean
freeCancellationUntil:
type:
- string
- 'null'
maxLength: 64
allowNonRefundable:
type: boolean
default: false
termsAccepted:
type: boolean
default: false
termsVersion:
type: string
minLength: 1
maxLength: 20
idempotencyKey:
type: string
minLength: 1
maxLength: 255
savedPaymentMethodPublicId:
type: string
minLength: 1
maxLength: 36
autoRebook:
type: boolean
default: false
turnstileToken:
type: string
maxLength: 2048
buyerCompanyName:
type: string
minLength: 1
maxLength: 255
buyerTaxIdCountry:
type: string
enum:
- IN
- GB
- AT
- BE
- BG
- CY
- CZ
- DE
- DK
- EE
- ES
- FI
- FR
- GR
- HR
- HU
- IE
- IT
- LT
- LU
- LV
- MT
- NL
- PL
- PT
- RO
- SE
- SI
- SK
buyerTaxId:
type: string
minLength: 1
maxLength: 50
required:
- hotelName
- roomName
- checkIn
- checkOut
- totalPrice
- currency
- guests
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `payment.createHotelCheckoutIntent` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: postV1PaymentsHotelCheckoutIntent
x-operation-id-source: derived
/v1/checkout/sessions:
post:
tags:
- Payments
summary: Hand a hotel checkout to the hosted web checkout
description: 'Runs `checkout.createSession` with the same stay-total mapping the MCP `create_checkout` tool uses, and returns its `{ id }`. The client opens `/checkout/`, where the guest pays on getmyhotels.com. Public by design (critical decision #4). Native apps use it when their in-app payment sheet cannot be shown, so a booking never dead-ends. Writes only the session row; nothing is charged.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ref:
type: string
minLength: 1
maxLength: 512
offerRef:
type: string
minLength: 1
maxLength: 16384
hotelName:
type: string
minLength: 1
maxLength: 300
roomName:
type: string
maxLength: 300
checkIn:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
checkOut:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
price:
type: number
exclusiveMinimum: 0
description: Total for the WHOLE stay across all rooms, as the checkout quote priced it.
currency:
type: string
minLength: 3
maxLength: 8
adults:
type: integer
minimum: 1
maximum: 30
children:
type: integer
minimum: 0
maximum: 12
rooms:
type: integer
minimum: 1
maximum: 9
childrenAges:
type: array
items:
type: integer
minimum: 0
maximum: 17
maxItems: 12
required:
- ref
- offerRef
- hotelName
- roomName
- checkIn
- checkOut
- price
- currency
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `checkout.createSession` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'429':
description: Rate limit reached for this caller. Show the message and let the customer retry later.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: postV1CheckoutSessions
x-operation-id-source: derived
/v1/payments/{publicId}/confirm:
post:
tags:
- Payments
summary: Finalize a hotel checkout after payment
description: 'Runs `payment.confirm` for the payment transaction created by `POST /v1/payments/hotel-checkout-intent`. Public by design — it is the second half of the guest-capable payment-first checkout (critical decision #4), and ownership is enforced by the procedure against the transaction''s own userId. Call it after the Stripe PaymentSheet reports success, or immediately when the intent came back with `testMode: true` (staff simulate path). Send `{}` when there is no provider transaction id to pass through. The booking row, supplier reservation and confirmation email are all created here, so the response carries the booking reference the confirmation screen shows.'
parameters:
- schema:
type: string
minLength: 1
maxLength: 36
required: true
name: publicId
in: path
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
providerTransactionId:
type: string
minLength: 1
maxLength: 255
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `payment.confirm` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: postV1PaymentsByPublicIdConfirm
x-operation-id-source: derived
/v1/payments/bookings/{bookingPublicId}/complete:
post:
tags:
- Payments
summary: Finish a paid booking whose supplier call never landed
description: 'Runs `payment.completePendingBooking`. Call it from the booking screen when a hotel booking reads `pending_payment`: on the payment-first flow the row is only written after the card is charged, so that status is not a customer who failed to pay — it is a customer whose money we took and whose supplier call died in flight. Charge-free by construction: it refuses unless a completed payment transaction already exists for the booking, and it never calls Stripe. Never send one of these bookings to `POST /v1/payments/hotel-checkout-intent` instead — that charges the card a second time for one stay. Public by design, matching the rest of the guest-capable checkout (critical decision #4): the CUID is the access key for guest rows, and a booking owned by an account must match the caller. Idempotent — a booking already confirmed answers 200 with `alreadyDone: true`, and the underlying supplier book is idempotent on the supplier reservation id, so a double tap cannot double-book. A supplier that still refuses is NOT an error here: the response is 200 with `status: "pending_manual"`, ops are paged, and the charge stands — show the customer that their booking is being settled by hand rather than a failure. 400 means the booking is unpaid or in a status nobody is waiting on us to finish.'
parameters:
- schema:
type: string
minLength: 1
maxLength: 36
required: true
name: bookingPublicId
in: path
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `payment.completePendingBooking` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: postV1PaymentsBookingsByBookingPublicIdComplete
x-operation-id-source: derived
/v1/payments/recovery/{token}:
get:
tags:
- Payments
summary: Resolve a 3DS payment-recovery link
description: 'Runs `payment.resolveCheckoutRecovery`. Public by design — the caller is a guest or signed-in customer who followed the `requires_action` email link with no other credential (critical decision #4). Never throws for an unknown, expired, or wrong-state token: every outcome, including one that doesn''t resolve to anything, is a distinct `kind` in the 200 body, so a probing caller and a legitimate one get the same shape of answer either way. When `kind` is `resumable`, the response carries a freshly-fetched Stripe client secret — re-fetched from Stripe on every call, never read from a stored column, and never logged — for the SAME PaymentIntent the original checkout created. Rate-limited like the rest of the write-tier payment surface even though this route never charges anything, because it calls out to Stripe on every resolve.'
parameters:
- schema:
type: string
minLength: 1
maxLength: 64
required: true
name: token
in: path
responses:
'200':
description: Success
content:
application/json:
schema:
description: Verbatim JSON output of the `payment.resolveCheckoutRecovery` tRPC procedure. Response shapes are intentionally not modeled in this spec; the native client types them by hand.
'400':
description: Request validation failed or the router rejected the input
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'426':
description: Reported X-GMH-App-Version is below the supported minimum — the app must update
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRequiredError'
'500':
description: Unexpected server error (opaque; details stay in logs)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
operationId: getV1PaymentsRecoveryByToken
x-operation-id-source: derived
components:
schemas:
UpgradeRequiredError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- UPGRADE_REQUIRED
message:
type: string
minVersion:
type: string
example: 1.2.0
platform:
type:
- string
- 'null'
required:
- code
- message
- minVersion
- platform
required:
- error
ApiError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: Booking not found
domainCode:
type: string
example: NON_REFUNDABLE_CONSENT_REQUIRED
issues:
type: array
items:
type: object
properties:
path:
type: string
message:
type: string
required:
- path
- message
required:
- code
- message
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Better Auth session token. Obtain it from the native /api/auth/* endpoints (Better Auth bearer plugin — out of scope for this spec, see #922).'
x-provenance:
method: harvested
publisher: GetMyHotels
source: https://api.getmyhotels.com/v1/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)