Create a one-time charge on a reservation and get a link to the Hostex payment page for it. Send the guest to payment_link; the guest pays there with the host's own payment accounts, and the money goes to those accounts the same way as for a charge the host creates in Hostex.
Typical flow for a booking website: create the reservation with POST /reservations, call this endpoint with the amount to collect, redirect the guest to payment_link, then read payment on GET /reservations to see whether it has been paid. There is no webhook when the guest pays, the guest is not redirected back to your website after paying, and Hostex does not cancel reservations that stay unpaid: cancel them yourself with DELETE /reservations/{reservation_code} if you need to.
Payment accounts. You do not choose the payment account. Hostex offers the guest every payment account of the host that is connected, has Use for charges turned on, and accepts the charge currency (WeChat Pay accounts accept CNY only, Flywire accounts only their own currency, and PayPal accounts only the currencies PayPal supports). If the host has no such account the request fails with 400 and nothing is created; the host has to connect a payment account in Hostex first. payment_account_types in the response lists the kinds of account the guest will see.
Income item and payment status. A payment on the charge is recorded as income under the charge's income item. payment on GET /reservations only counts income recorded as reservation payout, so leave income_item_id at its default 22 (Reservation payout) when you rely on payment to see whether the guest has paid. With another income item (for example a cleaning fee) the payment is still recorded, but payment.received_amount and payment.status do not change.
Notifications. The host's charge notification rules in Hostex apply to charges created here as well. Unless the host has changed them, the guest receives an email with the same payment link when the charge is created and reminders around the due date, and a confirmation after paying.
Retries. Send an idempotency_key to retry safely: within 24 hours, a request with the same key and the same parameters returns the charge the first request created (created: false) instead of creating another one. This also holds when a request with a key failed with 500: retrying it with the same key either returns the charge that request created or creates it once. Without a key, every request creates a new charge, and a guest could pay each of them.
400Invalid parameters; the currency is not the reservation's currency; the income item does not exist; the reservation is cancelled, declined or expired; or the host has no connected payment account with Use for charges turned on that accepts the currency. Nothing is created.
404The reservation was not found.
409The idempotency_key was already used with different parameters, or the charge it created has since been deleted. Use a new key.
420Charges are not available on the host's current plan.
429A request with the same idempotency_key is still being processed. Retry later with the same key.
