An AR payment is a transaction used to record a payment against an AR invoice or an AR adjustment/debit memo.

There are two payment objects:

  • The new ARPYMT object, which supports applying credits/discounts/advances at the line level.

    The ARPYMT object does not currently support creating advances—continue to use the legacy create_arpayment function to create advances.

  • The legacy ARPAYMENT object, which is provided for backwards compatibility and to support creating advances.

Important: Starting with 2019 Release 4, all new companies will be configured to use the new AR payment object. For such companies, when creating an AR payment with the legacy create_arpayment function, an ARPYMT object is created, not an ARPAYMENT object. Existing companies continue to use the ARPAYMENT object for the current release.


Get AR Payment Object Definition

lookup

List all the fields and relationships for the AR payment object:

<lookup>
    <object>ARPYMT</object>
</lookup>

Parameters

Name Required Type Description
object Required string Use ARPYMT

List AR Payments

query

List the record number for each AR payment without a description:

<query>
    <object>ARPYMT</object>
    <select>
        <field>RECORDNO</field>
    </select>
    <filter>
        <isnull>
            <field>DESCRIPTION</field>
        </isnull>
    </filter>
</query>

Parameters

Name Required Type Description
object Required string Use ARPYMT
select Required sequence One or more field names and an optional aggregate function such as count or sum. Returning all fields is not supported.
filter Optional object Query filter expression. Check the value of a single field using operators such as equalto/like, or multiple fields using and/or. Query fields on related objects using the dot operator (for example, VENDOR.CREDITLIMIT on APBILL).
orderby Optional object Provide an order element with a field name and choose an ascending or descending sort order, for example:
<order>
        <field>RECORDNO</field>
        <descending/>
</order>
options Optional object Set the caseinsensitive element to true for a case-insensitive query:
    <caseinsensitive>true</caseinsensitive>
In a multi-entity company, set the showprivate element to true to query data in private entities:
   <showprivate>true</showprivate>
pagesize Optional integer Custom page size between 1 and 2000 items (Default: 100)
offset Optional integer Point at which to start indexing into records (Default: 0)

List AR Payments (Legacy)

Lists AR payments including posted payments, advance payments, and overpayments.

readByQuery

List AR payments:

<readByQuery>
    <object>ARPYMT</object>
    <fields>*</fields>
    <query></query>
    <pagesize>100</pagesize>
</readByQuery>

List overpayments:

<readByQuery>
    <object>ARPYMT</object>
    <query>RECORDTYPE = 'rp'</query>
    <fields>*</fields>
    <pagesize>100</pagesize>
</readByQuery>

Parameters

Name Required Type Description
object Required string Use ARPYMT
fields Optional string Comma-separated list of fields on the object to list. For best performance and predictability, limit the number of fields. To return all fields, omit the element or provide * for the value.
query Required string SQL-like query based on fields on the object. The following operators are supported: <, >, >=, <=, =, like, not like, in, not in, IS NOT NULL, IS NULL, AND, OR. Illegal XML characters must be properly encoded, and single quotes must be escaped with backslashes ('Jane\'s Deli'). Joins are not supported.
pagesize Optional integer Custom page size between 1 and 1000 items (Default: 100)

query Fields

Name Required Type Description
RECORDTYPE Optional string Type of the record. Userp for overpayment, rr for AR advance payment, or ro for applied AR overpayment.

Get AR Payment

read

<read>
    <object>ARPYMT</object>
    <keys>1</keys>
    <fields>*</fields>
</read>

Parameters

Name Required Type Description
object Required string Use ARPYMT
keys Required string Payment RECORDNO to get
fields Optional string Comma-separated list of fields on the object to get. For best performance and predictability, limit the number of fields. To return all fields, omit the element or provide * for the value.

Create AR Payment

An ARPYMT is composed of header information and one or more payment detail (ARPYMTDETAIL) objects. A payment detail can specify either the invoice/debit memo as a whole (header level), or it can specify a line item. A payment detail also provides a transaction amount to pay, and can include an inline credit or discount. Note that the ARPYMT object does not currently support advances—continue to use the legacy create_arpayment function for that purpose.

With ARPYMT, you can apply multiple credits to the same line by providing multiple payment details for that line. You can also apply credits or discounts from a different invoice (for the same customer) on the current invoice.

When a payment does not cover the total balance, each line is paid in full, starting with the first line and continuing down the list. This is known as the waterfall method, and it means that you should list any high priority payments first in invoices/debit memos.

create

