Payments
A payment object describes details regarding a particular customer payment. There can be multiple payments for a single invoice. Multiple invoices can be paid in a single payment as well.
End Points
Create a payment
Update a payment
Retrieve a payment
Delete a payment
Attribute
payment_id
string
Unique ID of the payment generated by the server.
payment_mode
string
Mode through which payment is made. This can be
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refund. Refunds are applicable only for payments whose payment_mode is
autotransaction
. Refunds would be made to the respective card provided by the customer. bank_charges
double
Denotes any additional bank charges.
date
string
Date on which payment is made.
status
string
Status of the payment. It can either be
success
or failure
. reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
string
Description about the payment.
customer_id
string
Customer ID of the customer involved in the payment.
customer_name
string
Name of the customer to whom the invoice is raised.
email
string
Email address of the customer involved in the payment.
autotransaction
object
If the payment mode is
autotransaction
, autotransaction information will be displayed in the autotransaction object. It contains autotransaction_id
, payment_gateway
, gateway_transaction_id
, card_id
, last_four_digits
, expiry_month
and expiry_year
. autotransaction_id
string
Auto-transaction ID generated for the payment made.
payment_gateway
string
Name of the payment gateway associated with payment.
gateway_transaction_id
string
Transaction ID provided by the gateway for the transaction.
gateway_error_message
string
Gateway error message for a failed transaction.
card_id
string
Card ID of the card associated with the transaction.
last_four_digits
integer
Last four digits of the card.
expiry_month
integer
Expiry month of the card.
expiry_year
integer
Expiry year of the card.
invoices
array
List of invoices associated with the payment. Each invoice object contains
invoice_id
, invoice_number
, date
, invoice_amount
, amount_applied
and balance_amount
. invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Unique ID (starts with INV) of an invoice.
date
Date on which the invoice was raised.
invoice_amount
double
Total amount raised for the invoice.
amount_applied
double
Amount paid for the invoice.
balance_amount
double
Unpaid amount of the invoice.
currency_code
string
Currency code in which the payment is made.
currency_symbol
string
Customer's currency symbol.
custom_fields
array
Additional fields for the payments.
index
integer
Index of the custom field. It can hold any value from 1 to 10.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
{
"payment_id": "9030000079467",
"payment_mode": "cash",
"amount": 450,
"amount_refunded": 50,
"bank_charges": 10,
"date": "2016-06-05",
"status": "success",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"customer_id": "903000000000099",
"customer_name": "Bowman Furniture",
"email": "benjamin.george@bowmanfurniture.com",
"autotransaction": {
"autotransaction_id": "90300000079465",
"payment_gateway": "payflow_pro",
"gateway_transaction_id": "B10E6E0F31BD",
"gateway_error_message": "Gateway error message for a failed transaction.",
"card_id": "90300000079226",
"last_four_digits": 1111,
"expiry_month": 9,
"expiry_year": 2030
},
"invoices": [
{
"invoice_id": "90300000079426",
"invoice_number": "INV-384",
"date": "2016-06-05",
"invoice_amount": 450,
"amount_applied": 450,
"balance_amount": 0
}
],
"currency_code": "USD",
"currency_symbol": "$",
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
]
}
Create a payment
Create a new payment.
OAuth Scope : ZohoSubscriptions.payments.CREATE
Arguments
customer_id
string
(Required)
Customer ID of the customer involved in the payment.
payment_mode
string
(Required)
Mode through which payment is made. This can be
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. amount
double
(Required)
Amount paid in the respective payment.
date
string
Date on which payment is made.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
string
Description about the payment.
invoices
array
List of invoices associated with the payment. Each invoice object contains
invoice_id
, invoice_number
, date
, invoice_amount
, amount_applied
and balance_amount
. invoice_id
string
(Required)
Invoice ID of the required invoice.
amount_applied
double
(Required)
Amount paid for the invoice.
exchange_rate
double
, default is 1
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
double
Denotes any additional bank charges.
tax_account_id
string
Unique ID of the account which was used for transaction.
account_id
string
Unique ID of the account.
custom_fields
array
Additional fields for the payments.
label
string
Label of the custom field.
value
string
Value of the custom field.
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/payments"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;
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://www.zohoapis.com/billing/v1/payments")
.post(body)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'POST',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
'content-type': 'application/json'
},
body: '{"field1":"value1","field2":"value2"}'
};
fetch('https://www.zohoapis.com/billing/v1/payments', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("POST", "/billing/v1/payments", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "POST",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/payments",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"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://www.zohoapis.com/billing/v1/payments \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"customer_id": "903000000000099",
"payment_mode": "cash",
"amount": 450,
"date": "2016-06-05",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"invoices": [
{
"invoice_id": "90300000079426",
"amount_applied": 450
}
],
"exchange_rate": 1,
"bank_charges": 10,
"tax_account_id": "903000000000370",
"account_id": "903000000000361",
"custom_fields": [
{
"label": "label",
"value": 129890
}
]
}
{
"code": 0,
"message": "The payment has been created.",
"payment": {
"payment_id": "9030000079467",
"payment_mode": "cash",
"amount": 450,
"amount_refunded": 50,
"bank_charges": 10,
"date": "2016-06-05",
"status": "success",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"customer_id": "903000000000099",
"customer_name": "Bowman Furniture",
"email": "benjamin.george@bowmanfurniture.com",
"autotransaction": {
"autotransaction_id": "90300000079465",
"payment_gateway": "payflow_pro",
"gateway_transaction_id": "B10E6E0F31BD",
"gateway_error_message": "Gateway error message for a failed transaction.",
"card_id": "90300000079226",
"last_four_digits": 1111,
"expiry_month": 9,
"expiry_year": 2030
},
"invoices": [
{
"invoice_id": "90300000079426",
"invoice_number": "INV-384",
"date": "2016-06-05",
"invoice_amount": 450,
"amount_applied": 450,
"balance_amount": 0
}
],
"currency_code": "USD",
"currency_symbol": "$",
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
]
}
}
Update a payment
Update an existing payment information.
OAuth Scope : ZohoSubscriptions.payments.UPDATE
Arguments
customer_id
string
(Required)
Customer ID of the customer involved in the payment.
payment_mode
string
(Required)
Mode through which payment is made. This can be
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. amount
double
(Required)
Amount paid in the respective payment.
date
string
Date on which payment is made.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
string
Description about the payment.
invoices
array
(Required)
List of invoices associated with the payment. Each invoice object contains
invoice_id
, invoice_number
, date
, invoice_amount
, amount_applied
and balance_amount
. invoice_id
string
(Required)
Invoice ID of the required invoice.
amount_applied
double
(Required)
Amount paid for the invoice.
exchange_rate
double
, default is 1
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
double
Denotes any additional bank charges.
tax_account_id
string
Unique ID of the account which was used for transaction.
account_id
string
Unique ID of the account.
custom_fields
array
Additional fields for the payments.
label
string
Label of the custom field.
value
string
Value of the custom field.
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/payments/9030000079467"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;
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://www.zohoapis.com/billing/v1/payments/9030000079467")
.put(body)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'PUT',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
'content-type': 'application/json'
},
body: '{"field1":"value1","field2":"value2"}'
};
fetch('https://www.zohoapis.com/billing/v1/payments/9030000079467', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("PUT", "/billing/v1/payments/9030000079467", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "PUT",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/payments/9030000079467",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"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 PUT \
--url https://www.zohoapis.com/billing/v1/payments/9030000079467 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"customer_id": "903000000000099",
"payment_mode": "cash",
"amount": 450,
"date": "2016-06-05",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"invoices": [
{
"invoice_id": "90300000079426",
"amount_applied": 450
}
],
"exchange_rate": 1,
"bank_charges": 10,
"tax_account_id": "903000000000370",
"account_id": "903000000000361",
"custom_fields": [
{
"label": "label",
"value": 129890
}
]
}
{
"code": 0,
"message": "The payment details have been updated.",
"payment": {
"payment_id": "9030000079467",
"payment_mode": "cash",
"amount": 450,
"amount_refunded": 50,
"bank_charges": 10,
"date": "2016-06-05",
"status": "success",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"customer_id": "903000000000099",
"customer_name": "Bowman Furniture",
"email": "benjamin.george@bowmanfurniture.com",
"autotransaction": {
"autotransaction_id": "90300000079465",
"payment_gateway": "payflow_pro",
"gateway_transaction_id": "B10E6E0F31BD",
"gateway_error_message": "Gateway error message for a failed transaction.",
"card_id": "90300000079226",
"last_four_digits": 1111,
"expiry_month": 9,
"expiry_year": 2030
},
"invoices": [
{
"invoice_id": "90300000079426",
"invoice_number": "INV-384",
"date": "2016-06-05",
"invoice_amount": 450,
"amount_applied": 450,
"balance_amount": 0
}
],
"currency_code": "USD",
"currency_symbol": "$",
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
]
}
}
Retrieve a payment
Details of an existing payment.
OAuth Scope : ZohoSubscriptions.payments.READ
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/payments/9030000079467"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/payments/9030000079467")
.get()
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'GET',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/payments/9030000079467', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("GET", "/billing/v1/payments/9030000079467", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "GET",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/payments/9030000079467",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"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://www.zohoapis.com/billing/v1/payments/9030000079467 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "success",
"payment": {
"payment_id": "9030000079467",
"payment_mode": "cash",
"amount": 450,
"amount_refunded": 50,
"bank_charges": 10,
"date": "2016-06-05",
"status": "success",
"reference_number": "INV-384",
"description": "Payment has been added to INV-384",
"customer_id": "903000000000099",
"customer_name": "Bowman Furniture",
"email": "benjamin.george@bowmanfurniture.com",
"autotransaction": {
"autotransaction_id": "90300000079465",
"payment_gateway": "payflow_pro",
"gateway_transaction_id": "B10E6E0F31BD",
"gateway_error_message": "Gateway error message for a failed transaction.",
"card_id": "90300000079226",
"last_four_digits": 1111,
"expiry_month": 9,
"expiry_year": 2030
},
"invoices": [
{
"invoice_id": "90300000079426",
"invoice_number": "INV-384",
"date": "2016-06-05",
"invoice_amount": 450,
"amount_applied": 450,
"balance_amount": 0
}
],
"currency_code": "USD",
"currency_symbol": "$",
"custom_fields": [
{
"index": 1,
"value": 129890,
"label": "label",
"data_type": "text"
}
]
}
}
Delete a payment
Delete an existing payment.
OAuth Scope : ZohoSubscriptions.payments.DELETE
headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/payments/9030000079467"
type: DELETE
headers: headers_data
connection: <connection_name>
]
info response;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://www.zohoapis.com/billing/v1/payments/9030000079467")
.delete(null)
.addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
const options = {
method: 'DELETE',
headers: {
'X-com-zoho-subscriptions-organizationid': '10234695',
Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
}
};
fetch('https://www.zohoapis.com/billing/v1/payments/9030000079467', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import http.client
conn = http.client.HTTPSConnection("www.zohoapis.com")
headers = {
'X-com-zoho-subscriptions-organizationid': "10234695",
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
conn.request("DELETE", "/billing/v1/payments/9030000079467", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
const http = require("https");
const options = {
"method": "DELETE",
"hostname": "www.zohoapis.com",
"port": null,
"path": "/billing/v1/payments/9030000079467",
"headers": {
"X-com-zoho-subscriptions-organizationid": "10234695",
"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 DELETE \
--url https://www.zohoapis.com/billing/v1/payments/9030000079467 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'X-com-zoho-subscriptions-organizationid: 10234695'
{
"code": 0,
"message": "The payment has been deleted."
}