POS Billing Application Integration

Explore with AI

• Open in ChatGPT
• Open in Claude
• Copy for LLM
• View as Markdown

Integrate your billing application, such as Zoho Invoice, Zoho Books, or any other billing software you use, with Zoho Payments POS to initiate payment sessions, send them to the terminal for customer authentication, and poll for the final transaction status, all through simple REST APIs.

How It Works

Your billing application communicates with the POS device through the Zoho Payments Server. When a customer is ready to check out, the cashier triggers a payment from the billing application, which calls the Zoho Payments API to create a payment session.

The cashier then taps Fetch Payments on the POS device to pull the session. The customer completes the payment using their card or UPI, and the device processes the transaction through the acquiring bank. Once complete, the device reports the result back to the Zoho Payments Server. Your billing application polls the server for the final status and updates the invoice accordingly.

Here’s the end-to-end flow for the Zoho Payments billing application integration:

Get Started

To integrate your billing application with the POS device, you need to create a payment session via the API, have the cashier fetch it on the terminal, and then poll for the transaction result. All requests use HTTPS. Pass the organization ID as the account_id query parameter and your OAuth scope token in the Authorization header.

1. Create a Payment Session

Call the Create Payment Session API with the amount, currency, terminal ID, and payment method. The API returns a unique payments_session_id that tracks this transaction through its full lifecycle.

OAuth Scope: ZohoPay.payments.CREATE

{
  "amount": 100.50,
  "currency": "INR",
  "type": "pos_payment",
  "terminal_id": "1234r5tr",
  "invoice_number": "INV-12345",
  "description": "Payment for Order #12345",
  "meta_data": [
    { "key": "Key1", "value": "Value1" }
  ],
  "payment_method_details": {
    "type": "card"
  }
}

{
  "code": 0,
  "message": "success",
  "payments_session": {
    "payments_session_id": "2000000012001",
    "currency": "INR",
    "amount": "100.50",
    "terminal_id": "1234r5tr",
    "created_time": 1708950672,
    "payment_session_type": "pos_payment",
    "session_status": "in_progress",
    "invoice_number": "INV-12345",
    "description": "Payment for Order #12345",
    "meta_data": [
      { "key": "Key1", "value": "Value1" }
    ]
  }
}

Store the payments_session_id against the corresponding invoice or order in your billing system. This ID is required for all subsequent operations, including status polling, settlement reconciliation, and dispute handling.

Multi-counter setup

If your business operates multiple counters, assign a unique terminal_id to each counter in your billing system. When creating a payment session, always pass the terminal_id of the counter where the customer is currently checking out. This ensures the session appears only on that counter’s terminal and not on others.

2. Fetch the Payment on the Terminal

The cashier taps Fetch Payments on the POS device. The device pulls the active payment session assigned to it over a secure connection, based on the terminal_id specified during session creation. Once fetched, the terminal displays the payment details and is ready for the customer to pay.

3. Process the Payment

The POS device displays the payment details, the customer completes the payment using their preferred method, and the device forwards the authorization request to the processor. Once the processor responds, the device updates the session status on the Zoho Payments server and prints a receipt on success. For a detailed breakdown, refer to Transaction Flow at the Terminal.

While the device processes the payment, your billing application should begin polling the Zoho Payments server for the session status.

4. Poll for Payment Status

Poll the Retrieve Payment Session API every 5 seconds until session_status reaches a final state (succeeded or failed). Once a final status is returned, proceed to update your invoice.

Path Parameters:

{
  "code": 0,
  "message": "success",
  "payments_session": {
    "payments_session_id": "2000000012001",
    "currency": "INR",
    "amount": "100.50",
    "session_status": "in_progress",
    "payment_session_type": "pos_payment",
    "created_time": 1708950672,
    "invoice_number": "INV-12345",
    "description": "Payment for Order #12345"
  }
}

{
  "code": 0,
  "message": "success",
  "payments_session": {
    "payments_session_id": "2000000012001",
    "currency": "INR",
    "amount": "100.50",
    "session_status": "succeeded",
    "payment_session_type": "pos_payment",
    "created_time": 1708950672,
    "invoice_number": "INV-12345",
    "description": "Payment for Order #12345",
    "payments": [
      {
        "payment_id": "173000002314886",
        "status": "succeeded",
        "date": 1758174448,
        "date_formatted": "Sep 18, 2025, 11:17 am",
        "payment_method": {
          "type": "card",
          "type_formatted": "Card"
        }
      }
    ]
  }
}

{
  "code": 0,
  "message": "success",
  "payments_session": {
    "payments_session_id": "2000000012001",
    "currency": "INR",
    "amount": "100.50",
    "session_status": "failed",
    "payment_session_type": "pos_payment",
    "created_time": 1708950672,
    "invoice_number": "INV-12345",
    "description": "Payment for Order #12345",
    "payments": [
      {
        "payment_id": "173000002314886",
        "status": "failed",
        "date": 1758174448,
        "date_formatted": "Sep 18, 2025, 11:17 am",
        "failure_code": "insufficient_funds",
        "payment_method": {
          "type": "card",
          "type_formatted": "Card"
        }
      }
    ]
  }
}

Once you receive a succeeded or failed status, stop polling and update the corresponding invoice in your billing system.

5. Update the Invoice

Once the Retrieve Payment Session API returns a final status (succeeded or failed), use the invoice_number from the response to locate and update the corresponding record in your billing system. This step does not involve any Zoho Payments API call; the action is performed entirely within your own application.