Overview
This API enables you to collect payment for an invoice by using a guest's new (unsaved) credit or debit card.
Endpoint: POST /api/v1/invoices/{invoice_id}/online_payments
๐ Prerequisites
- Valid API authentication
- Invoice must exist and be in an open state
- User must have appropriate permissions (Add or Edit on Appointments object)
Key Information
-
Amount: If
amount
is not provided, the system calculates the total based on invoice balance, SSG amount, tip, and fees. -
New Card: For unsaved card transactions, the system will always return a hosted payment URI to collect card details securely
-
Redirect URI: Always include
redirect_uri
for proper redirection flow after payment completion -
Tip Handling:
- Tips can be included with invoice payment
- Tips can be processed separately after invoice is paid
- Use
amount: 0
withtip_amount
for tip-only transactions
-
Source Tracking: The
source
parameter helps track payment origin for analytics and reporting.- 1 for WebStore (default)
- 5 for Mobile
-
Billing Information: Required for new card transactions when AVS (Address Verification Service) is enabled.
-
Validation: The API validates invoice status, user permissions, and payment configuration before processing.
Request Structure
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"billing_info": null,
"source": 1
}
Billing Info Structure
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"country_code": "US",
"address": "123 Main St",
"state": "CA",
"zipcode": "90210",
"city": "Beverly Hills",
"phone": "+1-555-123-4567"
}
Response Structure
Success Response
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
Error Response
{
"success": false,
"error": {
"code": 400,
"message": "Invoice not found"
}
}
Use Cases
๐ Use Case 1: Standard Invoice Payment Using New Card
Scenario: A guest wants to pay for a service invoice using a new credit card.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
๐ณ Use Case 2: Invoice Payment with Tip Included
Scenario: A guest wants to pay both the invoice and tip in one transaction using a new card.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"tip_amount": 15.00,
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
๐งพ Use Case 3: Tip Payment After Invoice is Paid
Scenario: The invoice has already been paid, and the guest wants to add a tip using a new card.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"amount": 0,
"tip_amount": 15.00,
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
๐ Use Case 4: Group Invoice Payment by Host
Scenario: The host of a group appointment pays for the entire group invoice using a new card.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
๐ Use Case 5: Group Invoice Payment by Group Member
Scenario: A group member (not the host) wants to surprise the group by paying for everyone's services using their new card. Use paying_guest_id
to specify a different payer than the invoice host.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"paying_guest_id": "33CDC6F6-7GE1-68F6-AED8-D3E754FD6EE6",
"redirect_uri": "https://example.com/payment-success",
"tip_amount": 25.00,
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
๐ณ Use Case 6: New Card Payment and Save for Future Use
Scenario: A guest wants to pay for a invoice using a new credit card and save it for future payments.
Request Body:
{
"center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
"redirect_uri": "https://example.com/payment-success",
"can_save_card": true,
"billing_info": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"country_code": "US",
"address1": "123 Main St",
"state": "CA",
"zipcode": "90210",
"city": "Beverly Hills",
"phone": "+1-555-123-4567"
},
"source": 1
}
Response:
{
"success": true,
"error": null,
"hosted_payment_uri": "https://secure-payment.zenoti.com/collect-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
"token_id": "550e8400-e29b-41d4-a716-446655440124"
}
Response Details:
When processing payments with new cards, the API always returns:
-
hosted_payment_uri
: This field contains a URL to a secure hosted payment page where the guest can safely enter their new card details. You must redirect the guest to this URL to complete the card collection process. -
token_id
: A unique session token that maintains the payment session state during the hosted payment flow.
Implementation Flow:
- Initial Request: Send payment request with
center_id
andredirect_uri
- Hosted Payment Response: API returns
hosted_payment_uri
for secure card collection - Guest Redirect: Redirect guest's browser to the
hosted_payment_uri
- Card Collection: Guest enters their card details on the secure hosted page
- Payment Processing: System processes the payment using the provided card details
- Return: After payment completion, guest is redirected back to your
redirect_uri
with the payment status - Transaction Complete: Only after successful payment processing will an
invoice_transaction_id
be generated
Important Notes:
- The
hosted_payment_uri
is always provided for new card transactions - No
invoice_transaction_id
is returned in the initial response as payment hasn't been processed yet - Always redirect guests to the
hosted_payment_uri
to collect card details securely - The
redirect_uri
parameter is mandatory for all transactions - Payment is processed automatically after card details are collected
- Transaction ID will be available only after successful payment completion
Common Error Responses
AVS Verification Failed
{
"success": false,
"error": {
"code": 400,
"message": "Transaction failed due to an incorrect billing address. Please update the postal code and try again."
}
}
Invoice Not Found
{
"success": false,
"error": {
"code": 404,
"message": "Invoice not found"
}
}
Invoice Already Closed
{
"success": false,
"error": {
"code": 400,
"message": "Payment cannot be added for closed invoice"
}
}
Payment Already Made
{
"success": false,
"error": {
"code": 400,
"message": "Payment has already been made in full"
}
}
Invalid Center ID
{
"success": false,
"error": {
"code": 400,
"message": "Invalid center id"
}
}
Missing Redirect URI
{
"success": false,
"error": {
"code": 400,
"message": "redirect_uri is required"
}
}
Payment Configuration Not Found
{
"success": false,
"error": {
"code": 400,
"message": "Payment configuration not done"
}
}
User Not Authorized
{
"success": false,
"error": {
"code": 403,
"message": "User not authorized"
}
}
๐ก Implementation Notes
- New Card Processing: This API is designed for processing payments with new/unsaved credit or debit cards
- Mandatory Redirect URI: Always include
redirect_uri
as it's required for the hosted payment flow - Hosted Payment Flow: The system will redirect guests to a secure hosted payment page to enter their card details
- No Immediate Transaction ID: The response does not include
invoice_transaction_id
because payment processing occurs after card collection - Billing Information: Include billing details when AVS verification is required by the payment processor
- Group Invoice Support: Use
paying_guest_id
when someone other than the invoice host is paying - Asynchronous Processing: Payment is processed after card details are collected on the hosted page
- Security: All card data is handled securely through PCI-compliant hosted payment pages
This API provides a secure and flexible way to collect invoice payments using new credit or debit cards with full support for hosted payment collection and various payment scenarios.