Create a payment against the invoice header:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>JHC</CUSTOMERID>
        <DOCNUMBER>INV-007</DOCNUMBER>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <RECORDKEY>101</RECORDKEY>
                <TRX_PAYMENTAMOUNT>125</TRX_PAYMENTAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Create a payment against two invoice lines:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>JHC</CUSTOMERID>
        <DOCNUMBER>INV-009</DOCNUMBER>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <RECORDKEY>100</RECORDKEY>
                <ENTRYKEY>200</ENTRYKEY>
                <TRX_PAYMENTAMOUNT>30</TRX_PAYMENTAMOUNT>
            </ARPYMTDETAIL>
            <ARPYMTDETAIL>
                <RECORDKEY>100</RECORDKEY>
                <ENTRYKEY>201</ENTRYKEY>
                <TRX_PAYMENTAMOUNT>55</TRX_PAYMENTAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Create a payment against the invoice header, applying an inline credit:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>JHC</CUSTOMERID>
        <DOCNUMBER>INV-005</DOCNUMBER>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <RECORDKEY>100</RECORDKEY>
                <INLINEKEY>200</INLINEKEY>
                <INLINEENTRYKEY>202</INLINEENTRYKEY>
                <TRX_INLINEAMOUNT>15</TRX_INLINEAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Create a payment that applies an overpayment:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>JHC</CUSTOMERID>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <RECORDKEY>347</RECORDKEY>
                <OVERPAYMENTKEY>348</OVERPAYMENTKEY>
                <TRX_POSTEDOVERPAYMENTAMOUNT>33</TRX_POSTEDOVERPAYMENTAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Create a payment against a debit memo line by applying a credit memo line:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>Customer_022</CUSTOMERID>
        <DOCNUMBER>INV-001</DOCNUMBER>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <POSADJKEY>104</POSADJKEY>
                <POSADJENTRYKEY>204</POSADJENTRYKEY>
                <ADJUSTMENTKEY>105</ADJUSTMENTKEY>
                <ADJUSTMENTENTRYKEY>205</ADJUSTMENTENTRYKEY>
                <TRX_ADJUSTMENTAMOUNT>10</TRX_ADJUSTMENTAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Create a payment involving multi-currency:

<create>
    <ARPYMT>
        <FINANCIALENTITY>BOA</FINANCIALENTITY>
        <PAYMENTMETHOD>Cash</PAYMENTMETHOD>
        <CUSTOMERID>JHC</CUSTOMERID>
        <DOCNUMBER>INV-021</DOCNUMBER>
        <EXCH_RATE_TYPE_ID>Intacct Daily Rate</EXCH_RATE_TYPE_ID>
        <RECEIPTDATE>05/15/2019</RECEIPTDATE>
        <PAYMENTDATE>05/16/2019</PAYMENTDATE>
        <AMOUNTTOPAY>15</AMOUNTTOPAY>
        <TRX_AMOUNTTOPAY>10</TRX_AMOUNTTOPAY>
        <BASECURR>USD</BASECURR>
        <ARPYMTDETAILS>
            <ARPYMTDETAIL>
                <RECORDKEY>104</RECORDKEY>
                <TRX_PAYMENTAMOUNT>10</TRX_PAYMENTAMOUNT>
            </ARPYMTDETAIL>
        </ARPYMTDETAILS>
    </ARPYMT>
</create>

Parameters

Name Required Type Description
ARPYMT Required object Object to create

ARPYMT

