Refund

From API Documentation

This page describes the API used to create and query refunds. Note that refunds imply that money has been returned to customers. You should use adjustments (credit memos) for issuing credit to customers, but are not returning funds to a customer. Also, refunds must be applied against a previous payment, and cannot exceed payment amount.

Note: Refunds are available only in version 18.0 and higher of the Z-Commerce API.

This topic includes examples of a valid SOAP request call and response for creating an electronic refund.

Supported Calls

This object is used in the create and query calls.

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	No. (Yes for electronic non-referenced refunds.)	zns:ID	● Create ● Query ○ Update ● Delete ● Filter	A valid account number	The customer account ID. This is the Zuora-created ID, not the AccountNumber for the Account object. Do not specify the account ID when creating a refund, Zuora will automatically associate it to the account from the payment that the refund is tied to. This field is required when creating an electronic non-referenced refund.
AccountingCode	No, read-only	string	○ Create ● Query ○ Update ○ Delete ● Filter	A valid accounting code, 100 characters maximum.	Zuora will automatically populate the accounting code for the refund for the payment or invoice line item that it applies to. If there was no AccountingCode, then this remains Null.
Amount	Yes	double	● Create ● Query ○ Update ● Delete ● Filter	A valid currency amount	The amount the refund. Cannot exceed the amount of the payment the refund is applied to. Partial refunds are allowed when the original payment was made to a single invoice. If the payment was applied to multiple invoices, only a full refund is allowed via the API.
Comment	No	string	● Create ● Query ○ Update ○ Delete ● Filter	255 characters maximum	Use this optional field to add a note to the refund.
CreatedById	System generated, always exists.	zns:ID	○ Create ● Query ○ Update ○ Delete ● Filter	32 characters maximum. This field cannot be edited.	The Zuora system automatically generates the ID of the user who created the object.
CreatedDate	System generated, always exists.	dateTime	○ Create ● Query ○ Update ○ Delete ● Filter	This field cannot be edited.	The Zuora system automatically generates this value, which records when the object was created.
Gateway	No	string	○ Create ● Query ○ Update ○ Delete ● Filter	A valid name of one of the gateways.	The gateway used to process the original payment will be used to process the refund. If the payment gateway is no longer active, an electronic refund will fail.
GatewayResponse	No, read-only	string	○ Create ● Query ○ Update ○ Delete ● Filter	Response from the payment gateway, 500 characters maximum.	The message returned from the payment gateway for a given payment, if any. This is gateway dependent.
GatewayResponseCode	No, read-only	string	○ Create ● Query ○ Update ○ Delete ● Filter	Response code from the payment gateway, 20 characters maximum.	The code returned from the payment gateway for a given payment, if any. This is gateway dependent. Please consult your payment gateway documentation for specific meaning.
MethodType	No. Required for external refunds.	string	● Create ● Query ○ Update ○ Delete ● Filter	A valid external PaymentMethod type: ACH, Cash, Check, CreditCard, Other, PayPal, WireTransfer, DebitCard, CreditCardReferenceTransaction	Denotes how an external refund was issued (paid out) to a customer.
PaymentId	Yes for `create()` only. Not available for `query()`.	ID	● Create ○ Query ○ Update ○ Delete ○ Filter	A valid PaymentId from previous payment.	The reference of a previous payment to which a refund is applied. You can only apply a refund against a previous payment. You must reference this payment by its PaymentId. Please note that this is a helper field for `create()` only, as Zuora automatically creates the RefundInvoicePayment, which links the payment to the refund. PaymentId is not available for `query()`. See RefundInvoicePayment for more information. This field is non required when creating an electronic non-referenced refund.
PaymentMethodID	No (Yes for electronic non-referenced refunds)	string	● Create ● Query ○ Update ○ Delete ○ Filter		A valid PaymentMethod ID indicating the method being used to make the payment. This field is required when creating an electronic non-referenced refund.
ReferenceId	No, read-only. Returned by the gateway for electronic refunds.	string	○ Create ● Query ○ Update ○ Delete ● Filter	A valid ReferenceId from the gateway, 60 characters maximum.	The reference of the gateway transaction.
RefundDate	Depends. Only specify for external refunds. Zuora populates this for electronic refunds with the current date.	dateTime	● Create ● Query ○ Update ○ Delete ● Filter	A valid datetime	The date of the refund. The date of the refund cannot be before the Payment date.
RefundNumber	No, read-only. This is auto-generated by Zuora.	string	○ Create ● Query ○ Update ○ Delete ● Filter	A valid refund number.	A number/identifier for the refund.
RefundTransactionTime	No, automatically generated.	dateTime	○ Create ● Query ○ Update ○ Delete ● Filter	A valid datetime.	The date and time when the refund was issued.
SoftDescriptor	No	string	● Create ● Query ○ Update ○ Delete ● Filter	35 characters	Used for `read()` and `create()`, and applicable only for the Spectrum payment gateway. The following formats are supported: 3-byte company identifier "" 18-byte descriptor 7-byte company identifier "" 14-byte descriptor 12-byte company identifier "*" 9-byte descriptor If you are considering Spectrum as your payment gateway, please contact Zuora Support for more information about support for this gateway.
SoftDescriptorPhone	No	string	● Create ● Query ○ Update ○ Delete ● Filter	20 characters	Used for `read()` and `create()`, and applicable only for the Spectrum payment gateway. The following formats are supported: Customer service phone number formatted as: NNN-NNN-NNNN or NNN-AAAAAAA URL (non-e-Commerce): Transactions sent with a URL do not qualify for the best interchange rate. Email address If you are considering Spectrum as your payment gateway, please contact Zuora Support for more information about support for this gateway.
SourceType	No. For `query()` and `create()` only. Yes if you are creating an electronic non-referenced refund.	string	● Create ● Query ○ Update ○ Delete ● Filter	Payment or CreditBalance	Specifies whether the refund is a refund payment or a credit balance. This field is required when creating an electronic non-referenced refund. If you creating an electronic non-referenced refund, set this to `CreditBalance`.
Status	Never specified in the create call, as it is system generated.	string (enum)	○ Create ● Query ● Update ○ Delete ● Filter	Canceled, Error, Processed, Processing	The status of the refund. These statuses are determined by the system.
TransferredToAccounting	No	string	○ Create ● Query ● Update ○ Delete ● Filter	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	● Create ● Query ○ Update ○ Delete ● Filter	Electronic, External	Specifies if the refund is electronic or external.
UpdatedById	System generated, always exists	ZNS:id	○ Create ● Query ○ Update ○ Delete ● Filter	32 characters maximum. This field cannot be edited.	The Zuora system automatically generates this ID of the user who last updated the object.
UpdatedDate	System generated, always exists	dateTime	○ Create ● Query ○ Update ○ Delete ● Filter	This field cannot be edited.	The Zuora system automatically generates this to record when the object was last updated.

