Payments

The Payment APIs provide details about a payment transaction, including amounts, currencies, and status.

Download Payments OpenAPI Document

End Points

GET

/payments/{payment_id}

GET

/payments

Attribute

payment_id

string

A unique ID for payments made through Zoho Payments.

phone

string

Phone number associated with the payment.

amount

string

The payment amount.

currency

string

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

payments_session_id

string

An identifier assigned to the payment session. This can be used to track all payments within a specific session.

receipt_email

string

Email address to which the payment receipt will be sent.

reference_number

string

The reference number you provided during payment initiation.

transaction_reference_number

string

A unique ID linked to the transaction to help customers track and identify the payments with their bank.

invoice_number

string

The invoice number of the payment.

amount_captured

string

Amount captured from the transaction, excluding subsequent refunds.

amount_refunded

string

Total refunded amount.

fee_amount

string

Fee amount charged for the payment.

net_tax_amount

string

Net tax amount.

total_fee_amount

string

Total fee amount including all charges and deductions

net_amount

string

Net amount after deductions.

status

string

Status of the payment: initiated, succeeded, failed, canceled, incomplete, refunded, partially_refunded, blocked, or disputed.

statement_descriptor

string

Descriptor shown on the statement to identify the payment.

description

string

A description of the payment.

date

long

Date (milliseconds) on which the payment was processed.

payment_method

object

Payment method is either upi, net_banking, and card

Available payment method

upi

object

Contains UPI details.

Show Sub-Attributes

upi_id

string

The UPI ID associated with the transaction.

channel

string

The UPI channel used for the transaction (e.g., collect, qr, intent).

account_type

string

The type of account linked with the UPI transaction (e.g., bank_account, wallet, card).

net_banking

object

Contains net banking details.

Show Sub-Attributes

bank_name

string

The name of the bank used in the net banking transaction.

card

object

Contains card details.

Show Sub-Attributes

last_four_digits

string

The last four digits of the card number.

card_holder_name

string

The name of the cardholder.

expiry_month

string

The month when the card expires, formatted as MM.

expiry_year

string

The year when the card expires, formatted as YY.

brand

string

The brand of the card (e.g., visa, master_card, rupay).

funding

string

The type of funding for the card (e.g., credit, debit).

Payment method with UPI details

Show Sub-Attributes

type

string

The type of payment method. This can be upi, net_banking, and card.

upi

object

Contains UPI details.

Show Sub-Attributes

upi_id

string

The UPI ID associated with the transaction.

channel

string

The UPI channel or app used for the transaction.

account_type

string

The type of account linked with the UPI transaction.

mandate_id

string

The mandate ID associated with the recurring payment.

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.

{
    "payment_id": "1987000000724207",
    "phone": "+91 0000000000",
    "amount": "200.00",
    "currency": "INR",
    "payments_session_id": "1987000000724189",
    "receipt_email": "xxx@abc.com",
    "reference_number": "REF-12345",
    "transaction_reference_number": "11367820000A",
    "invoice_number": "INV-12345",
    "amount_captured": "200.00",
    "amount_refunded": "100.00",
    "fee_amount": "4.00",
    "net_tax_amount": "0.72",
    "total_fee_amount": "4.72",
    "net_amount": "95.28",
    "status": "partially_refunded",
    "statement_descriptor": "Zoho Payments",
    "description": "Payment for INV-000008",
    "date": 1715163045,
    "payment_method": {
        "type": "upi",
        "upi": {
            "upi_id": "akash@examplebank",
            "channel": "qr",
            "account_type": "bank_account"
        },
        "mandate_id": "216000001494790"
    },
    "meta_data": [
        {
            "key": "Key1",
            "value": "Value1"
        }
    ]
}

Retrieve Payment Details

Used to retrieve details of a specific payment.

Note: For recurring payments, the mandate_id will be returned in the response along with the payment details. To set up recurring payments, refer to the API Document for Mandates.

OAuth Scope : ZohoPay.payments.READ

Path Parameters

payment_id

long

(Required)

A unique ID for payments made through Zoho Payments.

Query Parameters

account_id

long

(Required)

The Zoho Payments account ID.

Request Example

OkHttpClient client = new OkHttpClient();

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

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

HttpResponse<String> response = Unirest.get("https://payments.zoho.in/api/v1/payments/731000001449003?account_id=23137556")
  .header("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .asString();

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

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

const settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://payments.zoho.in/api/v1/payments/731000001449003?account_id=23137556",
  "method": "GET",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

import http.client

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

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

conn.request("GET", "/api/v1/payments/731000001449003?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/payments/731000001449003?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();

const unirest = require("unirest");

const req = unirest("GET", "https://payments.zoho.in/api/v1/payments/731000001449003");

req.query({
  "account_id": "23137556"
});

req.headers({
  "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
});

req.end(function (res) {
  if (res.error) throw new Error(res.error);

  console.log(res.body);
});

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://payments.zoho.in/api/v1/payments/731000001449003',
  qs: {account_id: '23137556'},
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://payments.zoho.in/api/v1/payments/731000001449003?account_id=23137556")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://payments.zoho.in/api/v1/payments/731000001449003?account_id=23137556",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

<?php

$request = new HttpRequest();
$request->setUrl('https://payments.zoho.in/api/v1/payments/731000001449003');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData([
  'account_id' => '23137556'
]);

$request->setHeaders([
  'Authorization' => 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
]);

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://payments.zoho.in/api/v1/payments/731000001449003');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'account_id' => '23137556'
]));

