Skip to main content

Payment object

Zuora

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
Query
Filter

The unique account ID for the customer that the payment is for.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

AccountingCode

optional

Create
Query
Update
Filter

The accounting code for the payment. Accounting codes group transactions that contain similar accounting attributes.

Type: string
Character limit: 100
Version notes: --
Values: an active accounting code in your Zuora Chart of Accounts

Amount

required

Create
Query
Filter

The amount of the payment.

Type: decimal (currency)
Character limit: 16
Version notes: type is double for WSDL18.0 and older
Values: a valid currency value

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)
Character limit: 16
Version notes: --
Values: a valid currency value

This field is only available if you have the Invoice Settlement feature enabled.

AppliedCreditBalanceAmount

required

Create
Query
Delete
Filter

The amount of the payment to apply to a credit balance. This field is required in a create() call when the AppliedInvoiceAmount field value is null.

Type: decimal (currency)
Character limit: 16
Version notes: WSDL 22.0+. Requires access to credit balances.
Values: a valid currency value

AppliedInvoiceAmount

required

Create
Delete

The amount of the payment to apply to an invoice. 

Type: decimal (currency)
Character limit: 16
Version notes: valid from WSDL 22.0 +
Values: a valid currency value

AuthTransactionId

optional

Create
Query
Delete
Filter

The authorization transaction ID from the payment gateway. Use this field for electronic payments, such as credit cards.

Type: string
Character limit: 50
Version notes: --
Values: a string of 50 characters or fewer

BankIdentificationNumber

optional

Query
Filter

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
Character limit: 8
Version notes: WSDL 22.0+
Values: automatically generated

CancelledOn

optional

Query
Filter

The date when the payment was canceled.

Type: dateTime
Character limit: 29
Version notes: --
Values: automatically generated

Comment

optional

Create
Query
Filter

Additional information related to the payment.

Type: string
Character limit: 255
Version notes: --
Values: a string of 255 characters or fewer

CreatedById

required

Query
Filter

The user ID of the person who created the Payment object.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

CreatedDate

required

Query
Filter

The date when the Payment object was created in the Zuora system.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values automatically generated

EffectiveDate

required

Create
Query
Filter

The date when the payment takes effect.

Type:

  • date: Supported as of WSDL version 69+

  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: --
Values: a valid date and time value. For more information, see Date and dateTime Formats.

Gateway

optional

Create
Query
Filter

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
Filter

Use this field to pass gateway options.

Type: zns:GatewayOption
Character limit: 255
Version notes: WSDL 18.0+
Values: GatewayOption

GatewayOrderId

optional

Create
Query
Delete
Filter

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
Character limit: 70
Version notes: --
Values: a string of 70 characters or fewer

GatewayResponse

optional

Query
Filter

The message returned from the payment gateway for the payment. This message is gateway-dependent.

Type: string
Character limit: 500
Version notes: WSDL 9.0+
Values: automatically generated

GatewayResponseCode

optional

Query
Filter

The code returned from the payment gateway for the payment. This code is gateway-dependent.

Type: string
Character limit: 20
Version notes: WSDL 9.0+
Values: automatically generated

GatewayState

optional

Query
Filter

The status of the payment in the gateway; use for reconciliation.

Type: string (enum)
Character limit: 19
Version notes: --
Values: automatically generated

Id

optional

Query
Filter

The ID of this object. Upon creation, the ID of this object is PaymentId.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid object ID

InvoiceId

optional

Create

 

The ID of the invoice that the payment is applied to. 

Type: zns:ID
Character limit: 32
Version notes: Valid from WSDL 22.0+
Values: a valid invoice ID

InvoiceNumber

optional

Create

The unique identification number for the invoice that the payment is applied to.

Type: string
Character limit: 255
Version notes: WSDL 23.0+
Values: a unique number of 255 characters or fewer

InvoicePaymentData

optional

n/a

