Payment
From API Documentation
The Payment is a description of the customer's payment: how much the customer is paying, which invoice or invoices the payment is to be applied to, and the type of payment being made.
Supported Calls
This object is used in the create, query, and delete calls.
(The ability to delete payments was added in version 31).
Fields
In addition to the following fields, zObject contributes additional fields. For information on the field types, see Field Types.
| Name | Required? | Type | Allowed Operations: ● Yes ○ No | Allowable Values | Description |
|---|---|---|---|---|---|
| AccountID | Yes | zns: ID | ● Create
● Query | A valid account ID | A unique identifier for the account this payment is for. |
| AccountingCode | No | String | ○ Create
● Query | A valid accounting code configured within Z-Billing, 100 characters maximum. | The accounting code for the payment. |
| Amount | Yes | double (v1.0-18.0) / decimal (v19.0+) | ● Create
● Query | Any allowable currency values | The amount of the payment. |
| AppliedCreditBalanceAmount | Usually no, but required in create() call if AppliedInvoiceAmount is NULL. | decimal | ● Create
● Query | Any allowable currency values | Only in version 22.0+ of the API, only available to beta customers as of version 22.0. The amount of the payment that should be applied to the credit balance. For customers using credit balance only. |
| AppliedInvoiceAmount | Usually no, but required in create() call if AppliedCreditBalanceAmount is NULL.
| decimal | ● Create
○ Query | Any allowable currency values | Only in version 22.0+ of the API. The amount of the payment that should be applied to the invoice. Only used when applying payment to a single invoice in the create() call. |
| AuthTransactionId | No | string | ● Create
● Query | 50 characters maximum | The authorization transaction Id from the payment gateway. Only applies to electronic payments such as credit and debit cards. |
| BankIdentificationNumber | No, system generated. | string | ○ Create
● Query | 6 characters maximum | Only in version 22.0+ of the API. The first 6 digits of the debit/credit card used for the the payment, if applicable. Valuable when reconciling payments with your gateway and merchant banks. |
| CancelledOn | No | date | ○ Create
● Query | For a cancelled payment, the time that the cancellation occurred. | |
| Comment | No | string | ● Create
● Query | 255 characters maximum | An optional comment on this payment. |
| CreatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | This field is not editable. 32 characters maximum. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who created the object. |
| CreatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was first created. |
| EffectiveDate | Yes | dateTime | ● Create
● Query | A valid date value | The date on which this payment will be effective. |
| GatewayOrderId | No, system generated | string | ● Create
● Query | 70 characters maximum | The Id of the order from the payment gateway. |
| GatewayResponse | No, read-only | string | ○ Create
● Query | Response from the payment gateway | Available in version 9.0+ of the API. The message returned from the payment gateway for a given payment, if any. This is gateway dependent. |
| GatewayResponseCode | No, read-only | string | ○ Create
● Query | Response code from the payment gateway. | Available in version 9.0+ of the API. The code returned from the payment gateway for a given payment, if any. This is gateway dependent. Consult your payment gateway documentation for specific meaning. |
| GatewayState | Yes | string | ○ Create
● Query | NotSubmitted, MarkedForSubmission (Spectrum gateway only), Submitted, Settled | The state of a payment with respect to the payment gateway. |
| InvoiceId | Only when applying payment to a single invoice with the streamlined payment approach (see Basic Use Cases - Applying Payments for details). | ZNS:Id | ● Create
○ Query | Valid invoice ID | Available in version 22.0+ of the API. Only used in the create(), when applying payment to a single invoice or credit balance. |
| InvoiceNumber | Only when applying payment to a single invoice with the streamlined payment approach. | ZNS:Id | ● Create
○ Query | Valid invoice number | Available in version 23.0+ of the API. Only used in the create(), when applying payment to a single invoice or credit balance. |
| MarkedForSubmissionOn | No | date | ○ Create
● Query | The time at which a payment was marked for submission (Spectrum gateway only). | |
| PaymentMethodID | Yes | zns: ID | ● Create
● Query | This value is automatically generated | A valid PaymentMethod ID indicating the method being used to make the payment. |
| PaymentNumber | No, for query() only. Created by Zuora, and not specified in create() call. | string | ○ Create
● Query | This value is automatically generated, 32 characters maximum. | The Zuora payment number for the payment, which is useful when working/searching in the Z-Payments web application. |
| ReferenceId | No | string | ● Create
● Query | 30 characters maximum | A reference ID is the transaction id provided back by the payment gateway. Z-Payments stores this id with the payment which allows for reconciliation of payments between the gateway and the payment in Z-Payments. |
| RefundAmount | No | decimal | ○ Create
● Query | A valid currency amount | The amount of the payment that has been refunded. Null if no refund has been made against this payment. |
| SecondPaymentReferenceId | No | string | ○ Create
● Query | 60 characters maximum | A reference ID is the transaction id provided back by the payment gateway. Z-Payments stores this id with the payment which allows for reconciliation of payments between the gateway and the payment in Z-Payments. |
| SettledOn | No | date | ○ Create
● Query | The settlement date. | |
| SoftDescriptor | No | string | ● Create
● Query | 35 characters maximum | Only used for create(), and only applicable for Orbital and Verifi payment gateways. For Verifi, no verification is done by Zuora, and the field is directly passed. For Orbital, SoftDescriptor holds two fields, SDMerchantName and SDProductionInfo. These fields should be separated by an asterisk, such as [a]*[b], where [a] is passed as SDMerchantName and [b] is passed as SDProductionInfo. |
| SoftDescriptorPhone | No | String | ● Create
● Query | 20 characters maximum | Only used for create(), and only applicable for Orbital and Verifi payment gateways. A properly formatted string (as defined by Verifi and/or Orbital) that is passed as the SDPhone. |
| Status | Yes | string (enum) | ● Create
● Query | Canceled, Draft, Error, Posted, Processing, Processed, Voided | The status of the payment. These are determined by the system. |
| SubmittedOn | No | date | ○ Create
● Query | The date the settlement was submitted. | |
| TransferredToAccounting | No | string | ○ Create
● Query | Processing, Yes, Error, Ignore | Available in version 26.0 and greater. Specifies whether or not the object has been transferred to an external accounting system. Used for integrations with accounting systems such as NetSuite. |
| Type | Yes | string (enum) | ● Create
● Query | External, Electronic | Indicates how the customer is making the payment. |
| UpdatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | This field is not editable. 32 characters maximum. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who last updated the object. |
| UpdatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was last updated. |
