Working with Customer Payments in Zoho Books

Overview

The following operations allow you to work with customer payments. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with customer payments, see Sample configuration.

Operation	Description
createCustomerPayment	Creates a payment made by the customer.
listCustomerPayments	Retrieves all the payments made by your customer.

Operation details

This section provides further details on the operations related to customer payments.

Creating a payment made by the customer

The createCustomerPayment operation creates a payment made by your customer and you can also apply them to invoices either partially or fully.

createCustomerPayment

<zohobooks.createCustomerPayment>
    <date>{$ctx:date}</date>
	<amount>{$ctx:amount}</amount>
	<taxAccountId>{$ctx:taxAccountId}</taxAccountId>    
    <contactPersons>{$ctx:contactPersons}</contactPersons>
    <paymentMode>{$ctx:paymentMode}</paymentMode>
    <accountId>{$ctx:accountId}</accountId>
    <customerId>{$ctx:customerId}</customerId>
    <exchangeRate>{$ctx:exchangeRate}</exchangeRate>
    <description>{$ctx:description}</description>
	<referenceNumber>{$ctx:referenceNumber}</referenceNumber>
    <bankCharges>{$ctx:bankCharges}</bankCharges>
	<invoices>{$ctx:invoices}</invoices>
</zohobooks.createCustomerPayment>

Properties

date: Required - Date the payment is made.
amount: Required - Payment amount made by the customer.
taxAccountId: The ID of the tax account, in case of withholding tax.
contactPersons: The IDs of the contact persons the thank you mail has to be triggered to.
paymentMode: Mode of payment for the amount received.
accountId: The ID of the cash/ bank account the payment has to be deposited to.
customerId: The ID of the customer.
exchangeRate: Exchange rate of the currency.
description: Description for the customer payment.
referenceNumber: Reference number for the customer payment.
bankCharges: Bank charges incurred.
invoices: An Array which contains invoice payment details.

Sample Request

Following is a sample REST/JSON request that can be handled by the createCustomerPayment operation.

Sample Request for createCustomerPayment

{
    "apiUrl": "https://books.zoho.com",
    "authToken": "40652e2f50fb0873728fddf4d27f3a10",
    "organizationId": "48221130",
    "taxAccountId": "",
    "amount": "250",
    "paymentMode": "Cash",
    "accountId": "111948000000039475",
    "customerId": "111948000000038079",
    "exchangeRate": "2.0",
    "description": "test payment desc",
    "referenceNumber": "ref123456",
    "date": "2014-02-15",
    "bankCharges": "150",
    "invoices": [
        {
            "invoice_id": "111948000000041635",
            "amount_applied": 30,
            "tax_amount_withheld": 0
        }
    ],
	"contactPersons":[
        "111948000000038081"
    ]
}

Retrieving all the payments made by your customer

The listCustomerPayments operation retrieves all the payments made by your customer.

listCustomerPayments

<zohobooks.listCustomerPayments>
    <amountGreaterThan>{$ctx:amountGreaterThan}</amountGreaterThan>
    <paymentMode>{$ctx:paymentMode}</paymentMode>
    <amountLessThan>{$ctx:amountLessThan}</amountLessThan>
    <amountGreaterEqual>{$ctx:amountGreaterEqual}</amountGreaterEqual>
    <referenceNumber>{$ctx:referenceNumber}</referenceNumber>
    <dateEnd>{$ctx:dateEnd}</dateEnd>
    <paymentModeContains>{$ctx:paymentModeContains}</paymentModeContains>
    <date>{$ctx:date}</date>
    <dateBefore>{$ctx:dateBefore}</dateBefore>
    <amount>{$ctx:amount}</amount>
    <notesContains>{$ctx:notesContains}</notesContains>
    <customerNameStartswith>{$ctx:customerNameStartswith}</customerNameStartswith>
    <customerId>{$ctx:customerId}</customerId>
    <filterBy>{$ctx:filterBy}</filterBy>
    <paymentModeStartsWith>{$ctx:paymentModeStartsWith}</paymentModeStartsWith>
    <customerName>{$ctx:customerName}</customerName>
    <notesStartsWith>{$ctx:notesStartsWith}</notesStartsWith>
    <dateAfter>{$ctx:dateAfter}</dateAfter>
    <dateStart>{$ctx:dateStart}</dateStart>
    <referenceNumberContains>{$ctx:referenceNumberContains}</referenceNumberContains>
    <sortColumn>{$ctx:sortColumn}</sortColumn>
    <customerNameContains>{$ctx:customerNameContains}</customerNameContains>
    <referenceNumberStartswith>{$ctx:referenceNumberStartswith}</referenceNumberStartswith>
    <searchText>{$ctx:searchText}</searchText>
    <amountLessEqual>{$ctx:amountLessEqual}</amountLessEqual>
	<notes>{$ctx:notes}</notes>
</zohobooks.listCustomerPayments>

Properties

