public-api-docs

Operations API Payments And Invoices Guide

Overview

Payments and invoices connect rental and booking prices to the customer’s or business account’s financial record. Use the Operations API payment, invoice, balance, voucher, and billing-overview endpoints when building support tools, finance back-office workflows, payment retry tooling, refund workflows, invoice review screens, or customer-care credit workflows.

Finance actions can affect customer balances, payment provider charges, invoices, refunds, collection workflows, and audit trails. Treat write operations in this domain as privileged actions and make the user, branch, invoice, payment, amount, currency, and reason visible before submitting changes.

Related reference: Operations API Operations API Guide Rental Guide Booking Guide Customers And Groups Guide Pricing Guide Error Codes

Core Concepts

Price, Billing Overview, Invoice, Payment, Balance, Voucher

These concepts are related but not interchangeable:

Concept Meaning Use it for
Price Calculated cost of a booking, rental, addition, package, rebate, surcharge, or penalty. Understanding how an amount was calculated.
Billing overview Aggregated support view of pricing and refunds for a rental or booking. Explaining a charge to an operator or customer.
Invoice Financial document with invoice state, line items, tax, refund links, and payment reference. Finance review, download, refund, resend, collection.
Payment Payment collection attempt and state, usually linked to payment provider activity. Payment status and retry workflows.
Balance Wallet/account ledger for a user or business account. Reviewing open balances, settling balances, collection invoices.
Voucher Credit, package, promotion, customer-care benefit, or redeemable value. Customer-care credit and voucher campaigns.

For support tools, start with the billing overview on the rental or booking. Move to invoice, payment, balance, or voucher endpoints only when the operator needs the financial object itself.

Invoice State

Invoice states describe where the invoice is in its lifecycle:

State group Examples Meaning
Draft/open OPEN, CLOSED Invoice exists but is not necessarily billed or paid.
Billing/payment BILLED, IN_PAYMENT, PAID, PAID_EXTERNALLY Invoice was billed, is being paid, or was paid.
Payment exceptions EXCEPTION_BILLING, EXCEPTION_SEPA, EXCEPTION_PAYING, PUSH_BANK_REFUSED, THREE_DS_FAILED Billing or payment provider flow failed.
Push/3DS waiting PUSH_WAITING_FOR_USER, THREE_DS_WAITING_FOR_USER User action is needed in a payment flow.
Refund ALLOWS_REFUND, REFUND_IN_PROGRESS, REFUNDED, EXCEPTION_REFUND, IS_REFUND Refund is possible, running, completed, failed, or this invoice is a refunding invoice.
Collections COLLECTION, DISPUTED, IGNORE Invoice is in collection/dispute/ignored workflow.

Do not infer payment success from invoice state alone. If payment-provider state matters, inspect the linked payment and attempts.

Payment State And Attempts

A payment can have multiple attempts. The payment state summarizes the overall payment; attempts show individual provider interactions.

Payment states include:

State Meaning
OPEN Payment exists but is not finished.
IN_PAYMENT Payment is currently being processed.
AWAITING_RETRY Payment is waiting for a retry window.
PAID Payment succeeded.
FAILED Payment failed.
DISPUTED Payment is disputed.
COLLECTIONS Payment moved to collections.
PUSH_WAITING_FOR_USER User must act in a push payment flow.
PUSH_CANCELLED_BY_USER User canceled the push payment flow.
PUSH_BANK_REFUSED Bank refused the push payment flow.

Attempt states can show whether a specific attempt is retryable, refunded, disputed, waiting, paid, or failed. Use attempts when an operator needs to understand why retrying is or is not possible.

Payment Sources

Payment sources are available through customer and group endpoints:

Owner Endpoint
Customer GET /customers/{id}/payment-sources
Business account GET /groups/{id}/payment-sources

The response only includes payment sources the executing operator can see. Payment method editing is usually a customer-facing provider flow; do not expose payment-source deletion or source changes unless the operator role and tenant process explicitly allow it.

Balances

Balances are ledgers for users or business accounts. They can hold amounts that need to be settled, collected, or reviewed.

Use GET /balances with either userId or groupId. If both are provided, userId is used. Add branchId to limit balances to the billable branch context.

Business rentals are charged against the business account’s balance. For business account concepts, see the Customers And Groups Guide.

