Customers
The Customer APIs provide access to create and retrieve customer details in Zoho Payments.
End Points
Create Customer
Retrieve Customer List
Retrieve Customer
Attribute
customer_id
string
A unique identifier for the customer.
name
string
Name of the customer.
email
string
Email address of the customer.
phone
string
Phone number associated with the customer.
meta_data
array
Provides metadata for the customer, which can be useful for storing additional information. The maximum size of the array can be 5.
- Customer identifiers for easy reference.
- Any additional identifiers or data stored in key-value pairs that may be helpful for future reference.
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.
{
"customer_id": "1987000000724207",
"name": "Charles",
"email": "charles@example.com",
"phone": "+1 555-0100",
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
]
}
Create Customer
This API endpoint allows you to create a new customer in Zoho Payments.
OAuth Scope : ZohoPay.customers.CREATE
Arguments
name
string
(Required)
Name of the customer.
email
string
(Required)
Email address of the customer.
phone
string
Phone number associated with the customer.
meta_data
array
Provides metadata for the customer, which can be useful for storing additional information. The maximum size of the array can be 5.
- Customer identifiers for easy reference.
- Any additional identifiers or data stored in key-value pairs that may be helpful for future reference.
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.
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.com/api/v1/customers?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.com/api/v1/customers?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.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("POST", "/api/v1/customers?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.com",
"port": null,
"path": "/api/v1/customers?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.com/api/v1/customers?account_id=23137556' \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"name": "Charles",
"email": "charles@example.com",
"phone": "+1 555-0100",
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
]
}
{
"code": 0,
"message": "Customer created",
"customer": {
"customer_id": "1987000000724207",
"name": "Charles",
"email": "charles@example.com",
"phone": "+1 555-0100",
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
]
}
}
Retrieve Customer List
This API endpoint allows you to retrieve all the customer details.
OAuth Scope : ZohoPay.customers.READ
Query Parameters
account_id
(Required)
The Zoho Payments account ID.
filter_by
Filter the customer list using date intervals:
Date.Today, Date.ThisMonth, Date.ThisYear, Date.PreviousMonth, Date.PreviousYear, Date.CustomDate, Date.Last_30_Days. from_date
Required if the parameter filter_by is
Date.CustomDate. (e.g., 2024-08-06 ) to_date
Required if the parameter filter_by is
Date.CustomDate. (e.g., 2024-08-10 ) per_page
Indicates the number of records to list per page. The default value is 25, and the maximum limit is 200.
page
Indicates the page number of the list of records. (e.g.,
1 )OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://payments.zoho.com/api/v1/customers?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.com/api/v1/customers?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.com")
headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }
conn.request("GET", "/api/v1/customers?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.com",
"port": null,
"path": "/api/v1/customers?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.com/api/v1/customers?account_id=23137556' \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"code": 0,
"message": "success",
"customers": [
{
"customer_id": "1987000000724207",
"customer_name": "Charles",
"customer_email": "charles@example.com",
"customer_phone": "+1 555-0100",
"customer_status": "active",
"created_time": 1708950672,
"last_modified_time": 1708950672
},
{...},
{...}
]
}
Retrieve Customer
This API endpoint allows you to retrieve the details of a specific customer.
OAuth Scope : ZohoPay.customers.READ
Query Parameters
account_id
(Required)
The Zoho Payments account ID.
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://payments.zoho.com/api/v1/customers/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.com/api/v1/customers/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.com")
headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }
conn.request("GET", "/api/v1/customers/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.com",
"port": null,
"path": "/api/v1/customers/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.com/api/v1/customers/173000002315107?account_id=23137556' \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"code": 0,
"message": "success",
"customer": {
"customer_id": "1987000000724207",
"name": "Charles",
"email": "charles@example.com",
"phone": "+1 555-0100",
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
],
"payment_methods": [
{
"payment_method_id": "1987000000724209",
"type": "card",
"brand": "visa",
"last_four_digits": "3212",
"expiry_month": "01",
"expiry_year": "26",
"card": {
"card_holder_name": "Charles",
"last_four_digits": "3212",
"expiry_month": "01",
"expiry_year": "26"
}
}
],
"created_time": 1708950672,
"last_modified_time": 1708950672
}
}