amountGreaterThan: The number of the page to be returned - pagination value.
paymentMode: Search payments by payment mode.
amountLessThan: Search payments by payment amount which is less than the given amount.
amountGreaterEqual: Search payments by payment amount which is greater than or equal the given amount.
referenceNumber: Search payments by reference number.
dateEnd: Search payments by payment made date.
paymentModeContains: Search payments by a regex containing any part of the payment mode.
date: Search payments by payment made date.
dateBefore: Search payments by payment made dates which falls before the date given.
amount: Search payments by payment amount.
notesContains: Search payments by a regex containing any part of the customer notes.
customerNameStartswith: Search payments by a regex of the starting letter or letters of the customer name.
customerId: Search payments by customer ID.
filterBy: Filter payments by mode.
paymentModeStartsWith: Search payments by a regex of the starting letter or letters of the payment mode.
customerName: Search payments by the exact customer name.
notesStartsWith: Search payments by regex of the starting letter or letters of the customer notes.
dateAfter: Search payments by payment made dates which falls after the date given.
dateStart: Search payments by payment made date which falls on a date range.
referenceNumberContains: Search payments by a regex containing any part of the reference number.
sortColumn: Sort the payment list.
customerNameContains: Search payments by a regex containing any part of the customer name.
referenceNumberStartswith: Search payments by a regex of the starting letter or letters of the reference number.
searchText: Search payments by reference number or customer name or payment description.
amountLessEqual: Search payments by payment amount which is less than or equal the given amount.
notes: Search payments by customer notes.

Sample request

Following is a sample REST/JSON request that can be handled by the listCustomerPayments operation.

Sample Request for listCustomerPayments

{
    "authToken": "c11a87210138ff2e0bf6d049abd3c27e",
    "organizationId": "50875541",
    "apiUrl": "https://books.zoho.com",
    "customerNameContains": "Jay",
    "paymentModeStartsWith": "Ca",
    "filterBy": "PaymentMode.Cash",
    "dateAfter": "2015-02-15"
}

Note

There are more optional parameters available. For more information on the usage of these parameters please check the API document.

Sample Configuration

Following is a sample proxy service that illustrates how to connect to Zoho Books with the init operation and use the createCustomerPayment operation. The sample request for this proxy can be found in the createCustomerPayment sample request. You can use this sample as a template for using other operations in this category.

Sample proxy

<?xml version="1.0" encoding="UTF-8"?>
	<proxy xmlns="http://ws.apache.org/ns/synapse" name="zohobooks_createCustomerPayment" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
	 <target>
	 <inSequence>
      <property name="authToken" expression="json-eval($.authToken)"/>
      <property name="apiUrl" expression="json-eval($.apiUrl)"/>
      <property name="organizationId" expression="json-eval($.organizationId)"/>
      <property name="taxAccountId" expression="json-eval($.taxAccountId)"/>
      <property name="amount" expression="json-eval($.amount)"/>
      <property name="contactPersons" expression="json-eval($.contactPersons)"/>
      <property name="paymentMode" expression="json-eval($.paymentMode)"/>
      <property name="accountId" expression="json-eval($.accountId)"/>
      <property name="customerId" expression="json-eval($.customerId)"/>
      <property name="exchangeRate" expression="json-eval($.exchangeRate)"/>
      <property name="description" expression="json-eval($.description)"/>
      <property name="referenceNumber" expression="json-eval($.referenceNumber)"/>
      <property name="date" expression="json-eval($.date)"/>
      <property name="bankCharges" expression="json-eval($.bankCharges)"/>
      <property name="invoices" expression="json-eval($.invoices)"/>
      <zohobooks.init>
         <authToken>{$ctx:authToken}</authToken>
         <apiUrl>{$ctx:apiUrl}</apiUrl>
         <organizationId>{$ctx:organizationId}</organizationId>
      </zohobooks.init>
      <zohobooks.createCustomerPayment>
         <taxAccountId>{$ctx:taxAccountId}</taxAccountId>
         <amount>{$ctx:amount}</amount>
         <contactPersons>{$ctx:contactPersons}</contactPersons>
         <paymentMode>{$ctx:paymentMode}</paymentMode>
         <accountId>{$ctx:accountId}</accountId>
         <customerId>{$ctx:customerId}</customerId>
         <exchangeRate>{$ctx:exchangeRate}</exchangeRate>
         <description>{$ctx:description}</description>
         <referenceNumber>{$ctx:referenceNumber}</referenceNumber>
         <date>{$ctx:date}</date>
         <bankCharges>{$ctx:bankCharges}</bankCharges>
         <invoices>{$ctx:invoices}</invoices>
      </zohobooks.createCustomerPayment>
	   <respond/>
	 </inSequence>
	  <outSequence>
	   <send/>
	  </outSequence>
	 </target>
   <description/>
  </proxy>

WSO2 ESB Connectors Documentation

Working with Customer Payments in Zoho Books

Overview

Operation details

Creating a payment made by the customer

Properties

Sample Request

Related Zoho Books Documentation

Retrieving all the payments made by your customer

Properties

Sample request

Related Zoho Books documentation

Sample Configuration