$request->setHeaders([
  'Authorization' => 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

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

{
    "code": 0,
    "message": "success",
    "payment": {
        "payment_id": "1987000000724207",
        "phone": "+91 0000000000",
        "amount": "200.00",
        "currency": "INR",
        "payments_session_id": "1987000000724189",
        "receipt_email": "xxx@abc.com",
        "reference_number": "REF-12345",
        "transaction_reference_number": "11367820000A",
        "invoice_number": "INV-12345",
        "amount_captured": "200.00",
        "amount_refunded": "100.00",
        "fee_amount": "4.00",
        "net_tax_amount": "0.72",
        "total_fee_amount": "4.72",
        "net_amount": "95.28",
        "status": "partially_refunded",
        "statement_descriptor": "Zoho Payments",
        "description": "Payment for INV-000008",
        "date": 1715163045,
        "payment_method": {
            "type": "upi",
            "upi": {
                "upi_id": "akash@examplebank",
                "channel": "qr",
                "account_type": "bank_account"
            },
            "mandate_id": "216000001494790"
        },
        "meta_data": [
            {
                "key": "Key1",
                "value": "Value1"
            }
        ]
    }
}

Retrieve Payments List

Used to retrieve the details of all payments.
OAuth Scope : ZohoPay.payments.READ

Query Parameters

account_id

long

(Required)

The Zoho Payments account ID.

status

string

Status can be: Status.All, Status.Failed, Status.Succeeded, Status.Cancelled, Status.Refunded or Status.Disputed.

filter_by

string

Filter the payments list using date intervals: ChargeDate.Today, ChargeDate.ThisMonth, ChargeDate.ThisYear, ChargeDate.PreviousMonth, ChargeDate.PreviousYear, ChargeDate.CustomDate, ChargeDate.Last_30_Days.

from_date

string

If the given filter_by is ChargeDate.CustomDate, this param is required. (e.g., 2024-08-06 )

to_date

string

If the given filter_by is ChargeDate.CustomDate, this param is required. (e.g., 2024-08-10 )

payment_method_type

string

Payment method types can be: all, upi, card or net_banking.

per_page

integer

Indicates the number of payments to list per page. The default value is 25 per page, and the maximum limit is 200.

page

integer

Indicates the page number of the payments list. (e.g., 1 )

Request Example

OkHttpClient client = new OkHttpClient();

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

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

HttpResponse<String> response = Unirest.get("https://payments.zoho.in/api/v1/payments?account_id=23137556")
  .header("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .asString();

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

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

const settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://payments.zoho.in/api/v1/payments?account_id=23137556",
  "method": "GET",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

import http.client

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

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

conn.request("GET", "/api/v1/payments?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/payments?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();

const unirest = require("unirest");

const req = unirest("GET", "https://payments.zoho.in/api/v1/payments");

req.query({
  "account_id": "23137556"
});

req.headers({
  "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
});

req.end(function (res) {
  if (res.error) throw new Error(res.error);

  console.log(res.body);
});

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://payments.zoho.in/api/v1/payments',
  qs: {account_id: '23137556'},
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://payments.zoho.in/api/v1/payments?account_id=23137556")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://payments.zoho.in/api/v1/payments?account_id=23137556",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

<?php

$request = new HttpRequest();
$request->setUrl('https://payments.zoho.in/api/v1/payments');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData([
  'account_id' => '23137556'
]);

$request->setHeaders([
  'Authorization' => 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
]);

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://payments.zoho.in/api/v1/payments');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'account_id' => '23137556'
]));

$request->setHeaders([
  'Authorization' => 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

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

{
    "code": 0,
    "message": "success",
    "payments": [
        {
            "payment_id": "1987000000724207",
            "amount": "200.00",
            "currency": "INR",
            "payments_session_id": "1987000000724189",
            "receipt_email": "xxx@abc.com",
            "reference_number": "REF-12345",
            "amount_captured": "200.00",
            "amount_refunded": "100.00",
            "fee_amount": "4.00",
            "net_tax_amount": "0.72",
            "total_fee_amount": "4.72",
            "net_amount": "95.28",
            "status": "partially_refunded",
            "statement_descriptor": "Zoho Payments",
            "description": "Payment for INV-000008",
            "date": 1715163045,
            "payment_method": {
                "type": "upi"
            }
        },
        {...},
        {...}
    ]
}