Skip to main content

How do I bill for new purchases using the API without using the default payment method?

Zuora

How do I bill for new purchases using the API without using the default payment method?

Overview

Customers can have multiple payment methods associated with their account, but only one payment method can be set as the default. The default payment method is the customer's preferred method of payment. If an electronic payment method is set as the default (for example, a credit card) and auto-pay is enabled on the customer account, such credit card will be automatically charged for any payments owed by the customer. Customers may provide you multiple payment methods and request that a specific payment method is used for certain charges. For example, a customer may want to use their corporate credit card for recurring charges and a different credit card for one-time charges.

When using the Subscribe call you can either create a new PaymentMethod object, or specify the PaymentMethodId for an alternate PaymentMethod to be used for processing a payment for that subscription. If specifying the paymentmethodID, the operation will also set that payment methodID as the default Payment Method on the customer account. This is important to keep in mind as the  default payment method will be used to process future automatic payments for that customer.

Solution

This solution provides the steps to to apply a one-time payment for a brand new subscription (including products with one-time payments) for two uses.

Use Case 1: Using an existing PaymentMethod that is not the default PaymentMethod 

  1. Invoke the Subscribe call for your new product. Make sure to generate an Invoice by setting the GenerateInvoice to true, but do not process a Payment  by setting ProcessPayments to false.
<!-- sample subscribe call for an account that already exists -->
<!-- Valid for version 11.0+ of the Zuora WSDL -->

<ns2:subscribe>
<ns2:subscribes>
  <ns2:Account>
<!-- Set ID to the Account you want to create a subscription for-->
   <ns1:Id></ns1:Id>
  </ns2:Account>
  <ns2:SubscribeOptions>
   <ns2:GenerateInvoice>true</ns2:GenerateInvoice>
<!-- Make sure that you set the ProcessPayments to false-->
   <ns2:ProcessPayments>false</ns2:ProcessPayments>
  </ns2:SubscribeOptions>
  <ns2:SubscriptionData>
   <ns2:Subscription>
    <ns1:AutoRenew>true</ns1:AutoRenew>
<!-- See Working With Dates   - All datetimes are converted to GMT-08:00 -->
    <ns1:ContractAcceptanceDate>2009-07-03T08:07:55-07:00</ns1:ContractAcceptanceDate>
    <ns1:ContractEffectiveDate>2009-07-03T08:07:55-07:00</ns1:ContractEffectiveDate>
    <ns1:InitialTerm>12</ns1:InitialTerm>
    <ns1:Name>A-S00000020090703080755</ns1:Name>
    <ns1:RenewalTerm>12</ns1:RenewalTerm>
    <ns1:ServiceActivationDate>2009-07-03T08:07:55-07:00</ns1:ServiceActivationDate>
    <ns1:TermStartDate>2009-07-03T08:07:55-07:00</ns1:TermStartDate>
   </ns2:Subscription>
    <ns1:RatePlanData>
      <ns1:RatePlan xsi:type="ns2:RatePlan">
<!-- Set ID to the ProductRatePlan you want to subscribe to -->
        <ns2:ProductRatePlanId></ns2:ProductRatePlanId>
      </ns1:RatePlan>
<!-- example of how to set quantity of with RatePlanChargeData -->
      <ns1:RatePlanChargeData>
        <ns1:RatePlanCharge xsi:type="ns2:RatePlanCharge">
<!-- Set ID to the ProductRatePlan you want to subscribe to, and specify any other information you want to override or set- like quantity, charge number, etc -->
          <ns2:ProductRatePlanChargeId></ns2:ProductRatePlanChargeId>
          <ns2:Quantity>19</ns2:Quantity>
        </ns1:RatePlanCharge>
      </ns1:RatePlanChargeData>
    </ns1:RatePlanData>
  </ns2:SubscriptionData>
</ns2:subscribes>
</ns2:subscribe>
  1. Extract the invoice id from the Subscribe Result.
  2. Apply Payment to the Invoice
<ns1:create>
    <ns1:zObjects>           
<!-- Set ID to the Account you want to make a payment for [Required Value]-->   
       <ns2:AccountId>4028e485225d1d5f0122662fd6b249c8</ns2:AccountId>
<!-- Set the amount to be paid on the invoice [Required Value]-->
       <ns2:AppliedInvoiceAmount>100</ns2:AppliedInvoiceAmount>
<!-- Set the date of when the payment will be effective [Required Value]-->
       <ns2:EffectiveDate>2009-11-09T08:00:00</ns2:EffectiveDate>[Required]
<!-- Insert the InvoiceId from Subscribe call Result [Required Value]-->
       <ns2:InvoiceId>4028e485225d1d5f012266s2fd6bf49f8</ns2:AccountId>