Name Required Type Description
FINANCIALENTITY Optional string Financial entity from which the payment will be paid. Can be a checking account ID or a savings account ID. Required if not using a summary (PRBATCH) or undeposited funds account (UNDEPOSITEDACCOUNTNO).
PAYMENTMETHOD Required string Payment method. Payment method. Use Printed Check, Cash, EFT, Credit Card, Online Charge Card, or Online ACH Debit.
CUSTOMERID Required string Customer ID
DOCNUMBER Optional string Reference number, which can be a check number, an authorization code received from a charge card company, or a transaction number, depending on the payment method used
DESCRIPTION Optional string Description for the payment
EXCH_RATE_TYPE_ID Optional string Exchange rate type. Do not use if EXCHANGE_RATE is set. (Leave blank to use Intacct Daily Rate)
EXCHANGE_RATE Optional string Exchange rate value. Do not use if EXCH_RATE_TYPE_ID is set.
RECEIPTDATE Required string Receipt date in the mm/dd/yyyy format. This is the date on which to post to the GL.
PAYMENTDATE Optional string Payment date in the mm/dd/yyyy format when paying with a charge card. This is the date on which the transaction occurred, according to your statement. (Default: today’s date)
AMOUNTOPAY Optional currency For payment involving multi-currency, this is the translated payment base amount. (Amount is ignored if the payment is not cross currency.)
TRX_AMOUNTTOPAY Optional currency For payment involving multi-currency, this is the total transaction payment amount. (Amount is ignored if the payment is not cross currency.)
PRBATCH Optional string Summary name to post into if AR is configured for user-specified summary posting Required if not using a financial entity (FINANCIALENTITY) or undeposited funds account (UNDEPOSITEDACCOUNTNO).
WHENPAID Optional string Date when the invoice is fully paid in the mm/dd/yyyy format
CURRENCY Required string Transaction currency code
BASECURR Optional string Base currency code
UNDEPOSITEDACCOUNTNO Optional string Undeposited funds account. Required if not using a financial entity (FINANCIALENTITY) or summary (PRBATCH). You can record the deposit so that your books reflect the transfer of funds from your undeposited funds account to your bank account when you move the held payments.
OVERPAYMENTAMOUNT Optional currency Overpayment amount recorded by the payment
OVERPAYMENTLOCATIONID Optional string Location ID in which to receive an overpayment
OVERPAYMENTDEPARTMENTID Optional string Department ID in which to receive an overpayment
BILLTOPAYNAME Optional string Customer contact name for adjustments
ARPYMTDETAILS Required ARPYMTDETAIL[1...n] Details for the payment, including line items, discounts, adjustments, and so forth.
ONLINECARDPAYMENT Optional object Online card payment fields. Use only if payment method is Online Charge Card.

ARPYMTDETAIL

To make a simple payment against an invoice, provide the invoice RECORDNO as the RECORDKEY and specify a payment amount. To make a payment against a debit memo, use the RECORDNO from an ARADJUSTMENT as the POSADJKEY. You can only pay one or the other in a single payment detail. When a payment does not cover the total balance, lines are paid using the waterfall method.

To make a payment against a specific line of an invoice or debit memo, use ENTRYKEY or POSADJENTRYKEY, respectively.

When applying credits to payments, provide an ARPYMTDETAIL for each type of credit. Credits can be applied to the invoice/debit memo at the header level, or at the line level. When applying more than one type of credit against the same invoice or invoice line, provide an ARPYMTDETAIL for each type of credit.

Name Required Type Description
RECORDKEY Required integer Record number of the invoice being paid. You can pay either an invoice or a debit memo (via POSADJKEY), but not both in one payment detail.
ENTRYKEY Optional integer Record number of the line of the invoice being paid. If not supplied, lines of the invoice are paid using the waterfall method.
POSADJKEY Optional integer Record number of a debit memo being paid. Use readByQuery on ARADJUSTMENT to get the key. You can pay either a debit memo or an invoice (via RECORDKEY), but not both in one payment detail.
POSADJENTRYKEY Optional integer Record number of debit memo line
TRX_PAYMENTAMOUNT Optional currency Amount of the cash payment. Must be the full amount of the invoice or debit memo (with the discount amount calculated in) in order to apply a discount.
ADJUSTMENTKEY Optional integer Record number of a credit memo. Use readByQuery on ARADJUSTMENT to get the key.
ADJUSTMENTENTRYKEY Optional integer Record number of a credit memo line to apply to the payment
TRX_ADJUSTMENTAMOUNT Optional currency Adjustment transaction amount to apply to the payment
INLINEKEY Optional integer Record number of the invoice with inline credits to apply to the payment (typically from the same invoice that is being paid). Inline credits must be enabled in the AR configuration.
INLINEENTRYKEY Optional integer Record number of the invoice line with the inline credit apply to the payment
TRX_INLINEAMOUNT Optional currency Inline credit amount to apply to the payment
ADVANCEKEY Optional integer Record number of an advance to apply to the payment
ADVANCEENTRYKEY Optional integer Record number of an advance line to apply to the payment
TRX_POSTEDADVANCEAMOUNT Optional currency Advance credit amount to apply to the payment
OVERPAYMENTKEY Optional integer Record number of an overpayment to apply to the payment. To find available overpayments, use readByQuery on ARPYMT.
OVERPAYMENTENTRYKEY Optional integer Record number of an overpayment line to apply to the payment
TRX_POSTEDOVERPAYMENTAMOUNT Optional currency Overpayment credit amount to apply to the payment
NEGATIVEINVOICEKEY Optional integer Record number of a negative invoice to apply to the payment
NEGATIVEINVOICEENTRYKEY Optional integer Record number of a negative invoice line to apply to the payment
TRX_NEGATIVEINVOICEAMOUNT Optional currency Negative invoice amount to apply to the payment
DISCOUNTDATE Optional string Discount date in the mm/dd/yyyy format. All discounts available at this date are applied. You can supply a date in the past to access a discount whose deadline has already passed. You must provide the correct TRX_PAYMENTAMOUNT for the entire amount due (with the discount amount calculated in) for the discount to apply.

