Skip to main content

Apply Payments to an Invoice

Zuora

Apply Payments to an Invoice

As of API version 22, Zuora offers an improved, streamlined method of creating a payment and applying a payment to an invoice with a single API call. Zuora recommends all Z-Commerce API users to use the latest method.

However, if you are using an API version earlier than 22.0, or if you want to apply a single payment to multiple invoices, use the original method. 

Note that the process described in this topic will create a payment, apply it to an invoice, and send it to the gateway. However, it does not validate the results from the gateway; the success result from the final query only signifies that the status of the payment was updated to "Processed." You must query against the GatewayResponseCode for that payment to determine whether the payment was approved or declined by the gateway.

The method of using SOAP API to create InvoicePayment Object mentioned in this topic is not recommended anymore. Zuora now recommends using the CRUD: Create a payment REST API to create payment and apply it to invoices.

Apply Payments to an Invoice: Streamlined Method

This method is supported in version 22.0+ of API, and can be used when applying a payment to single invoice.

To create and apply an electronic payment to an invoice:

  1. Determine the invoice that you want to apply payment to.
  2. Create a new payment.

Step 1: Determine the Invoice

Execute the following query to determine the invoice to which you want to apply a payment:

select Id,Balance from Invoice where AccountId = 'someAccountId' and Balance > 0

SOAP Example

The following is an example of a SOAP call envelope payload for this query:

<ns1:query>
 <ns1:queryString>select Id,Balance from Invoice where AccountId = '4028e485225d1d5f0122662fd6b249c8' and Balance &gt; 0</ns1:queryString>
</ns1:query>

Step 2: Create a New Payment

Set the following fields to create a new Payment:

  • Specify the AccountId.
  • Specify Amount, which indicates the amount of the payment. If Invoice Settlement is enabled, this field is required.
  • Specify the InvoiceId, which is the single Invoice to which apply the payment.
  • Specify AppliedInvoiceAmount, the amount of the payment that should be applied to the invoice. This can be NULL if AppliedCreditBalanceAmount is not NULL.
  • Specify AppliedCreditBalanceAmount, the amount of the payment that should be added to the account credit balance. Use this if you are creating a payment that pays an invoice and also applies credit, which is useful for when a customer overpays. This can be NULL if AppliedInvoiceAmount is not NULL.
  • Set the EffectiveDate to the desired dateTime when this payment was made.
  • Specify the PaymentMethodId. This should equal to either the actual PaymentMethod ID for the account or the placeholder PaymentMethod ID for cash, check, or other payment method.
  • Set the Type for this payment: External (cash, check, other) or Electronic (credit card, PayPal, or ACH).
  • Set the Status to Processed.

See the create() API call for information about using create().

SOAP Example

The following is an example of a SOAP call envelope payload that will create the payment, create the InvoicePayment, and if the payment is electronic, process it through the gateway.

