Guide: take payments
This guide shows how to collect money on a reservation through the API: a payment link, a charge on a saved card, a security deposit, an offline payment and refunds.
Amounts are in the reservation currency, except payment links, which charge in the currency of their payment method.
Payment methods
GET /payment-gateways/methods lists the active payment methods, 100 per page.Each method belongs to one gateway and one currency; send
currency to get the methods of one currency.Use the method
id as payment_method_id below, and pick a method in the reservation currency.Option 1 - Payment link when the booking is created
POST /car-rental/reservations/confirm:| Field | Meaning |
|---|---|
return_payment_link | 1 to start an online payment. Leave the field out when you do not want one: even the string false starts a payment. |
payment_method_id | The method to pay with. If it does not match an available method, the first available one is used. |
payment_external_redirect | Where the customer goes after paying. |
set_amount_to_pay_online_from_settings | 1 to charge the online amount from your settings instead of the outstanding balance. |
data.transaction with the transaction uuid and the payment_link to send the customer to.data.transaction is missing when no payment method of the branch fits the booking, for example none in the reservation currency.Option 2 - Payment link for an existing reservation
item_type, item_id, payment_method_id, amount and external_redirect (a full URL) are required.The response has the transaction under
payment_gateways_transaction; send the customer to its external_url.If your account passes card fees on to customers, the fee is added to
amount.If an open transaction already exists for the same reservation and method, HQ reuses it with the new amount.
Check that the customer paid
GET /payment-gateways/payment-transactions/{uuid}/uuid returns the transaction; its status becomes paid once the payment is approved.At that moment HQ records the payment on the reservation and updates its totals.
To be told instead of asking, ask your HQ administrator for a Reservation Payment
Created webhook (see Webhooks).Charge a saved card
POST /car-rental/reservations/{reservation_id}/payments/charge-credit-card with amount charges a card the customer saved before, for example during an online booking.GET /payment-gateways/credit-cards?contact_type=contacts&contact_id=55 lists the saved cards of contact 55; send one id as preferred_card_id to try it first.Without it, HQ tries only the reservation's preferred card when it has one, otherwise every saved card.
"success": true even when no card was charged.Read
data.result: payment_approved, payment_declined, or payment_request_sent when you sent send_payment_request=1 and the customer has an email.skip_payment_email and skip_payment_request_email act on presence: any value turns them on, even 0.Leave them out to keep the emails.
Security deposits
authorization=1 to the charge-credit-card request to hold amount instead of charging it.Like the
skip_* flags it acts on presence: any value, even 0, places a hold, so leave it out to charge.POST /car-rental/reservations/{reservation_id}/payments/online-security-deposit-refund with refunded_amount, the amount to give back.POST /car-rental/reservations/{reservation_id}/payments/{id}/security-deposit-refund with amount_to_refund.The amount you give back is recorded as a refund, and the rest of the deposit becomes a payment.
Record a payment taken outside HQ
POST /car-rental/reservations/{reservation_id}/payments records a cash, bank transfer or other offline payment without charging anything.The body is your Payments form, with each value as
field_<id> (see Custom fields and item types).Send
send_confirmation_email=1 or 0 to choose whether the customer gets a receipt; without it, your account default applies.GET /car-rental/reservations/{reservation_id}/payments lists every payment of the reservation, including holds and online payments with their transaction.Refunds
POST /payment-gateways/payment-transactions/{id}/refund with refunded_amount refunds an online payment through its gateway.Take the transaction
id from the reservation's payments.Send
metadata as the JSON string {"payment_id": 812} with the id of that payment, so the refund is also recorded on the reservation; without it the card is refunded but the reservation still shows the payment.Like a charge, a refund is not idempotent, so read the reservation's payments before you retry one.
A refund larger than what is left on the transaction returns a validation error, and a refusal by the gateway returns
"success": false with the reason in errors.error.POST /car-rental/reservations/{reservation_id}/refunds records a refund made outside HQ.Like payments, the body is your Refunds form as
field_<id>; add send_confirmation_email=1 to email the customer.Modified at 2026-10-29 13:56:40