Payment object
A payment is the money that customers send to pay for invoices related to their subscriptions.
The Payment object holds all of the information about an individual payment, including the payment amount and to which invoices the payment was applied to. You can create the Payment object in a create() call and apply the payment to the customer's invoices and account.
There are two ways to create a payment:
Supported Calls
You can use this object with the following calls:
You can't use the delete() call for the Payment object if your WSDL is version 30.0 or older.
Walkthroughs and Use Cases
Here are some common ways to use this object:
- Apply a payment to an invoice
- Apply a payment to multiple invoices
- Delete a payment
- Change an existing payment
- Apply an external payment to an invoice
- Apply multiple payments to different invoices
Field Descriptions
All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.
| Name | Required to Create? | Allowed Operations | Description |
|---|---|---|---|
|
AccountId |
required |
Create |
The unique account ID for the customer that the payment is for. Type: zns:ID |
|
AccountingCode |
optional |
Create |
The accounting code for the payment. Accounting codes group transactions that contain similar accounting attributes. Type: string |
|
Amount |
required |
Create |
The amount of the payment. Type: decimal (currency) |
| AppliedAmount | optional | filter |
The amount of the payment that has already been applied to billing documents, such as invoices or debit memos. Type: decimal (currency) This field is only available if you have the Invoice Settlement feature enabled. |
|
AppliedCreditBalanceAmount |
required |
Create |
The amount of the payment to apply to a credit balance. This field is required in a create() call when the Type: decimal (currency) |
|
AppliedInvoiceAmount |
required |
Create |
The amount of the payment to apply to an invoice. Type: decimal (currency) |
|
AuthTransactionId |
optional |
Create |
The authorization transaction ID from the payment gateway. Use this field for electronic payments, such as credit cards. Type: string |
|
BankIdentificationNumber |
optional |
Query |
The first six or eight digits of the credit card or debit card used for the payment, when applicable. Use this field to reconcile payments between the gateway and merchant banks. Type: string |
|
CancelledOn |
optional |
Query |
The date when the payment was canceled. Type: dateTime |
|
Comment |
optional |
Create |
Additional information related to the payment. Type: string |
|
CreatedById |
required |
Query |
The user ID of the person who created the Type: zns:ID |
|
CreatedDate |
required |
Query |
The date when the Payment object was created in the Zuora system. Type: dateTime |
|
EffectiveDate |
required |
Create |
The date when the payment takes effect. Type:
Character limit: 29 |
|
Gateway |
optional |
Create |
Name of the gateway instance that processes the payment. When creating a Payment, this must be a valid gateway instance name and this gateway must support the specific payment method. If not specified, the default gateway on the Account will be used. For more information, see Payment Gateways. |
|
GatewayOptionData |
optional |
Create |
Use this field to pass gateway options. Type: zns:GatewayOption |
|
GatewayOrderId |
optional |
Create |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the PaymentNumber will be passed in instead. Type: string |
|
GatewayResponse |
optional |
Query |
The message returned from the payment gateway for the payment. This message is gateway-dependent. Type: string |
|
GatewayResponseCode |
optional |
Query |
The code returned from the payment gateway for the payment. This code is gateway-dependent. Type: string |
|
GatewayState |
optional |
Query |
The status of the payment in the gateway; use for reconciliation. Type: string (enum) |
|
Id |
optional |
Query |
The ID of this object. Upon creation, the ID of this object is Type: zns:ID |
|
InvoiceId |
optional |
Create
|
The ID of the invoice that the payment is applied to. Type: zns:ID |
|
InvoiceNumber |
optional |
Create |
The unique identification number for the invoice that the payment is applied to. Type: string |
|
InvoicePaymentData |
optional |
n/a |
A container of InvoicePayment. This field can be treated as an array or a list. Type: array |
|
MarkedForSubmissionOn |
optional |
Query |
The date when a payment was marked and waiting for batch submission to the payment process. Type: dateTime |
|
PaymentMethodId |
optional |
Create |
The ID of the payment method used for the payment. Required for Create. Type: zns:ID |
|
PaymentMethodSnapshotId |
read-only |
Query |
The unique ID of the payment method snapshot which is a copy of the particular Payment Method used in a transaction. Type: zns:ID |
|
PaymentNumber |
optional |
Query |
The unique identification number of a payment. For example: P-00000028. Type: string |
|
ReferenceId |
optional |
Create |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Z-Payments. Type: string |
|
RefundAmount |
optional |
Query |
The amount of the payment that is refunded. This field is null if no refund is made against the payment. Type: decimal (currency) |
|
SecondPaymentReferenceId |
optional |
Query |
The transaction ID returned by the payment gateway if there is an additional transaction for the payment. Use this field to reconcile payments between your gateway and Z-Payments. Type: string |
|
SettledOn |
optional |
Query |
The date when the payment was settled in the payment processor. This field is used by the Spectrum gateway only and not applicable to other gateways. Type: dateTime |
|
SoftDescriptor |
optional |
Create |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi. Type: string |
|
SoftDescriptorPhone |
optional |
Create |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi. Type: string |
|
Source |
optional |
Query |
Indicates how the payment was created, whether through API, manually, import, or payment run. Type: string |
|
SourceName |
optional |
Query |
Name of the source. Type: string |
|
Status |
required |
Create |
The status of the payment in Zuora. The value depends on the type of payment. Type: string (enum)
See Troubleshooting Payment Runs for more information. * Update of status can change value from |
|
SubmittedOn |
optional |
Query |
The date when the payment was submitted. Type: dateTime |
|
TransferredToAccounting |
optional |
Query |
Indicates if the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite. Type:string (enum) |
|
Type |
required |
Create |
Indicates if the payment is external or electronic. Type: string (enum) |
| UnappliedAmount | optional |
Query |
The unapplied amount of the payment. Type: decimal (currency) This field is only available if you have the Invoice Settlement feature enabled. |
|
UpdatedById |
No |
Query |
The ID of the user who last updated the payment. Type: zns:ID |
|
UpdatedDate |
No |
Query |
The date when the payment was last updated. Type: dateTime |
Additional Field Detail
GatewayOrderId
A merchant-specified natural key value that can be passed to the payment gateway when an electronic payment is created.
A gateway is an online service provider that connects an online shopping cart to a payment processor. Gateways check duplicates on the gateway order ID to ensure that the merchant didn't accidentally enter the same transaction twice. This ID can also be used to do reconciliation and tie the payment to a natural key in external systems. For example, a shopping cart order ID.
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 usually do a uniqueness check on this value 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.
If not provided, Zuora will default this value to the PaymentNumber.
GatewayState
The status of the payment in the gateway. This field is automatically generated and can have one of the following values:
NotSubmittedSubmittedSettledFailedToSettle
The value of this field remains NotSubmitted, if Gateway Reconciliation is not enabled for the gateway.
Id
The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscriptionobject's ID with the call.
The ID for the Payment object is PaymentId.
SoftDescriptor
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi. Use this field in create() calls. Zuora passes this field to Verifi directly with no verification. In general, this field will be defaulted by the gateway. For Orbital, this field contains two fields separated by an asterisk: SDMerchantName and SDProductionInfo. For more information, contact your payment gateway.
SoftDescriptorPhone
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi. Use this field in create() calls. This field itself contains the field, SDPhone. Verifi and Orbital determine how to format this string. For more information, contact your payment gateway.
Code Examples
Create Payment Using InvoiceId and InvoiceNumber
To create a payment against a single invoice.
<ns1:create>
<ns1:zObjects xsi:type="ns2:Payment">
<ns2:AccountId>2c92a0f94b07c36d014b178abac902f0</ns2:AccountId>
<ns2:Amount>500</ns2:Amount>
<ns2:AppliedCreditBalanceAmount>0</ns2:AppliedCreditBalanceAmount>
<ns2:AppliedInvoiceAmount>500</ns2:AppliedInvoiceAmount>
<ns2:EffectiveDate>2015-01-27T13:19:39</ns2:EffectiveDate>
<ns2:InvoiceId>2c92a0944b07c492014b178be9ef7327</ns2:InvoiceId>
<ns2:PaymentMethodId>2c92a0f94b07c36d014b178abae902f2</ns2:PaymentMethodId>
<ns2:Status>Processed</ns2:Status>
<ns2:Type>Electronic</ns2:Type>
</ns1:zObjects>
</ns1:create>
Create Payment Using InvoicePaymentData
To create a payment against multiple invoices.
<ns1:create xmlns:ns1="http://api.zuora.com/">
<ns1:zObjects xsi:type="ns2:Payment">
<ns2:AccountId>402896ba500425ab01500429176c000f</ns2:AccountId>
<ns2:Amount>200</ns2:Amount>
<ns2:EffectiveDate>2015-09-25</ns2:EffectiveDate>
<ns2:AppliedCreditBalanceAmount>0</ns2:AppliedCreditBalanceAmount>
<ns2:InvoicePaymentData>
<ns1:InvoicePayment xsi:type="ns2:InvoicePayment">
<ns2:Amount>100.0</ns2:Amount>
<ns2:InvoiceId>402896ba500425ab0150042ab9440035</ns2:InvoiceId>
<ns2:RefundAmount>0</ns2:RefundAmount>
</ns1:InvoicePayment>
<ns1:InvoicePayment xsi:type="ns2:InvoicePayment">
<ns2:Amount>100.0</ns2:Amount>
<ns2:InvoiceId>402896ba500425ab0150042c8d9b0053</ns2:InvoiceId>
<ns2:RefundAmount>0</ns2:RefundAmount>
</ns1:InvoicePayment>
</ns2:InvoicePaymentData>
<ns2:PaymentMethodId>402881e522cf4f9b0122cf5dc3ef003d</ns2:PaymentMethodId>
<ns2:Status>Processed</ns2:Status>
<ns2:Type>External</ns2:Type>
</ns1:zObjects>
</ns1:create>
Create() Call Response
All Payment create() calls return a Success response and a Payment Id. The Success response refers to the creation of the payment object, not to the success or failure of the payment request.
The following create request and the response demonstrate this point.
Create request
<ns1:create> <ns1:zObjects xsi:type="ns2:Payment"> <ns2:AccountId>2c92c0f84088c66101409de647c25608</ns2:AccountId> <ns2:Amount>530.00</ns2:Amount> <ns2:AppliedCreditBalanceAmount>530</ns2:AppliedCreditBalanceAmount> <ns2:EffectiveDate>2013-08-20T11:07:55-07:00</ns2:EffectiveDate> <ns2:PaymentMethodId>2c92c0f84088c66101409de647c7560a</ns2:PaymentMethodId> <ns2:Status>Processed</ns2:Status> <ns2:Type>Electronic</ns2:Type> </ns1:zObjects> </ns1:create>
Response
The request response indicates that the Payment object is successfully created, even if the Payment Status is Error. Furthermore, the response does not provide the gateway response.
<ns1:result> <ns1:Id>2c92c0f94088cd3c01409df413294e94</ns1:Id> <ns1:Success>true</ns1:Success> </ns1:result>
To see the gateway response to the request, use the payment ID to query the payment object that was created and review the Status, GatewayResponse, and GatewayResponseCode attributes.