Payment Session

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.
Each Payment Session will be valid for 15 minutes only.

End Points

POST

/paymentsessions

GET

/paymentsessions/{paymentsession_id}

Attribute

payments_session_id

string

The Payment Session ID is a unique identifier for the session.

currency

string

The currency of the payment amount, represented by a 3-letter ISO currency code (e.g., INR).

amount

string

Amount with which payment session was created

created_time

long

The timestamp (milliseconds) indicating when the payment session was created.

meta_data

array

Provides metadata for the payment, which can be useful for storing additional information. The maximum size of the array can be 5.
Avoid storing any sensitive information, like bank account numbers or card details, in metadata fields. Instead, use metadata to store non-sensitive identifiers such as:

Order IDs, Customer IDs, and other identifiers for easy reference.
Any additional identifiers or data stored in key-value pairs that may be helpful for future reference.

Show Sub-Attributes

key

string

A unique key used to store metadata for reference. The maximum length of the key can be 20 characters.

value

string

The value associated with the key for reference. The maximum length of the value can be 500 characters.

description

string

The description of the payment session. The maximum length of the description can be 500 characters.

invoice_number

string

The invoice number of the payment session. The maximum length of the invoice number can be 50 characters.

{
    "payments_session_id": "2000000012001",
    "currency": "INR",
    "amount": "100.50",
    "created_time": 1708950672,
    "meta_data": [
        {
            "key": "Key1",
            "value": "Value1"
        }
    ],
    "description": "Payment for Order #12345",
    "invoice_number": "INV-12345"
}

Create Payment Session

This API endpoint allows you to create a new Payment Session in Zoho Payments. Initiate a payment with a specific amount and currency.
OAuth Scope : ZohoPay.payments.CREATE

Arguments

amount

double

(Required)

The amount to be charged, with support for decimal places.

currency

string

(Required)

The currency of the payment amount, represented by a 3-letter ISO currency code (e.g., INR).

meta_data

array

Order IDs, Customer IDs, and other identifiers for easy reference.
Any additional identifiers or data stored in key-value pairs that may be helpful for future reference.

Show Sub-Attributes

key

string

A unique key used to store metadata for reference. The maximum length of the key can be 20 characters.

value

string

The value associated with the key for reference. The maximum length of the value can be 500 characters.

description

string

(Required)

The description of the payment session. The maximum length of the description can be 500 characters.

invoice_number

string

The invoice number of the payment session. The maximum length of the invoice number can be 50 characters.

Query Parameters

account_id

(Required)

The Zoho Payments account ID.

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://payments.zoho.in/api/v1/paymentsessions?account_id=23137556")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://payments.zoho.in/api/v1/paymentsessions?account_id=23137556', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("payments.zoho.in")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/api/v1/paymentsessions?account_id=23137556", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "payments.zoho.in",
  "port": null,
  "path": "/api/v1/paymentsessions?account_id=23137556",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://payments.zoho.in/api/v1/paymentsessions?account_id=23137556' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "amount": 100.5,
    "currency": "INR",
    "meta_data": [
        {
            "key": "Key1",
            "value": "Value1"
        }
    ],
    "description": "Payment for Order #12345",
    "invoice_number": "INV-12345"
}

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

Retrieve Payment Session

This API endpoint allows you to retrieve the details of the latest payment session.
OAuth Scope : ZohoPay.payments.READ

Query Parameters

account_id

(Required)

The Zoho Payments account ID.

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://payments.zoho.in/api/v1/paymentsessions/173000002315107?account_id=23137556")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://payments.zoho.in/api/v1/paymentsessions/173000002315107?account_id=23137556', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("payments.zoho.in")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/api/v1/paymentsessions/173000002315107?account_id=23137556", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "payments.zoho.in",
  "port": null,
  "path": "/api/v1/paymentsessions/173000002315107?account_id=23137556",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://payments.zoho.in/api/v1/paymentsessions/173000002315107?account_id=23137556' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "code": 0,
    "message": "success",
    "payments_session": {
        "payments_session_id": "2000000012001",
        "currency": "INR",
        "amount": "100.50",
        "status": "succeeded",
        "created_time": 1708950672,
        "payments": [
            {
                "payment_id": "173000002314883",
                "status": "succeeded",
                "created_time": 1708950672
            }
        ],
        "meta_data": [
            {
                "key": "Key1",
                "value": "Value1"
            }
        ],
        "description": "Payment for Order #12345",
        "invoice_number": "INV-12345"
    }
}