Creating and Applying Payments to an Invoice

From API Documentation

Jump to: navigation, search
NOTE: As of version 22.0, Zuora now offers a much improved, streamlined way to create a payment and apply payment to a single invoice with a single API call. Zuora recommends all Z-Commerce API users to use the latest method.

Contents

Streamlined Method

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

To create and apply an electronic payment to an invoice:

Step 1: Determine which Invoice to Apply Payment

Execute the following query: select Id,Balance from Invoice where AccountId = 'someAccountId' and Balance > 0

The SOAP call envelope payload should look like this: 

<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 the InvoiceId, which is the single Invoice to which apply payment.
  • Specify AppliedInvoiceAmount, the amount of the payment that should be applied to the invoice. This can be NULL if AppliedCreditBalanceAmount is not.
  • Specify AppliedCreditBalanceAmount, the amount of the payment that should be added to the account credit balance (in case you are creating a payment that pays an invoice AND also applies credit, which is very useful for when a customer overpays. This can be NULL if AppliedInvoiceAmount is not.
  • Set the EffectiveDate to the desired date/time 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, etc.
  • Set the Type for this payment: External (Cash, Check, Other, etc.) or Electronic (CreditCard, PayPal, or ACH).
  • Set the Status to Processes.

Next, create the new payment. See the create() API call.

The SOAP call envelope payload should look like this: 

<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: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-09T08:00:00</ns2:EffectiveDate>[Required]
       <ns2:InvoiceId>4028e485225d1d5f012266s2fd6bf49f8</ns2:AccountId>[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>

This will create the payment, the InvoicePayment, and if the payment is electronic, process it through the gateway.

Original Method

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

In this use case, several objects will be used to create and apply a Payment to an Invoice.

To create and apply an electronic payment to an invoice:

Step 1: Query for Invoice by AccountId

Execute the following query: 

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

The SOAP call envelope payload should look like this: 

<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:

  • Specify the AccountId.
  • Specify the payment Amount.
  • Set the EffectiveDate to the desired date/time 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, etc.
  • Set the Type for this payment: External (Cash, Check, Other, etc.) or Electronic (CreditCard, PayPal, or ACH).
  • Set the Status to Draft.

Next, create a new Payment. See the create() API call.

The SOAP call envelope payload should look like the following: 

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

Step 3: Create a New InvoicePayment Object

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

Set the following fields:

  • Set the Amount. Please note that this value needs to be larger than 0, but less than the remaining, unallocated amount of the Payment. The whole Payment amount will need to be allocated to an invoice or invoices, before the Payment can be processed.
  • Set the InvoiceId to the Invoice Id retrieved in step 1.
  • Set the PaymentId to the Id returned in step 2.

Next, create the InvoicePayment object.

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>
Note: You can create multiple InvoicePayment objects per Payment.  For example, if you have two invoice due, one for $100 and one for $75, you could create a $175 payment in step #1 and create two InvoicePayment objects in step #3, one for $100 and applied to first invoice, and one for $75 and applied to second invoice.

Step 4: Update the Payment

Set the following fields:

  • Specify the payment's Id.
  • Set Status to Processed.

Next, update the payment. See the update() API call. For Electronic payments, the payment will be processed via the Payment Gateway during the Update call.

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>
Retrieved from "http://apidocs.developer.zuora.com/index.php/Creating_and_Applying_Payments_to_an_Invoice"