ONLINECARDPAYMENT

Name Required Type Description
CARDNUM Optional string Card number
EXPIRYDATE Optional string Expiration date in the mm/dd/yyyy format.
CARDTYPE Optional string Card type
SECURITYCODE Optional string Security code
USEDEFAULTCARD Optional boolean Use false for No, true for Yes.

List AR Payments (legacy)

List AR payments including posted payments and advanced.

Note: This function is provided for backwards compatibility only. Use readByQuery on the ARPYMT object moving forward.

readByQuery

<readByQuery>
    <object>ARPAYMENT</object>
    <fields>*</fields>
    <query></query>
    <pagesize>100</pagesize>
</readByQuery>

Parameters

Name Required Type Description
object Required string Use ARPAYMENT
fields Optional string Comma-separated list of fields on the object to list. For best performance and predictability, limit the number of fields. To return all fields, omit the element or provide * for the value.
query Required string SQL-like query based on fields on the object. The following operators are supported: <, >, >=, <=, =, like, not like, in, not in, IS NOT NULL, IS NULL, AND, OR. Illegal XML characters must be properly encoded, and single quotes must be escaped with backslashes ('Jane\'s Deli'). Joins are not supported.
pagesize Optional integer Custom page size between 1 and 1000 items (Default: 100)

query Fields

Name Required Type Description
RECORDTYPE Optional string Type of the record. Userp for overpayment, rr for AR advance payment, or ro for applied AR overpayment.

Get AR Payment (Legacy)

Note: This function is provided for backwards compatibility only. Use read on the ARPYMT object moving forward.

read

<read>
    <object>ARPAYMENT</object>
    <keys>1</keys>
    <fields>*</fields>
</read>

Parameters

Name Required Type Description
object Required string Use ARPAYMENT
keys Required string Payment RECORDNO to get
fields Optional string Comma-separated list of fields on the object to get. For best performance and predictability, limit the number of fields. To return all fields, omit the element or provide * for the value.

Create AR Payment (Legacy)

This function creates an ARPYMT object instead of the legacy ARPAYMENT object. It is recommended that you use the create function on the new ARPYMT object, which provides line level payments and credits/debits.

When you create an AR payment that is not applied to an invoice, the AR configuration for the customer account type dictates how the payment is applied:

  • Open Item (most popular/default setting) - The system creates the payment as an AR Advance, leaving it unapplied
  • Balance Forward - The system creates the payment and applies it to the oldest invoices automatically

create_arpayment

Create a multi currency AR payment and apply it to an invoice:

<create_arpayment>
    <customerid>6</customerid>
    <paymentamount>10</paymentamount>
    <translatedamount>20</translatedamount>
    <bankaccountid>BOFA1435</bankaccountid>
    <refid>1234</refid>
    <overpaylocid></overpaylocid>
    <overpaydeptid></overpaydeptid>
    <datereceived>
        <year>2013</year>
        <month>5</month>
        <day>6</day>
    </datereceived>
    <paymentmethod>Printed Check</paymentmethod>
    <basecurr>USD</basecurr>
    <currency>CAD</currency>
    <exchratetype>Intacct Daily Rate</exchratetype>
    <arpaymentitem>
        <invoicekey>25</invoicekey>
        <amount>10</amount>
    </arpaymentitem>
</create_arpayment>

Create an AR advance since the Customer Account Type is set to Open Item:

<create_arpayment>
    <customerid>C1234</customerid>
    <paymentamount>1000.00</paymentamount>
    <bankaccountid>BOFA1435</bankaccountid>
    <refid>1234567890</refid>
    <overpaylocid>100</overpaylocid>
    <datereceived>
        <year>2018</year>
        <month>11</month>
        <day>1</day>
    </datereceived>
    <paymentmethod>Printed Check</paymentmethod>
</create_arpayment>

Parameters

