openapi: 3.0.0
info:
  title: In-Person
  description: The In-Person Payments APIs enable end-to-end integration between a Merchant Billing Application and Zoho Payments' in-person acceptance channels. The billing application creates an In-Person Payment Session for a specific amount, currency and acceptance device; the cashier pulls the session on that device and the customer completes the payment using card, UPI, NFC or any other supported method. The billing application then polls the Retrieve Payment Session API to determine the final status of the payment.  <br/>Each Payment Session of type <code>pos_payment</code> is valid for <b>3 minutes</b> only.
  contact: {}
  version: 1.0.0
servers:
  - url: https://payments.zoho.in/api/v1
    description: API Endpoint
tags:
  - name: in-person-payment-sessions
    description: In-Person Payments Module
paths:
  /terminal/paymentsessions:
    post:
      tags:
        - in-person-payment-sessions
      summary: Create Payment Session
      description: This API endpoint allows you to create a new In-Person Payment Session in Zoho Payments. The session is mapped to a specific acceptance device and can be pulled by the cashier on that device to complete the payment.
      parameters:
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pos-payment-session-request'
            examples:
              CreatePosPaymentSession:
                summary: Create Payment Session
                value:
                  amount: 1
                  currency: INR
                  type: pos_payment
                  terminal_id: '87971593'
                  invoice_number: INV-12345
                  description: 'Payment for Order #12345'
                  meta_data:
                    - key: Key1
                      value: Value1
                  payment_method_details:
                    type: upi
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pos-payment-session-create-response'
              examples:
                Initiation:
                  summary: Initiation Response
                  value:
                    code: 0
                    message: success
                    payments_session:
                      payments_session_id: '216000003925007'
                      currency: INR
                      amount: '1.00'
                      session_status: in_progress
                      created_time: 1779361483
                      terminal_id: '87971593'
                      payments_session_type: pos_payment
                      invoice_number: INV-12345
                      description: 'Payment for Order #12345'
                      meta_data:
                        - key: Key1
                          value: Value1
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.payments.CREATE
  /terminal/paymentsessions/{payments_session_id}:
    get:
      tags:
        - in-person-payment-sessions
      summary: Retrieve Payment Session
      description: This API endpoint allows you to retrieve the current state of an In-Person Payment Session. Poll this endpoint every 5 to 10 seconds until the <code>session_status</code> reaches a final state (<code>succeeded</code> or <code>failed</code>). Always treat this API as the source of truth for payment status.
      parameters:
        - name: payments_session_id
          description: The unique identifier of the In-Person Payment Session returned by the Create Payment Session API.
          in: path
          required: true
          schema:
            type: string
          example: '2000000012001'
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pos-payment-session-retrieve-response'
              examples:
                SuccessfulPayment:
                  summary: Successful Payment
                  value:
                    code: 0
                    message: success
                    payments_session:
                      payments_session_id: '216000003925007'
                      currency: INR
                      amount: '1.00'
                      session_status: succeeded
                      created_time: 1779361483
                      terminal_id: '87971593'
                      payments_session_type: pos_payment
                      invoice_number: INV-12345
                      description: 'Payment for Order #12345'
                      payments:
                        - payment_id: '216000003926003'
                          amount: '1.00'
                          status: succeeded
                          payment_method:
                            type: upi
                          date: 1779361502
                      meta_data:
                        - key: Key1
                          value: Value1
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.payments.READ
components:
  parameters:
    account_id:
      name: account_id
      description: The Zoho Payments account ID.
      in: query
      required: true
      schema:
        type: number
        format: long
      example: 23137556
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/pos-payment-session-response'
    payments_session_id:
      description: The In-Person Payment Session ID is a unique identifier for the session and is used for the full lifecycle of the transaction.
      type: string
      example: '216000003925007'
    amount-request:
      description: The transaction amount to be charged on the acceptance device, with support for decimal places.
      type: number
      format: double
      example: 1
    amount-response:
      description: The amount for which the In-Person Payment Session was created.
      type: string
      example: '1.00'
    currency:
      description: The currency of the payment amount, represented by a 3-letter ISO currency code <br>(e.g., <code class="url">INR</code>).
      type: string
      example: INR
    type:
      description: 'The type of the In-Person Payment Session. Accepted value: <code>pos_payment</code>.'
      type: string
      example: pos_payment
    payments_session_type:
      description: 'The type of the In-Person Payment Session. Possible value: <code>pos_payment</code>.'
      type: string
      example: pos_payment
    terminal_id:
      description: The unique identifier of the POS terminal that is mapped to the merchant during onboarding. The session will be pulled by this terminal when the cashier taps <b>Fetch Payments</b>. Required when <code>type</code> is <code>pos_payment</code>.
      type: string
      example: '87971593'
    invoice_number:
      description: The merchant invoice number for reconciliation. The maximum length can be 50 characters.
      type: string
      example: INV-12345
    description:
      description: A free-text description of the payment, shown on receipts and reports. The maximum length can be 500 characters.
      type: string
      example: 'Payment for Order #12345'
    created_time:
      description: The timestamp (in seconds) indicating when the In-Person Payment Session was created.
      type: integer
      format: int64
      example: 1779361483
    session_status:
      description: The current status of the In-Person Payment Session. Possible values are <code>in_progress</code>, <code>succeeded</code> and <code>failed</code>. Continue polling while the status is <code>in_progress</code>; <code>succeeded</code> and <code>failed</code> are final states.
      type: string
      example: in_progress
    payment_method_details:
      description: The payment method that the customer will use on the acceptance device.
      type: object
      required:
        - type
      properties:
        type:
          description: The payment method type. Accepted values are <code>card</code> or <code>upi</code>.
          type: string
          example: upi
    payment_id:
      description: A unique identifier for the payment attempt made through the acceptance device.
      type: string
      example: '216000003926003'
    payment_status:
      description: The status of an individual payment attempt. Possible values are <code>succeeded</code> and <code>failed</code>.
      type: string
      example: succeeded
    payment_amount:
      description: The amount processed for this individual payment attempt.
      type: string
      example: '1.00'
    payment_date:
      description: The timestamp (in seconds) indicating when the payment attempt was processed.
      type: integer
      format: int64
      example: 1779361502
    failure_code:
      description: The failure reason returned by the processor when a payment attempt fails (e.g., <code>generic_decline</code>, <code>insufficient_funds</code>). Present only on failed payment attempts.
      type: string
      example: generic_decline
    failure_category:
      description: The broad category of the failure (e.g., <code>other_errors</code>). Present only on failed payment attempts.
      type: string
      example: other_errors
    payment_method:
      description: Details about the payment method used for the payment attempt.
      type: object
      properties:
        type:
          description: The payment method type used for the payment. Accepted values are <code>card</code> and <code>upi</code>.
          type: string
          example: upi
    payments:
      description: The list of payment attempts associated with the In-Person Payment Session. This array is present once a payment attempt has been made on the acceptance device.
      type: array
      items:
        type: object
        properties:
          payment_id:
            $ref: '#/components/schemas/payment_id'
          amount:
            $ref: '#/components/schemas/payment_amount'
          status:
            $ref: '#/components/schemas/payment_status'
          failure_code:
            $ref: '#/components/schemas/failure_code'
          failure_category:
            $ref: '#/components/schemas/failure_category'
          payment_method:
            $ref: '#/components/schemas/payment_method'
          date:
            $ref: '#/components/schemas/payment_date'
    pos-payment-session-request:
      required:
        - amount
        - currency
        - type
        - terminal_id
        - payment_method_details
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/amount-request'
        currency:
          $ref: '#/components/schemas/currency'
        type:
          $ref: '#/components/schemas/type'
        terminal_id:
          $ref: '#/components/schemas/terminal_id'
        payment_method_details:
          $ref: '#/components/schemas/payment_method_details'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        description:
          $ref: '#/components/schemas/description'
        meta_data:
          $ref: ./common.yml#/components/schemas/meta_data
    pos-payment-session-response:
      type: object
      properties:
        payments_session_id:
          $ref: '#/components/schemas/payments_session_id'
        currency:
          $ref: '#/components/schemas/currency'
        amount:
          $ref: '#/components/schemas/amount-response'
        terminal_id:
          $ref: '#/components/schemas/terminal_id'
        created_time:
          $ref: '#/components/schemas/created_time'
        payments_session_type:
          $ref: '#/components/schemas/payments_session_type'
        session_status:
          $ref: '#/components/schemas/session_status'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        description:
          $ref: '#/components/schemas/description'
        meta_data:
          $ref: ./common.yml#/components/schemas/meta_data
    pos-payment-session-retrieve-payments-session:
      type: object
      properties:
        payments_session_id:
          $ref: '#/components/schemas/payments_session_id'
        currency:
          $ref: '#/components/schemas/currency'
        amount:
          $ref: '#/components/schemas/amount-response'
        session_status:
          $ref: '#/components/schemas/session_status'
        payments_session_type:
          $ref: '#/components/schemas/payments_session_type'
        created_time:
          $ref: '#/components/schemas/created_time'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        description:
          $ref: '#/components/schemas/description'
        payments:
          $ref: '#/components/schemas/payments'
    pos-payment-session-create-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        payments_session:
          $ref: '#/components/schemas/pos-payment-session-response'
    pos-payment-session-retrieve-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        payments_session:
          $ref: '#/components/schemas/pos-payment-session-retrieve-payments-session'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.in/oauth/v2/auth
          scopes:
            ZohoPay.payments.CREATE: Create In-Person Payment Session
            ZohoPay.payments.READ: Fetch In-Person Payment Session Details