Electronic Non-Referenced Refunds

As of API version 31.0+, you can electronically refund payments. The refund is not related to a specific payment, and can be refunded to any credit card listed in the account.

This feature is available only if you have enabled the Credit Balance feature. (You must create a Credit Balance to be able to create a refund.)

The following fields are required to create an electronic non-referenced refund:

AccountId
PaymentMethodId
TotalAmount
SourceType: Set this to CreditBalance
Type: Set this to Electronic

You do not need to specify the PaymentId when creating an electronic non-referenced refund.

See Creating an Electronic Non-Referenced Refund for Verifi and Orbital Payment Gateways for more information.

Examples

Example of a valid electronic refund create() call:

<ns1:create>
  <ns1:zObjects xsi:type="ns1:Refund">
     <ns2:Amount>5</ns2:Amount>
     <ns2:Comment>Refund for not applying discount.</ns2:Comment>
     <ns2:PaymentId>4028e69926c4da560126e8b1785c3b2a</ns2:PaymentId>
     <ns2:Type>Electronic</ns2:Type>
  </ns1:zObjects>
</ns1:create>

Example of a valid electronic refund create() response:

<ns1:createResponse xmlns:ns1="http://api.zuora.com/">
  <ns1:result>
     <ns1:Id>4028e6992745e8af012759c3deaf5459</ns1:Id>
     <ns1:Success>true</ns1:Success>
  </ns1:result>
</ns1:createResponse>

Upon successful creation of an electronic refund, money is refunded back to the customer via the payment gateway where the charge generated. Zuora will create a RefundInvoicePayment automatically with this API transaction.

Refund

From API Documentation

Contents

Supported Calls

Fields

Electronic Non-Referenced Refunds

Examples

Views

Search

Important!

Getting Started

Z-Commerce API Fundamentals

Z-Commerce API Reference

Personal tools