Skip to main content

Refund object

Zuora

Refund object

  1. Last updated
  2. Save as PDF

A refund returns money to a customer - as opposed to a credit, which creates a customer credit balance that may be applied to reduce the amount owed to you. For instance, refunds are used when a customer cancels service and is no longer your customer. Refunds can also represent processed payments that are reversed, such as a chargeback or a direct debit payment reversal.

See Refunds for more information.

A Refund object is used to create and query refunds. There are two types of refunds:

  • Electronic refunds are processed by Zuora via a payment gateway.
  • External refunds indicate that the refund was processed outside of Zuora, say by a check, and the transaction must be recorded.

A RefundInvoicePayment object is created when you create a Refund object. This object ties the Refund object to the associated InvoicePayment object.

Non-Referenced Refunds

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

  • AccountId
  • PaymentMethodId
  • TotalAmount
  • SourceType: Set to CreditBalance
  • Type: Set to Electronic or External

By definition, a non-referenced refund does not require a PaymentId (for example, the ID of the original payment).

A non-referenced refund can be issued to any payment method, including a credit card for Electronic refunds, on the customer's account, and it can use any payment gateway for which Zuora supports this type of transaction. See Canceling and Refunding Credit Balances for a list of supported payment gateways.

Non-referenced refunds are available only if you have enabled the Credit Balance feature. You must create a credit balance before you can create this type of refund.

Supported Calls

You can use this object in the following calls:

A Refund create() call will return Success in the response along with the Refund ID regardless of the gateway response. When processing a refund the create() call refers to the successful creation of the Refund object. It is not an indicator that the payment gateway processed the refund successfully. 

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

optional

Create
Query
Delete
Filter

The ID of the account associated with this refund. Specify a value for this field only if you're creating an electronic non-referenced refund. Don't specify a value for any other type of refund; Zuora associates the refund automatically with the account from the associated payment.

Type: zns:ID
Character limit: 32
Version notes: WSDL 18.0+
Values: a valid account ID

AccountingCode

optional

Query
Filter

The accounting code for the payment or invoice line item that the refund applies to. If there is no accounting code, then this value is null. Accounting codes group transactions that contain similar accounting attributes.

Type: string
Character limit: 50
Version notes: WSDL 18.0+
Values: automatically generated

Amount

required

Create
Query
Delete
Filter

The amount of the refund. The amount can't exceed the amount of the associated payment. If the original payment was applied to a single invoice, you can create a partial refund by specifying an amount in this field or through the UI. If the payment was applied to multiple invoices, you can create a partial refund by using the RefundInvoicePaymentData field or through the UI.

Type: decimal (currency)
Character limit: 16
Version notes: type is double in WSDL 18.0.
Values: a valid currency amount
CancelledOn optional

Query
Filter

The date the refund was cancelled.

Type: dateTime
Character limit: --
Version notes: WSDL 31.0+
Values: automatically generated

Comment

optional

Create
Query
Filter

Use this field to record comments about the refund.

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

CreatedById

optional

Query
Filter

The ID of the Zuora user who created the Refund object.

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

CreatedDate

optional

Query
Filter

The date when the Refund object was created.

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

Gateway

optional

Query
Filter

The gateway that processed the original payment. Zuora uses this same gateway for the corresponding refund. If this payment gateway is no longer active, then the electronic refund fails. A gateway is an online service provider that connects an online shopping cart to a payment processor.

Type: string
Character limit: --
Version notes: WSDL 18.0+
Values: automatically inherited from the Payment object
GatewayOptionData optional

Create
Filter

Use this field to pass gateway options.

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

GatewayResponse

optional

Query
Filter

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

Type: string
Character limit: 500
Version notes: WSDL 18.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 18.0+
SystemValues: automatically generated
GatewayState optional

Query

Filter

The status of the payment in the gateway.

Type: string (enum)
Character limit: 19
Version notes: --
Values: automatically generated
Id optional Query
Filter

The ID of this object. Upon creation of this object, this field becomes RefundId.

Type: zns:ID
Character limit: 32
Values: automatically generated
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

MethodType

optional

Create
Query
Filter

Indicates how an external refund was issued to a customer. This field is required for an external refund. You can issue an external refund on an electronic payment. 

Type: string (enum)
Character limit: 30
Version notes: WSDL 18.0+
Values: 

  • ACH
  • Cash
  • Check
  • CreditCard
  • Other
  • PayPal
  • WireTransfer
  • DebitCard
  • CreditCardReferenceTransaction

PaymentId

optional

Create

 

The unique ID of the payment associated with this refund. Don't specify a value for this field if you're creating an electronic non-referenced refund.

Type: zns:ID
Character limit: 32
Version notes: WSDL 18.0+
Values: a valid payment ID