Vouchers

Vouchers represent credit or benefits that can affect what a customer pays. They may come from packages, promotions, customer care, subscriptions, signup/referral workflows, or other voucherable templates.

Use customer-care apply-vouchers endpoints for support credit. Use voucher/redeemable endpoints for issued-voucher review and campaign-style code workflows. Promotion, package, subscription, ride-pass, customer-care template, and benefit setup belongs in the Operations API Promotions, Packages, Subscriptions, And Benefits Guide.

Common Operator Workflows

Explain A Rental Or Booking Charge

Use the billing overview first:

Source Endpoint
Rental GET /rentals/{rentalId}/billing-overview
Booking GET /bookings/{bookingId}/billing-overview

Billing overview is the best support-facing starting point because it shows the price overview and refunds overview without requiring the operator to manually join price, invoice, line item, and refund data.

If the operator needs the underlying financial document, follow the invoice reference from the billing overview to the invoice endpoints.

Search And Review Invoices

Use GET /invoices.

Useful filters:

Filter Use it for
branchId Required branch scope.
balanceId Find invoices linked to a balance.
chargeId Find an invoice by payment-provider charge reference.
invoiceId Find a specific numeric invoice record.
guser.firstName Search by customer first name.
invoiceType Filter REGULAR or BUSINESS invoices.

Use GET /invoices/{invoiceId} for the invoice detail and GET /invoices/{invoiceId}/line-items for line items. Line items can optionally be filtered by bookingId or rentalId.

Download, Resend, Or Review Invoice Reports

Use these endpoints:

Task Endpoint
Download invoice GET /invoices/{invoiceId}/download
Resend invoice POST /invoices/{invoiceId}/resend
Invoice overview GET /invoices/overview
Invoice statement report GET /invoices/reports
Line item templates GET /invoices/line-item-templates

Resending an invoice requires a mailMessage and can optionally specify a notification channel such as EMAIL, SMS, PUSH, or SLACK.

Edit Or Bill An Invoice

Use these endpoints only in administrative finance tooling:

Task Endpoint
Patch invoice title/description PATCH /invoices/{invoiceId}
Patch one line item PATCH /invoices/{invoiceId}/line-item/{lineItemId}
Delete one line item DELETE /invoices/{invoiceId}/line-items/{lineItemId}
Bill invoice POST /invoices/{invoiceId}/bill

When creating or updating line item amounts, provide either net or gross price, not both. If using a line item template, the template controls which fields are overrideable.

Refund An Invoice

Use POST /invoices/{invoiceId}/refund.

Refunds should include a reason and explicit refund items. Refund workflows can create refunding invoices and update invoice states such as REFUND_IN_PROGRESS, REFUNDED, EXCEPTION_REFUND, or IS_REFUND.

Operator tools should:

Mark Invoice Payment Or Collection State

Use these endpoints only for finance workflows where the operator has authority to change invoice settlement state:

Task Endpoint
Mark paid externally POST /invoices/{invoiceId}/set-paid-externally
Mark as lost POST /invoices/{invoiceId}/mark-as-lost
Mark for collection POST /invoices/{invoiceId}/mark-for-collection

These actions can materially change finance operations. Require confirmation and show the current invoice state before submitting.

Review And Retry Payments

Use these endpoints:

Task Endpoint
List payments for branch GET /payments?branchId={branchId}
Get payment GET /payments/{id}
Retry payment POST /payments/{id}/retry

Retry only when the payment and attempt state indicate retry is appropriate. Some flows require user action, such as push or 3DS approval; retrying immediately may not help.

Review Or Remove Payment Sources

Use customer/group payment-source endpoints for review:

Owner Endpoint
Customer GET /customers/{id}/payment-sources
Business account GET /groups/{id}/payment-sources

DELETE /payments removes or changes a payment source for either userId or userGroupId using a sourceId request body. Expose this only in controlled support/admin workflows because removing a payment source can block future rentals, bookings, or invoice settlement.

Review And Settle Balances

Use these endpoints:

Task Endpoint
List balances GET /balances
Create balance POST /balances
Get balance GET /balances/{balanceId}
Get balance events GET /balances/{balanceId}/events
Get balance updates GET /balances/{balanceId}/updates
Extended balance view GET /balances/extended
Settle balance POST /balances/{balanceId}/settle
Bulk settle balances POST /balances/bulk-settle
Generate collection invoice POST /balances/{balanceId}/settle-by-collection-invoice

