ExternalPaymentOptions
Use the ExternalPaymentOptions container to create or change a subscription and mark its invoice as already paid.
You're essentially linking a payment that you've already received to an invoice. This feature is equivalent to using the web-based UI to process a manual payment.
An external payment occurs outside Zuora but must be recorded in Zuora to ensure that account balances and invoice balances are appropriately updated. An external payment can be any type, such as a credit card, debit card, ACH, check, wire transfer, bank transfer, Paypal, CCRef, and cash, but it's usually cash or a check.
ExternalPaymentOptions fields
|
Name |
Required? |
Description |
|---|---|---|
|
Amount |
required |
The amount of the payment. The value must be equal to the invoice's total balance. Type : decimal Character limi t: Version notes : WSDL 42.0+ System-generated: no Values :a positive decimal value Partial external payments and external overpayments are not supported. The Amount field value must equal the invoice's total balance. Otherwise the entire call will fail. |
|
EffectiveDate |
required |
The date when the external payment was made. If you leave this field value empty, then Zuora provides the current system date and time. Type :
Character limi t: 29 Version notes : WSDL 42.0+ System-generated : yes, if null Values : a valid date and time value |
|
GatewayOrderId |
optional |
The ID of the gateway order, which is the merchant-specified natural key value. Type : string Character limit : 255 Version note s: WSDL 42.0+ System-generated : no Values : a string of 255 characters or fewer |
|
PaymentMethodId |
required |
The ID of the payment method. A payment method is the form of payment that a customer used for the external payment. The ID is the unique identifier for that particular payment method. Type : zns:ID Character limit : 32 Version notes : WSDL 42.0+ System-generated : no Values :a valid payment method ID |
|
ReferenceId |
optional |
The ID returned by the bank or gateway that created the payment. Type : string Character limit : 60 Version notes : WSDL 42.0+ System-generated : no Values: a string of 60 characters or fewer |
EffectiveDate
While similarly named fields in other areas of the Zuora API refer to when the item takes effect, the EffectiveDate field in the ExternalPaymentOptions container is the date that the payment was made. For example, the customer makes a payment on 01 October 2012. You create the record of the payment on 07 October 2012. The EffectiveDate value is 01 October, not 07 October because that's when the money moved from the customer's account to the merchant's account. The CreatedDate field value is the value that reflects the 01 October date.
GatewayOrderId
The ID of the gateway order, which is the merchant-specified natural key value. A gateway is an online service provider that connects a virtual terminal to a payment processor.
The source of this ID varies by merchant. Some merchants use their shopping cart order IDs, and others use something different. Merchants use this ID to track transactions in their eCommerce systems.
Gateways can do a uniqueness check on this value as a means to prevent multiple submissions of the same transaction, such as when a customer clicks the Pay button twice during a single checkout process, inadvertently sending two identical orders to Zuora and the gateway. A uniqueness check prevents DuplicateOrderID exceptions.