API Docs
/
No Results Found
Help Docs
FAQs
Developer Docs
Payments

Payments

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

End Points
Retrieve Payments
Retrieve Payments List

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.
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 arrow
upi
object
Contains UPI details.
Show Sub-Attributes arrow
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 arrow
bank_name
string
The name of the bank used in the net banking transaction.
card
object
Contains card details.
Show Sub-Attributes arrow
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 Card details
Show Sub-Attributes arrow
type
string
The type of payment method. This can be upi, net_banking, and card.
card
object
Contains card details.
Show Sub-Attributes arrow
card_holder_name
string
The name of the cardholder.
last_four_digits
string
The last four digits of the card number.
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).
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 arrow
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.

Example

{ "payment_id": "1987000000724207", "phone": "+91 0000000000", "amount": "200.00", "currency": "INR", "payments_session_id": "1987000000724189", "receipt_email": "xxx@abc.com", "reference_number": "REF-12345", "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": "card", "card": { "card_holder_name": "Akash", "last_four_digits": "3212", "expiry_month": "01", "expiry_year": "26", "brand": "rupay", "funding": "debit" } }, "meta_data": [ { "key": "Key1", "value": "Value1" } ] }

Retrieve Payments

Used to retrieve specific payment details, including records of failed payments.
OAuth Scope : ZohoPay.payments.READ

Query Parameters

account_id
(Required)
The Zoho Payments account ID.

Request Example

Click to copy
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();
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));
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();
curl --request GET \ --url 'https://payments.zoho.in/api/v1/payments/731000001449003?account_id=23137556' \ --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{ "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", "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": "card", "card": { "card_holder_name": "Akash", "last_four_digits": "3212", "expiry_month": "01", "expiry_year": "26", "brand": "rupay", "funding": "debit" } }, "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
(Required)
The Zoho Payments account ID.
status
Status can be : Status.All, Status.Failed, Status.Succeeded, Status.Cancelled, Status.Refunded or Status.Disputed.
filter_by
We can 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
If the given filter_by is ChargeDate.CustomDate, this param is required. (e.g., 2024-08-06 )
to_date
If the given filter_by is ChargeDate.CustomDate, this param is required. (e.g., 2024-08-10 )
payment_method_type
Payment method types can be : all, upi, card or net_banking.
per_page
Indicates the number of payments to list per page. The default value is 25 per page, and the maximum limit is 200.
page
Indicates the page number of the payments list. (e.g., 1 )

Request Example

Click to copy
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();
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));
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();
curl --request GET \ --url 'https://payments.zoho.in/api/v1/payments?account_id=23137556' \ --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{ "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": "card", "card": { "card_holder_name": "Akash", "last_four_digits": "3212", "expiry_month": "01", "expiry_year": "26", "brand": "rupay", "funding": "debit" } } }, {...}, {...} ] }