Use balance events and updates for audit-style review. Treat settlement, bulk settlement, and collection invoice generation as finance-admin actions.

Deprecated customer/group balance endpoints exist in the API, but new tooling should use the /balances endpoints instead of /customers/{customerId}/balances or /groups/{id}/balances.

Apply Customer-Care Credit

For customer-care benefits, use:

Task Endpoint
Apply vouchers to customer POST /customers/{userId}/apply-vouchers
Apply vouchers to business account POST /groups/{groupId}/apply-vouchers

These endpoints create all vouchers produced by the selected customer-care voucherable. Prefer them over deprecated singular voucher endpoints.

Review And Manage Vouchers

Use these endpoints:

Task Endpoint
List vouchers GET /vouchers
Get voucher by code GET /vouchers/by-code/{code}
List constraint vouchers GET /vouchers/constraint-vouchers
Cancel constraint voucher POST /vouchers/constraint-vouchers/{id}/cancel
Create redeemable vouchers POST /vouchers/redeemable
Create constraint redeemable vouchers POST /vouchers/redeemable/constraint
Redeemable voucher summary GET /vouchers/redeemable/summary

POST /vouchers and GET /vouchers/voucher-campaigns are deprecated. Use the redeemable/constraint endpoints and voucherable/package workflows for new tooling.

Most Relevant APIs

Area Endpoint
Rental billing overview GET /rentals/{rentalId}/billing-overview
Booking billing overview GET /bookings/{bookingId}/billing-overview
Invoice list/detail GET /invoices, GET /invoices/{invoiceId}
Invoice line items GET /invoices/{invoiceId}/line-items, line-item patch/delete endpoints
Invoice document/reporting GET /invoices/{invoiceId}/download, GET /invoices/overview, GET /invoices/reports
Invoice actions Refund, resend, bill, set paid externally, mark lost, mark collection endpoints
Payments GET /payments, GET /payments/{id}, POST /payments/{id}/retry
Payment sources GET /customers/{id}/payment-sources, GET /groups/{id}/payment-sources, DELETE /payments
Balances GET/POST /balances, balance detail/events/updates/settlement endpoints
Customer-care vouchers POST /customers/{userId}/apply-vouchers, POST /groups/{groupId}/apply-vouchers
Vouchers GET /vouchers, voucher by code, constraint voucher, redeemable voucher endpoints

Permissions And Settings

Finance endpoints are permission-gated and commonly evaluated on the business unit/billable branch behind the operational branch. A user may be able to view a rental through branch permissions but not view its billing overview, invoice, payment, balance, payment source, voucher, or refund controls if they lack the matching business-unit permission.

Common permission considerations:

Workflow Permission consideration
Billing overview Rental/booking read plus billing visibility.
Invoice search and detail Invoice/finance read permission for the business unit/billable branch.
Invoice edits and billing Finance administration permission on the business unit.
Refunds Refund permission and often elevated finance role.
Mark paid externally/lost/collection Finance administration or collections permission.
Payment retry Payment administration permission.
Payment sources Payment-source visibility and support/admin permission.
Balances and settlement Balance/finance permissions.
Vouchers/customer-care credit Voucher/customer-care permissions on the business unit that owns the template or issued voucher.

Settings and configuration that can affect this domain include:

Area Why it matters
Payment settings Control supported payment methods, payment provider behavior, pre-authorizations, signup fees, and retry behavior.
Invoice settings Control invoice creation, billing cycles, templates, tax, and notification behavior.
Business account settings Affect invoicing, billing cycle, cost centers, and balance settlement for business rentals.
Pricing settings Determine the calculated amounts that appear on invoices and billing overview.
Rental requirements Can require payment source, signup fee, positive credit, or payment pre-authorization before rental start.
Voucher/package settings Control voucher applicability, package purchase behavior, and signup/referral benefits.

Use GET /settings only when your tool knows the relevant DASHBOARD or SHARED setting keys. Use /settings-management for administrative settings discovery and configuration.

Implementation Notes For Custom Tools

Review Notes

The following product decisions are reflected in this guide: