API Reference

Collect invoice payment by using a guest's unsaved credit/debit card

post https://api.zenoti.com/v1/invoices//online_payments

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 with tip_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:

  1. Initial Request: Send payment request with center_id and redirect_uri
  2. Hosted Payment Response: API returns hosted_payment_uri for secure card collection
  3. Guest Redirect: Redirect guest's browser to the hosted_payment_uri
  4. Card Collection: Guest enters their card details on the secure hosted page
  5. Payment Processing: System processes the payment using the provided card details
  6. Return: After payment completion, guest is redirected back to your redirect_uri with the payment status
  7. 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.

Language
Credentials
Header
Click Try It! to start a request and see the response here!