Payments Tools
View payment transactions, record manual payments, process refunds, send payment links, manage custom charges, and apply promo codes and vouchers to bookings.
Required scope: bookings:read for read tools, bookings:write for write tools
Tools Overview
| Tool | Description | Read-only? |
|---|---|---|
get_payment_transactions | List payment transactions for a booking | Yes |
get_amount_due | Get remaining balance on a booking | Yes |
get_stripe_status | Payment gateway status for this business | Yes |
get_till | The cash drawer today at each location | Yes |
get_security_deposits | What the shop kept from security deposits over a period | Yes |
record_payment | Record a manual/offline payment | No |
process_refund | Process a Stripe refund | No |
send_payment_link | Send a payment link to a customer | No |
send_payment_receipt | Send a payment receipt email | No |
record_security_deposit | Record a deposit taken by hand as held | No |
release_security_deposit | Release a security deposit hold | No |
add_custom_charge | Add an additional charge to a booking | No |
apply_promo_code | Validate and apply a promo code | No |
apply_voucher | Apply/redeem a voucher as payment | No |
get_payment_transactions
List payment transactions for a booking. Shows all payments, refunds, and security deposit transactions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
get_amount_due
Get the remaining balance (amount due) on a booking, including payments and voucher redemptions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
get_till
The cash drawer today at each location: whether the till is open, what it started with, cash sales and refunds, cash security deposits held and returned, cash put in or taken out, and what should be in the drawer now. Once closed: what was counted, whether it was over or short, what was left for tomorrow and what went to the bank. A location where no till was opened today reads not opened today. Needs the Record payments permission.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
location_id | integer | No | One location only. Leave it out for every location |
See Till (cash drawer) for how "should be in the drawer" is worked out.
get_security_deposits
How much the business kept from security deposits over a period, and on which bookings and items. Returns the total kept, the total given back, each booking with its customer, items, the amount kept and the day it was kept, and the same totals grouped by item. Each amount is the one the booking page shows. When part of a kept deposit paid for missing parts, kept_for_missing_parts names that share; it is already inside the kept amount. A deposit split into parts lists each part that was kept. Needs the View bookings permission.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
period | string | No | today, yesterday, this_week, last_week, this_month, last_month or this_year. Leave everything out for this month |
start_date | string | No | First day, YYYY-MM-DD, when no period fits |
end_date | string | No | Last day, YYYY-MM-DD. Defaults to today |
get_stripe_status
Returns the payment gateway status for this business: which gateway it takes card payments on, whether it is ready to accept them, whether security deposits can be held on a card and for how long, and whether card readers are supported.
Businesses on Stripe also get the Stripe Connect detail (account id, onboarding complete, charges and payouts enabled). A business on another gateway does not, because those fields describe an account it never opened.
The tool name is unchanged for compatibility. It answers for every gateway, not only Stripe.
Parameters
None.
Returns
| Field | Type | Description |
|---|---|---|
provider | string | stripe, paystack, rapyd, authorizenet or tilopay |
provider_name | string | The gateway's display name |
ready_to_accept_payments | boolean | Whether the connection is complete enough to take money |
security_deposit_holds_supported | boolean | Whether a deposit can be held on a card rather than charged |
hold_window_days | integer | How many days a hold stays capturable on this gateway |
card_readers_supported | boolean | Whether in-person readers are available |
record_payment
Record a manual/offline payment on a booking (cash, bank transfer, credit card swipe). For Stripe online payments, use send_payment_link instead.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
amount | number | Yes | The payment amount |
payment_method | string | Yes | Method: manual, credit_card, other |
offline_method | string | No | For manual payments: cash, bank_transfer, other |
reference | string | No | Payment reference or note |
confirmed | boolean | No | Must be true to record. First call without to preview. |
process_refund
Process a Stripe refund for a booking. The booking must have a Stripe payment to refund.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
amount | number | Yes | The amount to refund |
reason | string | No | Reason for the refund |
confirmed | boolean | No | Must be true to execute. First call without to preview. |
send_payment_link
Create and send a payment link to a customer for a booking. The customer receives an email with a link to pay online.
The link is paid through the business's own payment gateway: Stripe, Paystack, Rapyd or Authorize.net. On Paystack the customer pays in Paystack's payment window, in ZAR.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
amount | number | No | Amount to charge. If not provided, uses the remaining balance. |
customer_email | string | No | Email to send to. If not provided, uses the booking customer email. |
confirmed | boolean | No | Must be true to send. First call without to preview. |
send_payment_receipt
Send a payment receipt email to the customer for a specific payment transaction.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
transaction_id | integer | Yes | The payment transaction ID |
confirmed | boolean | No | Must be true to send. First call without to preview. |
record_security_deposit
Record a security deposit the business took by hand (cash, bank transfer, other) as held. No card is charged. Pass amount when the owner names the figure taken; it becomes the booking's deposit, so the booking and the record agree.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
amount | number | No | The deposit amount actually taken, in the booking currency. Must be greater than zero. Omit to use the booking's deposit amount. |
offline_method | string | No | cash (default), bank_transfer or other |
security_deposit_id | integer | No | For a deposit split into parts: the part to record |
confirmed | boolean | No | Must be true to record. First call without to preview. |
The reply reads the saved deposit back: deposit_amount and deposit_status (held).
release_security_deposit
Release a security deposit hold or refund a security deposit charge for a booking.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
confirmed | boolean | No | Must be true to execute. First call without to preview. |
add_custom_charge
Add an additional charge to a booking (e.g., damage fee, late return fee, extra service).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
description | string | Yes | Description of the charge (e.g., "Late return fee") |
unit_price | number | Yes | Price per unit |
quantity | integer | No | Quantity (default 1) |
user_confirmed | boolean | Yes | Must be true to add |
apply_promo_code
Validate and apply a promo code to a booking.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
code | string | Yes | The promo code to apply |
user_confirmed | boolean | Yes | Must be true to apply |
apply_voucher
Apply/redeem a voucher as payment on a booking. Immediately applies the voucher balance.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | Yes | The booking ID |
code | string | Yes | The voucher code to apply |
Related
- Bookings Tools - Booking management
- Promotions Tools - Promo code and voucher management