Customer Payment
A customer payment transaction records a customer payment and applies it to the appropriate invoice or cash sale, decreasing the amount due and tracking income.
For details about this type of transaction, see Customer Payments.
The customer payment record is defined in the tranCust (customers) XSD.
Supported Operations
The following operations can be used with customer payment records:
add | addList | attach / detach | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | initialize / initializeList | search | update | updateList | upsert | upsertList
You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.
Field Definitions
The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s customer payment reference page.
For information on using the SOAP Schema Browser, see SOAP Schema Browser.
The balance field is only returned when using advanced search. It is not returned when using the <Record>SearchBasic search object. In advanced search, you must set the bodyFieldsOnly preference to false. The balance field is not returned if the bodyFieldsOnly preference is set to true. For more information, see bodyFieldsOnly.
Usage Notes
Working with Credit Card Data
When working with credit card data, be aware of the following security features:
-
When adding a transaction that uses a credit card number, you cannot identify the credit card number using a masked value such as ************5151. You must enter the full 16-digit number, or you can identify an existing credit card record through a RecordRef. (You can identify the full number using the ccNumber field. You can reference an existing record using the creditCard field.)
-
Searches do not work if they include the operator is or isNot in conjunction with the ccNumber field. The only search operators that can apply to this field are empty and notEmpty.
Initializing Customer Payments
You can initialize a customer payment from a Customer or an Invoice.
The SOAP web services initialize operation emulates the UI workflow by prepopulating fields on transaction line items with values from a related record. For more information about this operation, see initialize / initializeList.
Working with AutoApply
If you specify the “total amount of the original payment” as the payment value in a customer payment, autoApply through SOAP web services fails when there has already been an amount applied previously on the payment. This process fails when autoApply is set to true, and an invoice with apply = true already exists in the customer payment.
To work around this, you must set apply=false for the invoice. The following is the preferred workflow:
GET: (get the existing customer payment)
<get xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<baseRef internalId="2262" type="customerPayment" xsi:type="ns1:RecordRef" xmlns:ns1="urn:core_2017_1.platform.webservices.netsuite.com"/>
</get>
RESPONSE: (the response will return all the invoices that were already applied)
<ns3:applyList>
<ns3:apply>
<ns3:apply>true</ns3:apply>
<ns3:doc>1929</ns3:doc>
<ns3:total>27.92</ns3:total>
<ns3:due>27.92</ns3:due>
<ns3:amount>27.92</ns3:amount>
</ns3:apply>
<ns3:apply>
<ns3:apply>true</ns3:apply>
<ns3:doc>1930</ns3:doc>
<ns3:total>27.92</ns3:total>
<ns3:due>27.92</ns3:due>
<ns3:amount>27.92</ns3:amount>
</ns3:apply>
</ns3:applyList>
UPDATE: (update the customer payment - set paymentAmount to the original amount, set autoApply = true, **AND** set apply = false on all the invoices that have been already applied)
<update xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record internalId="2262" xsi:type="ns1:CustomerPayment" xmlns:ns1="urn:customers_2017_1.transactions.webservices.netsuite.com">
<ns1:customer internalId="176" xsi:type="ns2:RecordRef" xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns1:payment xsi:type="xsd:double">80.0</ns1:payment>
<ns1:autoApply xsi:type="xsd:boolean">true</ns1:autoApply>
<ns1:applyList replaceAll="false" xsi:type="ns1:CustomerPaymentApplyList">
<ns1:apply xsi:type="ns1:CustomerPaymentApply">
<ns1:apply xsi:type="xsd:boolean">false</ns1:apply>
<ns1:doc xsi:type="xsd:long">1929</ns1:doc>
</ns1:apply>
<ns1:apply xsi:type="ns1:CustomerPaymentApply">
<ns1:apply xsi:type="xsd:boolean">false</ns1:apply>
<ns1:doc xsi:type="xsd:long">1930</ns1:doc>
</ns1:apply>
</ns1:applyList>
</record>
</update>
GET: (perform a get to verify that it worked)
<get xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<baseRef internalId="2262" type="customerPayment" xsi:type="ns1:RecordRef" xmlns:ns1="urn:core_2017_1.platform.webservices.netsuite.com"/>
</get>
RESPONSE: (this response shows that the update worked. The invoices that were applied before are still applied, and the rest of the Payment Amount was applied to new invoices)
<ns3:applyList>
<ns3:apply>
<ns3:apply>true</ns3:apply>
<ns3:doc>1933</ns3:doc>
<ns3:total>27.92</ns3:total>
<ns3:due>27.92</ns3:due>
<ns3:amount>24.16</ns3:amount>
</ns3:apply>
<ns3:apply>
<ns3:apply>true</ns3:apply>
<ns3:doc>1929</ns3:doc>
<ns3:total>27.92</ns3:total>
<ns3:due>27.92</ns3:due>
<ns3:amount>27.92</ns3:amount>
</ns3:apply>
<ns3:apply>
<ns3:apply>true</ns3:apply>
<ns3:doc>1930</ns3:doc>
<ns3:total>27.92</ns3:total>
<...
Setting Accounts on Customer Payments
The 2013.1 endpoint changed the precedence for setting the account on customer payments from earlier endpoints. For the 2013.1 and later endpoints, if Undep. Funds is set to True, this value overrides Payment Method, and if Undep. Funds is set to False, Account overrides Payment Method.
In the 2012.2 and earlier endpoints, the account for a customer payment can only be set to Undep. Funds if the Payment Method and Account fields do not have values set, and there are also further complexities. Review the following table for details about setting the account on a customer payment in these earlier endpoints:
|
Payment Method Group with Undep. Funds or Deposit to Account? |
Is Payment Method Field Value Set? |
What Is Undep. Funds Field Value? |
Is Account Field Value Set? |
What is Result? |
|---|---|---|---|---|
|
Deposit to Account |
Yes |
False |
Yes |
account = value set for Account Field |
|
Deposit to Account |
Yes |
True |
No |
account = account associated with selected payment meethod |
|
Group with Undep. Funds |
No |
False |
Yes |
FAIL |
|
Group with Undep. Funds |
No |
True |
No |
account = Undeposited Funds account |
|
Group with Undep. Funds |
No |
True |
Yes |
FAIL |
|
Deposit to Account |
Yes |
True |
Yes |
account = value set for Account Field |