PaymentMethodId

optional

Create
Query

The unique ID of the payment method that the customer used to make the payment. Specify a value for this field only if you're creating an electronic non-referenced refund.

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

ReasonCode

optional

Create
Query
Update
Filter

A code identifying the reason for the transaction. Must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.

Type: string
Character limit: 32
Version notes: WSDL 44.0+
Values: a valid reason code

ReferenceID

optional

Query
Filter

The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Z-Payments.

Type: string
Character limit: 60
Version notes: WSDL 18.0+
Values: a string of 60 characters or fewer

RefundDate

optional

Create
Query
Filter

The date of the refund. The date of the refund cannot be before the payment date. Specify this field only for external refunds. Zuora automatically generates this field for electronic refunds.

Type: 

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: WSDL 18.0+
Values: a valid date and time value
RefundInvoicePaymentData optional Create

Supports refunds against multiple invoices.

Type: Array
Character limit: -
Version notes: WSDL 64+
Values: RefundInvoicePayment

RefundNumber

optional

Query
Filter

The unique identifier of the refund.

Type: string
Character limit: 50
Version notes: WSDL 18.0+
Values: automatically generated

RefundTransactionTime

optional

Query
Filter

The date and time when the refund was issued.

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

SecondRefundReferenceId

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: WSDL 47+
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 Zuora to other gateways . 

Type: string
Character limit: 35
Version notes: WSDL 18.0+
Values: 

  • 3-byte company identifier "*" 18-byte descriptor
  • 7-byte company identifier "*" 14-byte descriptor
  • 12-byte company identifier "*" 9-byte descriptor

SoftDescriptorPhone

optional

Create
Query
Filter

A payment gateway-specific field that maps Zuora to other gateways . 

Type: string
Character limit: 20
Version notes: WSDL 18.0+
Values: 

  • 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

SourceType

optional

Create
Query
Filter

Specifies whether the refund is a refund payment or a credit balance. This field is required when creating an non-referenced refund. If you creating an non-referenced refund, then set this value to CreditBalance.

Type: string (enum)
Character limit: 13
Version notes: WSDL 18.0+
Values:

  • Payment
  • CreditBalance

Status

optional

Query
Update
Filter

The status of the refund.

Type: string (enum)
Character limit: 10
Version notes: WSDL 18.0+
Values: automatically generated:

  • Canceled
  • Error
  • Processed
  • Processing
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

Specifies whether or not the object has been transferred to an external accounting system. Use this field for integrations with accounting systems such as NetSuite.

Type: string (enum)
Character limit: 10
Version notes: WSDL 26.0+
Values: automatically generated:

  • Processing
  • Yes
  • Error
  • Ignore

Type

required

Create
Query
Filter

Specifies if the refund is electronic or external.

Type: string (enum)
Character limit: 10
Version notes: WSDL 18.0+
Values: 

  • Electronic
  • External

UpdatedById

optional

Query
Filter

The ID of the last user to update the object.

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

UpdatedDate

optional

Query
Filter

The date when the object was last updated.

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

Additional Field Detail

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 Subscription object's ID with the call.

The ID for the Refund object is RefundId.

Code Examples

SOAP: Electronic Refund create() Call

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

SOAP: 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 to the customer through the payment gateway that generated the original Payment. Zuora creates a RefundInvoicePayment object automatically for this transaction.

SOAP: Create a Refund Against Multiple Invoices Using RefundInvoicePaymentData

This method requires WSDL 64 or higher.

<ns1:create xmlns:ns1="http://api.zuora.com/">
    <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Refund">
       <ns2:AccountId>4028924549bdb5e00149bdbc19770011</ns2:AccountId>
       <ns2:Amount>4</ns2:Amount>
       <ns2:PaymentId>4028924549bdb5e00149bdbf164d004d</ns2:PaymentId>
       <ns2:Type>Electronic</ns2:Type>
       <ns2:RefundInvoicePaymentData>
          <ns1:RefundInvoicePayment xsi:type="ns2:RefundInvoicePayment">
             <ns2:RefundAmount>2</ns2:RefundAmount>
             <ns2:InvoiceId>4028924549bdb5e00149bdbed3da0038</ns2:InvoiceId>
          </ns1:RefundInvoicePayment>
          <ns1:RefundInvoicePayment xsi:type="ns2:RefundInvoicePayment">
             <ns2:RefundAmount>2</ns2:RefundAmount>
             <ns2:InvoiceId>402881e849b885fe0149b892f90c007f</ns2:InvoiceId>
          </ns1:RefundInvoicePayment>
       </ns2:RefundInvoicePaymentData>
    </ns1:zObjects>
</ns1:create>