A container of InvoicePayment. This field can be treated as an array or a list.

Type: array
Character limit:  Less than or equal to 200 InvoicePayment instances are allowed to pass into it
Version notes: WSDL 64+
Values: Only InvoicePayment instance is allowed, all others will be ignored

MarkedForSubmissionOn

optional

Query
Filter

The date when a payment was marked and waiting for batch submission to the payment process. 

Type: dateTime
Character limit: 29
Version notes: --
Values: automatically generated

PaymentMethodId

optional

Create
Query
Filter

The ID of the payment method used for the payment. Required for Create.

Type: zns:ID
Character limit: 32
Version notes: --
Values: automatically generated

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
Character limit: 32
Version notes: WSDL 60.0+
Values: a valid payment method snapshot ID

PaymentNumber

optional

Query
Filter

The unique identification number of a payment. For example: P-00000028.

Type: string
Character limit: 32
Version notes: WSDL 23.0+
Values: automatically generated

ReferenceId

optional

Create
Query
Filter

The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Z-Payments.

Type: string
Character limit: 60
Version notes: --
Values: a string of 60 characters or fewer

RefundAmount

optional

Query
Filter

The amount of the payment that is refunded. This field is null if no refund is made against the payment.

Type: decimal (currency)
Character limit16
Version notes: --
Values: automatically generated

SecondPaymentReferenceId

optional

Query
Filter

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
Character limit: 60
Version notes: --
Values: a string of 60 characters or fewer

SettledOn

optional

Query
Filter

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
Character limit: 29
Version notes: --
Values: automatically generated

SoftDescriptor

optional

Create
Query
Filter

A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi

Type: string
Character limit: 35
Version notes: --
Values[SDMerchantName]*[SDProductionInfo]

SoftDescriptorPhone

optional

Create
Query
Filter

A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi

Type: string
Character limit: 20
Version notes: --
Values[SDPhone]

Source

optional

Query

Indicates how the payment was created, whether through API, manually, import, or payment run.

Type: string
Character limit
Version notes: WSDL 65+
Values: PaymentRun, Import, Manually, and API

SourceName

optional

Query

Name of the source.

Type: string
Character limit
Version notes: WSDL 65+
Values: PaymentRun number or a file name.

Status

required

Create
Update*
Query
Filter

The status of the payment in Zuora. The value depends on the type of payment.

Type: string (enum)
Character limit: 11
Version notes: --
Values

  • For Create:
    • Processed

  • For Update: One of the following:

    • Voided

    • Canceled

See Troubleshooting Payment Runs for more information.

* Update of status can change value from Processed to Voided for Electronic payment and to Canceled for External payment.

SubmittedOn

optional

Query
Filter

The date when the payment was submitted.

Type: dateTime
Character limit: 29
Version notes: --
Values: automatically generated

TransferredToAccounting

optional

Query
Update
Filter

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)
Character limit: 11
Version notes: --
ValuesProcessingYesErrorIgnore

Type

required

Create
Query
Filter

Indicates if the payment is external or electronic.

Type: string (enum)
Character limit: 10
Version notes: --
Values: External, Electronic

UnappliedAmount optional

Query
Filter

The unapplied amount of the payment.

Type: decimal (currency)
Character limit: 16
Version notes: --
Values: a valid currency value

This field is only available if you have the Invoice Settlement feature enabled.

UpdatedById

No

Query
Filter

The ID of the user who last updated the payment.

Type: zns:ID
Character limit
Version notes: --
Values: automatically generated

UpdatedDate

No

Query
Filter

The date when the payment was last updated.

Type: dateTime
Character limit
Version notes: --
Values Values: automatically generated

 

Additional Field Detail

GatewayOrderId

A merchant-specified natural key value that can be passed to the payment gateway when an electronic payment is created.

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:

  • NotSubmitted
  • Submitted
  • Settled
  • FailedToSettle

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.