API Docs
/
No Results Found
Customer-Payments

Attribute

payment_id
string
Unique ID of the payment generated by the server. Max-length [2000]
payment_mode
string
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Max-length [100]
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. Format [yyyy-mm-dd]
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. Max-length [100]
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. Max-length [100]
email
string
Email address of the customer involved in 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.
Show Sub-Attributes arrow
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.
Show Sub-Attributes arrow
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.

Example

{ "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", "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.

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. Max-length [100]
amount
double
(Required)
Amount paid in the respective payment.
date
string
(Required)
Date on which payment is made. Format [yyyy-mm-dd]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
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.
Show Sub-Attributes arrow
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.
custom_fields
array
Additional fields for the payments.
Show Sub-Attributes arrow
label
string
Label of the custom field.
value
string
Value of the custom field.
invoice_id
string
(Required)
Invoice ID of the required invoice.
amount_applied
double
(Required)
Amount paid for the invoice.
tax_amount_withheld
double
Amount withheld for tax.
account_id
string
ID of the cash/bank account the payment has to be deposited.
contact_persons
array
IDs of the contact personsthe thank you mail has to be triggered.

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments?organization_id=10234695 -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "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, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " ", "contact_persons": [ "982000000870911", "982000000870915" ] }

Response Example

{ "code": 0, "message": "The payment has been created. <br><code>oauthscope :<span style=\"color:#6C69F3;\"> ZohoBooks.customerpayments.CREATE </span></code>", "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", "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" } ] } }

List Customer Payments

List all the payments made by your customer.
oauthscope : ZohoBooks.customerpayments.READ

Query Parameters

customer_name
Search payments by customer name. Variants: customer_name_startswith and customer_name_contains. Max-len [100]
reference_number
Search payments by reference number. Variants: reference_number_startswith and reference_number_contains. Max-len [100]
date
amount
Search payments by payment amount. Variants: amount_less_than, amount_less_equals, amount_greater_than and amount_greater_equals
notes
Search payments by customer notes. Variants: notes_startswith and notes_contains
payment_mode
Search payments by payment mode. Variants: payment_mode_startswith and payment_mode_contains
filter_by
Filter payments by mode.Allowed Values: PaymentMode.All, PaymentMode.Check, PaymentMode.Cash, PaymentMode.BankTransfer, PaymentMode.Paypal, PaymentMode.CreditCard, PaymentMode.GoogleCheckout, PaymentMode.Credit, PaymentMode.Authorizenet, PaymentMode.BankRemittance, PaymentMode.Payflowpro, PaymentMode.Stripe, PaymentMode.TwoCheckout, PaymentMode.Braintree and PaymentMode.Others
sort_column
search_text
Search payments by reference number or customer name or payment description. Max-length [100]
customer_id
Customer ID of the customer involved in the payment.
organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "customer_payments": [ { "payment_id": "9030000079467", "payment_number": "2", "invoice_number": "INV-384", "date": "2016-06-05", "payment_mode": "cash", "amount": 450, "bcy_amount": 450 }, {...}, {...} ], "page_context": null }

Update a payment

Update an existing payment information.
oauthscope : ZohoBooks.customerpayments.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. Max-length [100]
amount
double
(Required)
Amount paid in the respective payment.
date
string
Date on which payment is made. Format [yyyy-mm-dd]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
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.
Show Sub-Attributes arrow
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.
custom_fields
array
Additional fields for the payments.
Show Sub-Attributes arrow
label
string
Label of the custom field.
value
string
Value of the custom field.
invoice_id
string
(Required)
Invoice ID of the required invoice.
amount_applied
double
(Required)
Amount paid for the invoice.
tax_amount_withheld
double
Amount withheld for tax.
account_id
string
ID of the cash/bank account the payment has to be deposited.

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "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, "custom_fields": [ { "label": "label", "value": 129890 } ], "invoice_id": "90300000079426", "amount_applied": 450, "tax_amount_withheld": 0, "account_id": " " }

Response Example

{ "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", "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.
oauthscope : ZohoBooks.customerpayments.READ

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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", "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.
oauthscope : ZohoBooks.customerpayments.DELETE

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{payment_id}?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The payment has been deleted." }

Refund an excess customer payment

Refund the excess amount paid by the customer.
oauthscope : ZohoBooks.customerpayments.CREATE

Arguments

date
string
(Required)
Date on which payment is made. Format [yyyy-mm-dd]
refund_mode
string
The method of refund. Max-length [50]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
amount
double
(Required)
Amount paid in the respective payment.
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.
from_account_id
string
(Required)
The account from which payment is refunded.
description
string
Description about the payment.

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?organization_id=10234695 -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "from_account_id": " ", "description": "Payment has been added to INV-384" }

Response Example

{ "code": 0, "message": "The refund information for this payment has been saved.", "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" }, {...}, {...} ] }

List refunds of a customer payment

List all the refunds pertaining to an existing customer payment.
oauthscope : ZohoBooks.customerpayments.READ

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The list of refunds of the customer is displayed successfully.", "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "payment_number": "2", "customer_name": "Bowman Furniture", "amount_bcy": 10, "amount_fcy": 10 }, {...}, {...} ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "report_name": "Customer Payments Refund", "sort_column": "created_time", "sort_order": "D" } }

Update a refund

Update the refunded transaction.
oauthscope : ZohoBooks.customerpayments.UPDATE

Arguments

date
string
(Required)
Date on which payment is made. Format [yyyy-mm-dd]
refund_mode
string
The method of refund. Max-length [50]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Max-length [100]
amount
double
(Required)
Amount paid in the respective payment.
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.
description
string
Description about the payment.
from_account_id
string
(Required)
The account from which payment is refunded.

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384", "from_account_id": " " }

Response Example

{ "code": 0, "message": "The refund information has been saved.", "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" }, {...}, {...} ] }

Details of a refund

Obtain details of a particular refund of a customer payment.
oauthscope : ZohoBooks.customerpayments.READ

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The details of the refund are displayed successfully.", "payment_refunds": [ { "payment_refund_id": "3000000003017", "payment_id": "9030000079467", "date": "2016-06-05", "refund_mode": "cash", "reference_number": "INV-384", "amount": 450, "exchange_rate": 1, "description": "Payment has been added to INV-384" }, {...}, {...} ] }

Delete a Refund

Delete refund pertaining to an existing customer payment.
oauthscope : ZohoBooks.customerpayments.DELETE

Query Parameters

organization_id
(Required)
ID of the organization

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/:refund_id?organization_id=10234695 -X DELETE -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "The refund has been deleted." }