Name Required Type Description
customerid Required string Customer ID
paymentamount Required currency Transaction amount
translatedamount Optional currency Base amount
batchkey Optional integer AR payment summary record number to add this payment to. Required if not using bankaccountid or undepfundsacct.
bankaccountid Optional string Bank account ID. Required if not using undepfundsacct or batchkey.
undepfundsacct Optional string Undeposited funds GL account. Required if not using bankaccountid or batchkey. You can record the deposit so that your books reflect the transfer of funds from your undeposited funds account to your bank account when you move the held payments.
refid Optional string Reference number
overpaylocid Optional string Overpayment location ID
overpaydeptid Optional string Overpayment department ID
datereceived Optional object Received payment date
paymentmethod Optional string Payment method. Use Printed Check, Cash, EFT, Credit Card, Online Charge Card, or Online ACH Debit.
basecurr Optional string Base currency code
currency Optional string Payment currency code
exchratedate Optional object Exchange rate date
exchratetype Optional string Exchange rate type. Do not use if exchrate is set. (Leave blank to use Intacct Daily Rate)
exchrate Optional currency Exchange rate value. Do not use if exchangeratetype is set.
cctype Optional string Credit card type
authcode Optional string Authorization code to use
arpaymentitem Optional object Transactions records to apply the payment to. Element may appear 0 to N times. If 0 elements are provided, the AR module’s Customer Account Type setting will dictate how the payment is applied (see the description for the function above).
onlinecardpayment Optional object Online card payment fields only used if paymentmethod is Online Charge Card
onlineachpayment Optional object Online ACH payment fields only used if paymentmethod is Online ACH Debit

arpaymentitem

Name Required Type Description
invoicekey Required integer Transaction record number to apply payment to
amount Required currency Amount to apply. This must be less than or equal to paymentamount element of payment.

onlinecardpayment

Name Required Type Description
cardnum Required string Card number
expirydate Required string Expiration date
cardtype Required string Card type
securitycode Optional string Security code
usedefaultcard Optional boolean Use false for No, true for Yes.

onlineachpayment

Name Required Type Description
bankname Required string Bank name
accounttype Required string Account type
accountnumber Required string Account number
routingnumber Required string Routing number
accountholder Required string Account holder
usedefaultcard Optional boolean Use false for No, true for Yes.

Apply AR Payment (Legacy)

You can apply overpayments, advances, credit memos, or negative invoices using apply_arpayment. To do so, set the arpaymentkey as follows:

  • To apply an overpayment or an advance, use the RECORDNO from the ARPAYMENT object.
  • To apply a credit memo, use the RECORDNO from the ARADJUSTMENT object.
  • ​To apply a negative invoice or invoice with an inline credit, use the RECORDNO from the ARINVOICE object.

apply_arpayment

<apply_arpayment>
    <arpaymentkey>136</arpaymentkey>
    <paymentdate>
        <year>2013</year>
        <month>5</month>
        <day>16</day>
    </paymentdate>
    <memo>Apply AR Payment from API</memo>
    <overpaylocid></overpaylocid>
    <overpaydeptid></overpaydeptid>
    <arpaymentitems>
        <arpaymentitem>
            <invoicekey>135</invoicekey>
            <amount>10.99</amount>
        </arpaymentitem>
    </arpaymentitems>
</apply_arpayment>

Parameters

Name Required Type Description
arpaymentkey Required integer Payment record to apply.
paymentdate Required object Apply payment date
memo Optional string Memo
overpaylocid Optional string Overpayment location ID
overpaydeptid Optional string Overpayment department ID
arpaymentitems Required arpaymentitem[1...n] Transactions records to apply the payment to

arpaymentitem

You can apply the payments to an invoice or a debit memo. To do so, set the invoicekey as follows:

  • To apply to an invoice, use the RECORDNO from the ARINVOICE object. (This is not the RECORDNO from a sales invoice (SODOCUMENT). The PRRECORDKEY on SODOCUMENT is the RECORDNO on ARINVOICE.)
  • To apply to a debit memo, use the RECORDNO from the ARADJUSTMENT.
Name Required Type Description
invoicekey Required integer Transaction record number to apply payment to
amount Required currency Amount to apply. This must be less than or equal to paymentamount element of payment.

Reverse AR Payment (Legacy)

reverse_arpayment

<reverse_arpayment key="1234">
    <datereversed>
        <year>2015</year>
        <month>06</month>
        <day>30</day>
    </datereversed>
</reverse_arpayment>

Parameters

Name Required Type Description
key Required integer AR payment record number to reverse
datereversed Required object Reverse date
description Optional string Memo
nsfclosedaccount Optional string NSF closed account

datereversed

Name Required Type Description
year Required string Year yyyy
month Required string Month mm
day Required string Day dd

Provide feedback