API Docs
/
No Results Found
FAQ
Help Docs
All Resources
Customer Payments

Customer 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.

Possible error codes:
Error CodeMessage
3004The Customer field can neither be blank nor incorrect. Please enter a correct Customer
9521Partial payment for retainer invoice is not allowed. Please record the full payment
9523Payment amount made to retainer invoice cannot be changed. You could instead delete it and add it back
24016The amount entered is more than the balance due for this invoice

End Points
Create a payment
List Customer Payments
Update a payment
Retrieve a payment
Delete a payment
Refund an excess customer payment
List refunds of a customer payment
Update a refund
Details of a refund
Delete a Refund

Attribute

payment_id
string
Unique ID of the payment generated by the server. Maximum length allowed [2000]
payment_mode
string
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others. Maximum length [100]
amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refunded. 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. Date 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. Maximum length of the reference number [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. Maximum length [100]
email
string
Email address of the customer involved in the payment.
invoices
array
Invoice related to a payment
Show Sub-Attributes arrow
invoice_id
string
Invoice ID of the required invoice.
invoice_payment_id
string
Payment ID of the 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
Custom fields for a payment received.
Show Sub-Attributes arrow
customfield_id
long
Unique ID of the custom field
data_type
string
Data type of the custom field
index
integer
The index of the custom field
label
string
Name of the custom field
show_on_pdf
boolean
Enable/Disable show this custom field on pdf for that invoice
show_in_all_pdf
Enable/Disable show this custom field on all the pdf
value
integer
Value 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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] }

Create a payment

Create a new payment.
oauthscope : ZohoInvoice.customerpayments.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. Maximum length [100]
amount
double
(Required)
Amount paid in the respective payment.
date
string
(Required)
Date on which payment is made. Date 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. Maximum length of the reference number [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
Custom fields for a payment received.
Show Sub-Attributes arrow
label
string
Name of the custom field
value
integer
Value of the custom field

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -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": "Record Number", "value": 23 } ] }

Response Example

{ "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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

List Customer Payments

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

Query Parameters

customer_name
Search payments by customer name. Variants: customer_name_startswith and customer_name_contains. Maximum length [100]
reference_number
Search payments by reference number. Variants: reference_number_startswith and reference_number_contains. Maximum length [100]
date
Date on which payment is made. Date Format [yyyy-mm-dd]
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
Sort based on selected column
search_text
Search payments by reference number or customer name or payment description. Maximum length [100]

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments -H "X-com-zoho-invoice-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Update a payment

Update an existing payment information.
oauthscope : ZohoInvoice.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. Maximum length [100]
amount
double
(Required)
Amount paid in the respective payment.
date
string
(Required)
Date on which payment is made. Date 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. Maximum length of the reference number [100]
description
string
Description about the payment.
invoices
array
(Required)
Invoice associated to a payment
Show Sub-Attributes arrow
invoice_id
string
(Required)
Invoice ID of the required invoice.
invoice_payment_id
string
Payment ID of the 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 to support payment information
Show Sub-Attributes arrow
label
string
Name of the custom field
value
integer
Value of the custom field

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -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", "invoice_payment_id": "27161000000203281", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "custom_fields": [ { "label": "Record Number", "value": 23 } ] }

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": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

Retrieve a payment

Details of an existing payment.
oauthscope : ZohoInvoice.customerpayments.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -H "X-com-zoho-invoice-organizationid: 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", "online_transaction_id": "", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "test@zylker.org", "invoices": [ { "invoice_id": "90300000079426", "invoice_payment_id": "27161000000203281", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "customfield_id": 439910000000236000, "data_type": "number", "index": 1, "label": "Record Number", "show_on_pdf": true, "show_in_all_pdf": true, "value": 23 } ] } }

Delete a payment

Delete an existing payment.
oauthscope : ZohoInvoice.customerpayments.DELETE

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id} -X DELETE -H "X-com-zoho-invoice-organizationid: 10234695" -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 : ZohoInvoice.customerpayments.CREATE

Arguments

date
string
(Required)
Date on which payment is made. Date Format [yyyy-mm-dd]
refund_mode
string
The method of refund. Maximum length [50]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [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.

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds -X POST -H "X-com-zoho-invoice-organizationid: 10234695" -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" }

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 : ZohoInvoice.customerpayments.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds -H "X-com-zoho-invoice-organizationid: 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 }, {...}, {...} ] }

Update a refund

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

Arguments

date
string
(Required)
Date on which payment is made. Date Format [yyyy-mm-dd]
refund_mode
string
The method of refund. Maximum length [50]
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [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.

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id} -X PUT -H "X-com-zoho-invoice-organizationid: 10234695" -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" }

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 : ZohoInvoice.customerpayments.READ

Request Example

Click to copy
$ curl https://invoice.zoho.com/api/v3/customerpayments/{customer_payment_id}/refunds/{refund_id} -H "X-com-zoho-invoice-organizationid: 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 : ZohoInvoice.customerpayments.DELETE

Request Example

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

Response Example

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