API Reference

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

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

This API enables you to collect payment for an invoice by using a guest's previously saved credit or debit card.

To retrieve the payment methods saved against a guest, please refer to the API documentation link.

Key information useful for using the API appropriately

  • Amount : If amount is not provided, the system calculates the total based on invoice balance, SSG amount, tip, and fees.

  • Saved Card: Include account_id, the system processes payment using the previously saved payment method.

  • 3D Secure : Always include redirect_uri for proper redirection flow in case cards requiring 3DS authentication

  • 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",
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "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
}

Error Response

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Invoice not found"
  }
}

Use Cases

🔄 Use Case 1: Standard Invoice Payment Using Saved Card

Scenario: A guest has a saved card and wants to pay for a service invoice.

Request:

POST /api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/online_payments

Request Body:

{
  "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "redirect_uri": "https://example.com/payment-success",
  "source": 1
}

Response:


{
  "success": true,
  "error": null,
  "invoice_transaction_id": "550e8400-e29b-41d4-a716-446655440123",
  "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.

Request Body:

{
  "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
  "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,
  "invoice_transaction_id": "550e8400-e29b-41d4-a716-446655440123",
  "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.

Request Body:

{
  "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
  "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,
  "invoice_transaction_id": "550e8400-e29b-41d4-a716-446655440123",
  "token_id": "550e8400-e29b-41d4-a716-446655440124"
}

🔐 Use Case 4: Payment with 3D Secure Enforced Card

Scenario: Guest uses a card that requires 3D Secure authentication.

  1. Include redirect_uri in the request.
  2. Receive hosted_payment_uri in the response.
  3. Redirect the guest to complete 3DS authentication.

Request Body:

{
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "redirect_uri": "https://example.com/payment-success",
  "billing_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "country_code": "US",
    "address": "123 Main St",
    "state": "CA",
    "zipcode": "90210",
    "city": "Beverly Hills"
  },
  "source": 1
}

Response Details:

Response:

{
  "success": true,
  "error": null,
  "hosted_payment_uri": "https://secure-payment.zenoti.com/3ds/authenticate?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
}

When 3D Secure authentication is required, the API returns:

  • hosted_payment_uri: If present in the response, this field contains a URL to a hosted payment page. The presence of this field indicates that the issuer is enforcing 3D Secure (3DS) authentication for this transaction.
    Action:
    When hosted_payment_uri is provided, you must redirect the guest (end user) to this URL to complete the 3DS authentication process.

Implementation Flow:

  1. Initial Request: Send payment request with new card details and redirect_uri
  2. 3DS Detection: System detects card requires 3D Secure authentication
  3. Redirect Response: API returns hosted_payment_uri instead of processing payment immediately
  4. Guest Redirect: Redirect guest's browser to the hosted_payment_uri
  5. Authentication: Guest completes 3DS challenge on issuer's secure page
  6. Return: After authentication, guest is redirected back to your redirect_uri with the payment status
  7. Completion: Payment is automatically processed if 3DS authentication succeeds

Important Notes:

  • The payment is not completed until 3DS authentication succeeds
  • Always check for hosted_payment_uri in the response before assuming payment is complete
  • The redirect_uri parameter is mandatory for 3DS-enabled transactions
  • Failed 3DS authentication will result in payment decline

🏠 Use Case 5: Group Invoice Payment by Host

Scenario: The host of a group appointment pays for the entire group invoice using their saved card.

Request:

POST /api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/online_payments

Request Body:

{
  "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "source": 1,
  "redirect_uri": "https://example.com/payment-success"
}

Response:

{
  "success": true,
  "error": null,
  "invoice_transaction_id": "550e8400-e29b-41d4-a716-446655440123",
  "token_id": "550e8400-e29b-41d4-a716-446655440124"
}

🎁 Use Case 6: Group Invoice Payment by Group Member

Scenario: A group member (not the host) wants to surprise the group by paying for everyone's services. Use paying_guest_id to specify a different payer than the invoice host

Request:

POST /api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/online_payments

Request Body:

{
  "account_id": "22BDB5E5-6FD0-57E5-9DC7-C2D643EC5DD5",
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "paying_guest_id": "33CDC6F6-7GE1-68F6-AED8-D3E754FD6EE6",
  "source": 1,
  "tip_amount": 25.00,
  "redirect_uri": "https://example.com/payment-success"
}

Response:

{
  "success": true,
  "error": null,
  "hosted_payment_uri": "https://secure-payment.zenoti.com/3ds/authenticate?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fpayment-success",
}

Common Error Responses

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"
  }
}

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"
  }
}
Language
Credentials
Header
Click Try It! to start a request and see the response here!