<ns1:create xmlns:ns1="http://api.zuora.com/">
    <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Payment">                 
       <ns2:AccountId>4028e485225d1d5f0122662fd6b249c8</ns2:AccountId>[Required]
       <ns2:Amount>120</ns2:Amount>[if invoice settlement is enabled, it's required]
       <ns2:AppliedInvoiceAmount>100</ns2:AppliedInvoiceAmount>[if invoiceId is not null,it's required]
       <ns2:AppliedCreditBalanceAmount>20.00</ns2:AppliedCreditBalanceAmount>[if invoice id is null,it's required]
       <ns2:EffectiveDate>2009-11-09</ns2:EffectiveDate>[Required]
       <ns2:InvoiceId>4028e485225d1d5f012266s2fd6bf49f8</ns2:InvoiceId>[if creditbalanceamount is null,it's required]
       <ns2:PaymentMethodId>9f9fde6aa678102bb59000188b619ff8</ns2:PaymentMethodId>[Required]
       <ns2:Status>Processed</ns2:Status>[the status must be Processed only]
       <ns2:Type>Electronic</ns2:Type>[Required]
   </ns1:zObjects>
</ns1:create>

Apply Payments to an Invoice: Original Method

This method is supported in API versions 21.0 and earlier, or when applying payment to multiple invoices.

This use case uses several objects to create and apply a Payment to an Invoice.

To create and apply an electronic payment to an invoice:

  1. Query for the invoice by AccountId.
  2. Create a new payment.
  3. Create a new InvoicePayment object.
  4. Update the payment.

Query for the Invoice by AccountId

Execute the following query to determine the invoice to which you want to apply a payment:

select Id,Balance from Invoice where AccountId = 'someAccountIdAccountId' and Balance > 0

SOAP Example

The following is an example of a SOAP call envelope payload for this query:

<ns1:query>
 <ns1:queryString>select Id,Balance from Invoice where AccountId = '4028e485225d1d5f0122662fd6b249c8' and Balance &gt; 0</ns1:queryString>
</ns1:query>

Create a New Payment

Set the following fields to create a new Payment:

  • Specify the AccountId.
  • Specify the payment Amount.
  • Set the EffectiveDate to the desired dateTime when this payment was made.
  • Specify the PaymentMethodId. This should equal to either the actual PaymentMethod ID for the account or the placeholder PaymentMethod ID for cash, check, or other payment method.
  • Set the Type for this payment: External (cash, check, other) or Electronic (credit card, PayPal, or ACH).
  • Set the Status to Draft.

See the create() API call for information about using create().

SOAP Example

The following is an example of a SOAP call envelope payload that will create the payment:

<ns1:create>
 <ns1:zObjects xsi:type="ns2:Payment">
   <ns2:AccountId>4028e485225d1d5f0122662fd6b249c8</ns2:AccountId>
   <ns2:Amount>104.97</ns2:Amount>
   <ns2:EffectiveDate>2009-11-09</ns2:EffectiveDate>
   <ns2:PaymentMethodId>9f9fde6aa678102bb59000188b619ff8</ns2:PaymentMethodId>
   <ns2:Status>Draft</ns2:Status>
   <ns2:Type>Electronic</ns2:Type>
 </ns1:zObjects>
</ns1:create>

Create a New InvoicePayment Object

Create a new InvoicePayment object to relate the payment to an Invoice.

Set the following fields:

  • Set the Amount. This value must be greater than 0, but less than the remaining, unallocated amount of the Payment. The entire Payment amount must be allocated to an one or more invoice before the Payment can be processed.
  • Set the InvoiceId to the Invoice Id that you retrieved when you queried for the invoice by AccountId.
  • Set the PaymentId to the ID returned when you created the payment.

You can create multiple InvoicePayment objects per payment. For example, if you have two invoices due, one for $100 and one for $75, you can create a $175 payment in and then create two InvoicePayment objects: One for $100 and applied to first invoice, and one for $75 and applied to second invoice.

SOAP Example

The SOAP call envelope payload should look like the following:

<ns1:create>
 <ns1:zObjects xsi:type="ns2:InvoicePayment">
  <ns2:Amount>104.97</ns2:Amount>
  <ns2:InvoiceId>8a8ae4b122f5e34d0122f6d269610760</ns2:InvoiceId>
  <ns2:PaymentId>4028e4861dc1ff0e011ddc1554bf1e9d</ns2:PaymentId>
 </ns1:zObjects>
</ns1:create>

Update the Payment

Set the following fields to update the payment:

  • Specify the ID of the payment.
  • Set the Status of the payment to Processed.

See the update() API call for information about using update().

For Electronic payments, the payment will be processed by the payment gateway during the update() call.

SOAP Example

The SOAP call envelope payload should look like the following:

<ns1:update>
 <ns1:zObjects xsi:type="ns2:Payment">
   <ns2:Id>4028e4861dc1ff0e011ddc1554bf1e9d</ns2:Id>
   <ns2:Status>Processed</ns2:Status>
 </ns1:zObjects>
</ns1:update>