<!--This should equal to either the actual PaymentMethod ID for the account or the placeholder PaymentMethod ID for cash, check, or other payment method[Required Value]-->
       <ns2:PaymentMethodId>9f9fde6aa678102bb59000188b619ff8</ns2:PaymentMethodId>[Required]
<!-- the status must be Processed only-->
       <ns2:Status>Processed</ns2:Status>
       <ns2:Type>Electronic</ns2:Type>[Required]
   </ns1:zObjects>
</ns1:create>

Use Case 2: Creating and Using a Brand New PaymentMethod 

  1. Invoke the Subscribe call for your new product, making sure to generate an Invoice by setting the GenerateInvoice to true, but do not process a Payment  by setting ProcessPayments to false.
<!-- sample subscribe call for an account that already exists -->
<!-- Valid for version 11.0+ of the Zuora WSDL -->

<ns2:subscribe>
<ns2:subscribes>
  <ns2:Account>
<!-- Set ID to the Account you want to create a subscription for-->
   <ns1:Id></ns1:Id>
  </ns2:Account>
  <ns2:SubscribeOptions>
   <ns2:GenerateInvoice>true</ns2:GenerateInvoice>
<!-- Make sure that you set the ProcessPayments to false-->
   <ns2:ProcessPayments>false</ns2:ProcessPayments>
  </ns2:SubscribeOptions>
  <ns2:SubscriptionData>
   <ns2:Subscription>
    <ns1:AutoRenew>true</ns1:AutoRenew>
<!-- See Working With Dates   - All datetimes are converted to GMT-08:00 -->
    <ns1:ContractAcceptanceDate>2009-07-03T08:07:55-07:00</ns1:ContractAcceptanceDate>
    <ns1:ContractEffectiveDate>2009-07-03T08:07:55-07:00</ns1:ContractEffectiveDate>
    <ns1:InitialTerm>12</ns1:InitialTerm>
    <ns1:Name>A-S00000020090703080755</ns1:Name>
    <ns1:RenewalTerm>12</ns1:RenewalTerm>
    <ns1:ServiceActivationDate>2009-07-03T08:07:55-07:00</ns1:ServiceActivationDate>
    <ns1:TermStartDate>2009-07-03T08:07:55-07:00</ns1:TermStartDate>
   </ns2:Subscription>
    <ns1:RatePlanData>
      <ns1:RatePlan xsi:type="ns2:RatePlan">
<!-- Set ID to the ProductRatePlan you want to subscribe to -->
        <ns2:ProductRatePlanId></ns2:ProductRatePlanId>
      </ns1:RatePlan>
<!-- example of how to set quantity of with RatePlanChargeData -->
      <ns1:RatePlanChargeData>
        <ns1:RatePlanCharge xsi:type="ns2:RatePlanCharge">
<!-- Set ID to the ProductRatePlan you want to subscribe to, and specify any other information you want to override or set- like quantity, charge number, etc -->
          <ns2:ProductRatePlanChargeId></ns2:ProductRatePlanChargeId>
          <ns2:Quantity>19</ns2:Quantity>
        </ns1:RatePlanCharge>
      </ns1:RatePlanChargeData>
    </ns1:RatePlanData>
  </ns2:SubscriptionData>
</ns2:subscribes>
</ns2:subscribe>
  1. Extract the invoice id from the Subscribe Result.
  2. Create a Payment Method.
  3. Apply Payment to the Invoice
<ns1:create>
    <ns1:zObjects>           
<!-- Set ID to the Account you want to make a payment for [Required Value]-->   
       <ns2:AccountId>4028e485225d1d5f0122662fd6b249c8</ns2:AccountId>
<!-- Set the amount to be paid on the invoice [Required Value]-->
       <ns2:AppliedInvoiceAmount>100</ns2:AppliedInvoiceAmount>
<!-- Set the date of when the payment will be effective [Required Value]-->
       <ns2:EffectiveDate>2009-11-09T08:00:00</ns2:EffectiveDate>[Required]
<!-- Insert the InvoiceId from Subscribe call Result [Required Value]-->
       <ns2:InvoiceId>4028e485225d1d5f012266s2fd6bf49f8</ns2:AccountId>
<!--This should equal to either the actual PaymentMethod ID for the account or the placeholder PaymentMethod ID for cash, check, or other payment method[Required Value]-->
       <ns2:PaymentMethodId>9f9fde6aa678102bb59000188b619ff8</ns2:PaymentMethodId>[Required]
<!-- the status must be Processed only-->
       <ns2:Status>Processed</ns2:Status>
       <ns2:Type>Electronic</ns2:Type>[Required]
   </ns1:zObjects>
</ns1:create>