openapi: 3.0.0
info:
  title: Payment Session
  description: The Payment Session represents a single payment initiation using Zoho Payments. It includes key details such as the session ID, amount, currency, and the time when the session was created. <br/>Each Payment Session will be valid for <b>15 minutes</b> only.
  contact: {}
  version: 1.0.0
servers:
  - url: https://payments.zoho.com/api/v1
    description: API Endpoint
tags:
  - name: payment-session
    description: Payment Session Module
paths:
  /paymentsessions:
    post:
      tags:
        - payment-session
      summary: Create Payment Session
      description: This API endpoint allows you to create a new Payment Session in Zoho Payments. Initiate a payment with a specific amount and currency.
      parameters:
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-session-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-session-create-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.payments.CREATE
  /paymentsessions/{payments_session_id}:
    get:
      tags:
        - payment-session
      summary: Retrieve Payment Session
      description: This API endpoint allows you to retrieve the details of the latest payment session.
      parameters:
        - name: payments_session_id
          description: The Payment Session ID is a unique identifier for the session.
          in: path
          required: true
          schema:
            type: number
            format: long
          example: 173000002315107
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-session-payment-response'
      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/payment-session-response'
    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'
        created_time:
          $ref: '#/components/schemas/created-time'
        expiry_time:
          $ref: '#/components/schemas/expiry-time'
        meta_data:
          $ref: ./common.yml#/components/schemas/meta_data
        description:
          $ref: '#/components/schemas/description'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        reference_number:
          $ref: '#/components/schemas/reference_number'
        max_retry_count:
          $ref: '#/components/schemas/max-retry-count'
        access_key:
          $ref: '#/components/schemas/access-key'
        configurations:
          $ref: '#/components/schemas/configurations'
    amount:
      description: The amount for which the payment session was created.
      type: string
      example: '100.50'
    currency:
      description: |-
        Currency of the payment amount, represented by a <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank" rel="noopener noreferrer">3-letter ISO currency code</a> (e.g., <code class="url">USD</code>).<br> <details> <summary class="link"><span class="show-hide-attribute-text" data-showhide="Show list of supported currencies">Show list of supported currencies</span> <img src="/us/payments/api/v1/images/dropdown-arrow.svg" class="arrow-icon" alt="arrow" width="9px" height="9px"> </summary> <input type="text" id="currencySearchPaymentSession1" placeholder="Search currency code..." style="margin:10px 0;padding:5px;width:100%;box-sizing:border-box;"> <div id="currencyGrid1" style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; max-height: 300px; overflow-y: auto; font-family: monospace;"> <span>USD</span><span>EUR</span><span>GBP</span><span>INR</span> <span>AUD</span><span>CAD</span><span>JPY</span><span>CNY</span> <span>NZD</span><span>SGD</span><span>CHF</span><span>SEK</span> <span>NOK</span><span>DKK</span><span>ZAR</span><span>HKD</span> <span>MXN</span><span>BRL</span><span>RUB</span><span>KRW</span> <span>IDR</span><span>MYR</span><span>THB</span><span>PHP</span> <span>VND</span><span>TRY</span><span>PLN</span><span>CZK</span> <span>HUF</span><span>ILS</span><span>SAR</span><span>AED</span> <span>EGP</span><span>PKR</span><span>BDT</span><span>LKR</span> <span>NPR</span><span>UAH</span><span>KZT</span><span>QAR</span> <span>OMR</span><span>KWD</span><span>BHD</span><span>JOD</span> <span>NGN</span><span>GHS</span><span>ARS</span><span>CLP</span> <span>COP</span><span>PEN</span><span>UYU</span><span>BOB</span> <span>VES</span><span>DZD</span><span>MAD</span><span>TND</span> <span>XOF</span><span>XAF</span><span>XCD</span><span>XPF</span> <span>MMK</span><span>MNT</span><span>LAK</span><span>KHR</span> <span>BTN</span><span>MVR</span><span>SCR</span><span>SYP</span> <span>SDG</span><span>ETB</span><span>RWF</span><span>BIF</span> <span>ZMW</span><span>ZWL</span><span>AOA</span><span>MWK</span> <span>MZN</span><span>GNF</span><span>DJF</span><span>UGX</span> <span>TZS</span><span>LSL</span><span>SZL</span><span>GMD</span> <span>SLL</span><span>XDR</span><span>FJD</span><span>WST</span> <span>TOP</span><span>PGK</span><span>VUV</span><span>KYD</span> <span>BBD</span><span>TTD</span><span>BSD</span><span>HTG</span> <span>JMD</span><span>ANG</span><span>AWG</span><span>SRD</span> <span>GYD</span><span>BZD</span><span>BMD</span><span>BAM</span> <span>MAD</span><span>MDL</span><span>MKD</span><span>ISK</span> <span>GEL</span><span>AZN</span><span>AMD</span><span>KGS</span> <span>TJS</span><span>UZS</span><span>MGA</span><span>AOA</span> </div>
        <script> document.getElementById("currencySearchPaymentSession1").addEventListener("input", function() { const filter = this.value.toUpperCase(); const spans = document.getElementById("currencyGrid1").getElementsByTagName("span"); let matchFound = false;  for (let i = 0; i < spans.length; i++) { const txtValue = spans[i].textContent || spans[i].innerText; const isVisible = txtValue.toUpperCase().includes(filter); spans[i].style.display = isVisible ? "" : "none"; if (isVisible) { matchFound = true;  } } }); </script> </details>
      type: string
      example: USD
    description:
      description: The description of the payment session. The maximum length of the description can be 500 characters.
      type: string
      example: 'Payment for Order #12345'
    invoice_number:
      description: The invoice number of the payment session. The maximum length of the invoice number can be 50 characters.
      type: string
      example: INV-12345
    reference_number:
      description: A reference to identify the transaction. The maximum length can be 50 characters.
      type: string
      example: reference_123
    max-retry-count:
      description: The maximum number of payment attempts allowed for this session. Accepted values are between 1 and 5. If not provided, the default retry count is applied.
      type: integer
      minimum: 1
      maximum: 5
      example: 3
    created-time:
      description: The timestamp (milliseconds) indicating when the payment session was created.
      type: integer
      format: int64
      example: 1708950672
    expiry-time:
      description: The timestamp (seconds) indicating when the payment session will expire.
      type: integer
      format: int64
      example: 1708951572
    payments-session-id:
      description: The Payment Session ID is a unique identifier for the session.
      type: string
      example: '1987000000724213'
    amount-response:
      description: Amount with which payment session was created
      type: string
      example: '100.50'
    status:
      description: Payment Session status is either <code>failed</code>, <code>created</code>, <code>in_progress</code>, and <code>succeeded</code>.
      type: string
      example: succeeded
    payment_id:
      description: Payment ID
      type: string
      example: '1987000000724215'
    payments:
      description: List of Payments in the Session
      type: array
      items:
        type: object
        properties:
          payment_id:
            $ref: '#/components/schemas/payment_id'
          status:
            $ref: '#/components/schemas/status'
          created_time:
            $ref: '#/components/schemas/created-time'
    payments_session:
      description: Payment session
      type: object
      properties:
        payments_session_id:
          $ref: '#/components/schemas/payments-session-id'
        currency:
          description: |-
            Currency of the payment amount, represented by a <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank" rel="noopener noreferrer">3-letter ISO currency code</a> (e.g., <code class="url">USD</code>).<br> <details> <summary class="link"><span class="show-hide-attribute-text" data-showhide="Show list of supported currencies">Show list of supported currencies</span> <img src="/us/payments/api/v1/images/dropdown-arrow.svg" class="arrow-icon" alt="arrow" width="9px" height="9px"> </summary> <input type="text" id="currencySearchPaymentSession2" placeholder="Search currency code..." style="margin:10px 0;padding:5px;width:100%;box-sizing:border-box;"> <div id="currencyGrid2" style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; max-height: 300px; overflow-y: auto; font-family: monospace;"> <span>USD</span><span>EUR</span><span>GBP</span><span>INR</span> <span>AUD</span><span>CAD</span><span>JPY</span><span>CNY</span> <span>NZD</span><span>SGD</span><span>CHF</span><span>SEK</span> <span>NOK</span><span>DKK</span><span>ZAR</span><span>HKD</span> <span>MXN</span><span>BRL</span><span>RUB</span><span>KRW</span> <span>IDR</span><span>MYR</span><span>THB</span><span>PHP</span> <span>VND</span><span>TRY</span><span>PLN</span><span>CZK</span> <span>HUF</span><span>ILS</span><span>SAR</span><span>AED</span> <span>EGP</span><span>PKR</span><span>BDT</span><span>LKR</span> <span>NPR</span><span>UAH</span><span>KZT</span><span>QAR</span> <span>OMR</span><span>KWD</span><span>BHD</span><span>JOD</span> <span>NGN</span><span>GHS</span><span>ARS</span><span>CLP</span> <span>COP</span><span>PEN</span><span>UYU</span><span>BOB</span> <span>VES</span><span>DZD</span><span>MAD</span><span>TND</span> <span>XOF</span><span>XAF</span><span>XCD</span><span>XPF</span> <span>MMK</span><span>MNT</span><span>LAK</span><span>KHR</span> <span>BTN</span><span>MVR</span><span>SCR</span><span>SYP</span> <span>SDG</span><span>ETB</span><span>RWF</span><span>BIF</span> <span>ZMW</span><span>ZWL</span><span>AOA</span><span>MWK</span> <span>MZN</span><span>GNF</span><span>DJF</span><span>UGX</span> <span>TZS</span><span>LSL</span><span>SZL</span><span>GMD</span> <span>SLL</span><span>XDR</span><span>FJD</span><span>WST</span> <span>TOP</span><span>PGK</span><span>VUV</span><span>KYD</span> <span>BBD</span><span>TTD</span><span>BSD</span><span>HTG</span> <span>JMD</span><span>ANG</span><span>AWG</span><span>SRD</span> <span>GYD</span><span>BZD</span><span>BMD</span><span>BAM</span> <span>MAD</span><span>MDL</span><span>MKD</span><span>ISK</span> <span>GEL</span><span>AZN</span><span>AMD</span><span>KGS</span> <span>TJS</span><span>UZS</span><span>MGA</span><span>AOA</span> </div>
            <script> document.getElementById("currencySearchPaymentSession2").addEventListener("input", function() { let filter = this.value.toUpperCase(); let spans = document.getElementById("currencyGrid2").getElementsByTagName("span"); let matchFound = false;  for (let i = 0; i < spans.length; i++) { let txtValue = spans[i].textContent || spans[i].innerText; let isVisible = txtValue.toUpperCase().includes(filter); spans[i].style.display = isVisible ? "" : "none"; if (isVisible) { matchFound = true;  } } }); </script> </details>
          type: string
          example: USD
        amount:
          $ref: '#/components/schemas/amount-response'
        status:
          $ref: '#/components/schemas/status'
        created_time:
          $ref: '#/components/schemas/created-time'
        expiry_time:
          $ref: '#/components/schemas/expiry-time'
        payments:
          $ref: '#/components/schemas/payments'
        meta_data:
          $ref: ./common.yml#/components/schemas/meta_data
        description:
          $ref: '#/components/schemas/description'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        reference_number:
          $ref: '#/components/schemas/reference_number'
        max_retry_count:
          $ref: '#/components/schemas/max-retry-count'
        configurations:
          $ref: '#/components/schemas/configurations'
    payment-session-request:
      required:
        - amount
        - currency
        - description
      type: object
      properties:
        amount:
          description: The amount to be charged, with support for decimal places.
          type: number
          format: double
          example: 100.5
        currency:
          description: |-
            Currency of the payment amount, represented by a <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank" rel="noopener noreferrer">3-letter ISO currency code</a> (e.g., <code class="url">USD</code>).<br> <details> <summary class="link"><span class="show-hide-attribute-text" data-showhide="Show list of supported currencies">Show list of supported currencies</span> <img src="/us/payments/api/v1/images/dropdown-arrow.svg" class="arrow-icon" alt="arrow" width="9px" height="9px"> </summary> <input type="text" id="currencySearchPaymentSession3" placeholder="Search currency code..." style="margin:10px 0;padding:5px;width:100%;box-sizing:border-box;"> <div id="currencyGrid3" style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; max-height: 300px; overflow-y: auto; font-family: monospace;"> <span>USD</span><span>EUR</span><span>GBP</span><span>INR</span> <span>AUD</span><span>CAD</span><span>JPY</span><span>CNY</span> <span>NZD</span><span>SGD</span><span>CHF</span><span>SEK</span> <span>NOK</span><span>DKK</span><span>ZAR</span><span>HKD</span> <span>MXN</span><span>BRL</span><span>RUB</span><span>KRW</span> <span>IDR</span><span>MYR</span><span>THB</span><span>PHP</span> <span>VND</span><span>TRY</span><span>PLN</span><span>CZK</span> <span>HUF</span><span>ILS</span><span>SAR</span><span>AED</span> <span>EGP</span><span>PKR</span><span>BDT</span><span>LKR</span> <span>NPR</span><span>UAH</span><span>KZT</span><span>QAR</span> <span>OMR</span><span>KWD</span><span>BHD</span><span>JOD</span> <span>NGN</span><span>GHS</span><span>ARS</span><span>CLP</span> <span>COP</span><span>PEN</span><span>UYU</span><span>BOB</span> <span>VES</span><span>DZD</span><span>MAD</span><span>TND</span> <span>XOF</span><span>XAF</span><span>XCD</span><span>XPF</span> <span>MMK</span><span>MNT</span><span>LAK</span><span>KHR</span> <span>BTN</span><span>MVR</span><span>SCR</span><span>SYP</span> <span>SDG</span><span>ETB</span><span>RWF</span><span>BIF</span> <span>ZMW</span><span>ZWL</span><span>AOA</span><span>MWK</span> <span>MZN</span><span>GNF</span><span>DJF</span><span>UGX</span> <span>TZS</span><span>LSL</span><span>SZL</span><span>GMD</span> <span>SLL</span><span>XDR</span><span>FJD</span><span>WST</span> <span>TOP</span><span>PGK</span><span>VUV</span><span>KYD</span> <span>BBD</span><span>TTD</span><span>BSD</span><span>HTG</span> <span>JMD</span><span>ANG</span><span>AWG</span><span>SRD</span> <span>GYD</span><span>BZD</span><span>BMD</span><span>BAM</span> <span>MAD</span><span>MDL</span><span>MKD</span><span>ISK</span> <span>GEL</span><span>AZN</span><span>AMD</span><span>KGS</span> <span>TJS</span><span>UZS</span><span>MGA</span><span>AOA</span> </div>
            <script> document.getElementById("currencySearchPaymentSession3").addEventListener("input", function() { const filter = this.value.toUpperCase(); const spans = document.getElementById("currencyGrid3").getElementsByTagName("span"); let matchFound = false;  for (let i = 0; i < spans.length; i++) { const txtValue = spans[i].textContent || spans[i].innerText; const isVisible = txtValue.toUpperCase().includes(filter); spans[i].style.display = isVisible ? "" : "none"; if (isVisible) { matchFound = true;  } } }); </script> </details>
          type: string
          example: USD
        expires_in:
          description: The expiration time for the payment session in seconds. The value must be between 300 (5 minutes) and 900 (15 minutes). Default expiry is 900 seconds (15 minutes).
          type: integer
          minimum: 300
          maximum: 900
          example: 900
        meta_data:
          $ref: ./common.yml#/components/schemas/meta_data
        description:
          $ref: '#/components/schemas/description'
        invoice_number:
          $ref: '#/components/schemas/invoice_number'
        reference_number:
          $ref: '#/components/schemas/reference_number'
        configurations:
          $ref: '#/components/schemas/configurations'
        max_retry_count:
          $ref: '#/components/schemas/max-retry-count'
    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/payment-session-response'
    payment-session-payment-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        payments_session:
          $ref: '#/components/schemas/payments_session'
    configurations:
      description: Allows you to customize the payment experience for your customers.
      type: object
      properties:
        allowed_payment_methods:
          description: A list of payment methods allowed for this payment session. Accepted values are <code>card</code>, <code>ach_debit</code>.
          type: array
          items:
            type: string
          example:
            - ach_debit
            - card
        hosted_checkout_parameters:
          $ref: '#/components/schemas/hosted-checkout-parameters'
    access-key:
      description: Present when <code>configurations.hosted_checkout_parameters</code> was supplied at creation. Use this key in the Hosted Pages URL path (<code>hostedpages/{access_key}</code>) to open the checkout page.
      type: string
      readOnly: true
      example: ZWFybmVzdGVuY3J5cHRlZHRva2Vu
    hosted-checkout-parameters:
      description: Hosted Pages settings. When included, the create response includes an <code>access_key</code> to open the hosted checkout.
      type: object
      required:
        - success_url
        - failure_url
        - description
      properties:
        phone_country_code:
          type: string
          description: ISO country code for the customer phone (e.g. <code>IN</code> for India).
          example: IN
        phone:
          type: string
          description: Customer phone number.
          example: '5551234567'
        name:
          type: string
          description: Customer name.
          example: Charles
        email:
          type: string
          format: email
          description: Customer email address.
          example: xxx@abc.com
        description:
          type: string
          maxLength: 500
          description: Displayed to the customer on the hosted checkout page.
          example: 'Payment for Order #12345'
        success_url:
          type: string
          format: uri
          maxLength: 1000
          description: HTTPS URL to redirect the customer after a successful payment.
          example: https://example.com/success
        failure_url:
          type: string
          format: uri
          maxLength: 1000
          description: HTTPS URL to redirect after a failed payment.
          example: https://example.com/failure
        udf1:
          type: string
          maxLength: 1000
          description: Optional user-defined field.
          example: example_udf_1
        udf2:
          type: string
          maxLength: 1000
          description: Optional user-defined field.
          example: example_udf_2
        udf3:
          type: string
          maxLength: 1000
          description: Optional user-defined field.
          example: example_udf_3
        udf4:
          type: string
          maxLength: 1000
          description: Optional user-defined field.
          example: example_udf_4
        udf5:
          type: string
          maxLength: 1000
          description: Optional user-defined field.
          example: example_udf_5
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoPay.payments.CREATE: Create Payment Session
            ZohoPay.payments.READ: Fetch Payments Details
