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 Code | Message |
---|---|
3004 | The Customer field can neither be blank nor incorrect. Please enter a correct Customer |
9521 | Partial payment for retainer invoice is not allowed. Please record the full payment |
9523 | Payment amount made to retainer invoice cannot be changed. You could instead delete it and add it back |
24016 | The amount entered is more than the balance due for this invoice |
Attribute
Maximum length allowed [2000]
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. Maximum length [100]
autotransaction
. Refunds would be made to the respective card provided by the customer.Date Format [yyyy-mm-dd]
success
or failure
.Maximum length of the reference number [100]
Maximum length [100]
{
"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
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. Maximum length [100]
Date Format [yyyy-mm-dd]
Maximum length of the reference number [100]
invoice_id
, invoice_number
, date
, invoice_amount
, amount_applied
and balance_amount
.$ 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"}'
{
"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
}
]
}
{
"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_startswith
and customer_name_contains
. Maximum length [100]
reference_number_startswith
and reference_number_contains
. Maximum length [100]
Date Format [yyyy-mm-dd]
amount_less_than
, amount_less_equals
, amount_greater_than
and amount_greater_equals
notes_startswith
and notes_contains
payment_mode_startswith
and payment_mode_contains
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
Maximum length [100]
$ curl https://invoice.zoho.com/api/v3/customerpayments
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
check
, cash
, creditcard
, banktransfer
, bankremittance
, autotransaction
or others
. Maximum length [100]
Date Format [yyyy-mm-dd]
Maximum length of the reference number [100]
$ 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"}'
{
"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
}
]
}
{
"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
$ curl https://invoice.zoho.com/api/v3/customerpayments/{payment_id}
-H "X-com-zoho-invoice-organizationid: 10234695"
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"
{
"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
$ 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"
{
"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 Format [yyyy-mm-dd]
Maximum length [50]
Maximum length of the reference number [100]
$ 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"}'
{
"date": "2016-06-05",
"refund_mode": "cash",
"reference_number": "INV-384",
"amount": 450,
"exchange_rate": 1,
"description": "Payment has been added to INV-384"
}
{
"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
$ 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"
{
"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 Format [yyyy-mm-dd]
Maximum length [50]
Maximum length of the reference number [100]
$ 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"}'
{
"date": "2016-06-05",
"refund_mode": "cash",
"reference_number": "INV-384",
"amount": 450,
"exchange_rate": 1,
"description": "Payment has been added to INV-384"
}
{
"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
$ 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"
{
"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
$ 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"
{
"code": 0,
"message": "The refund has been deleted."
}