CRUD: Create a refund

Creates a refund.

If you have the Invoice Settlement feature enabled, you can use this operation to unapply the payment from an invoice or multiple invoices, and refund the payment.

If the unapplied payment is left in the following scenarios, you have to reapply the unapplied payment to the original invoices:

  • An electronic refund in Processing status is handled to change to Error. An unapplied payment is left.
  • An electronic refund gets to Error, and payment reapplying fails due to the concurrent issue.
  • The refund canceling operation updates the status of a refund from Processed to Canceled. When it is successful, an unapplied payment is left.
Request
query Parameters
rejectUnknownFields
boolean
Default: false

Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:

{
    "message": "Error - unrecognised fields"
}

By default, Zuora ignores unknown fields in the request body.

header Parameters
Idempotency-Key
string <= 255 characters

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

Accept-Encoding
string

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encoding
string

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Authorization
string

The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Request Body schema: application/json
required
AccountId
string

The ID of the account associated with this refund. This field is only required if you create a 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. Character limit: 32 Values: a valid account ID

Amount
required
number <double>

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 of this operation or through the UI. Character limit: 16 Values: a valid currency amount

Comment
string

Use this field to record comments about the refund. Character limit: 255 Values: a string of 255 characters or fewer

object

A field used to pass gateway options. Zuora allows you to pass in special gateway-specific parameters for payments through the gateway integrations that support gateway options.

For each of these special parameters, you supply the name-value pair and Zuora passes it to the gateway. This allows you to add functionality that's supported by a specific gateway but currently not supported by Zuora.

Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.

GatewayState
string

The status of the payment in the gateway. Character limit: 19 Values: automatically generated

MethodType
string

Indicates how an external refund was issued to a customer. This field is only required if the Type field is set to External. You can issue an external refund on an electronic payment. Character limit: 30 Values:

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

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. Character limit: 32 Values: a valid payment ID

PaymentMethodId
string

The unique ID of the payment method that the customer used to make the payment. This field is only required if you create a non-referenced refund. Character limit: 32 V****alues: a valid payment method ID

ReasonCode
string

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. Character limit: 32 V****alues: a valid reason code

RefundDate
string <date> <= 29 characters

The date of the refund, in yyyy-mm-dd format. The date of the refund cannot be before the payment date. This field is only required if the Type field is set to External. Zuora automatically generates this field for electronic refunds.

With the Future Dated Credit Balance Adjustment feature enabled, you can create a non-referenced refund with a refund date.

  • For external refunds, you can specify any date.
  • For electronic refunds, you can only set the date to the date when the API operation is called or one day later.
object

Container for the refund invoice payment data. This field is only required if you apply a full or partical refund against a payment attached to muliple invoices.

SoftDescriptor
string

A payment gateway-specific field that maps Zuora to other gateways . Character limit: 35 Values:

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

A payment gateway-specific field that maps Zuora to other gateways . Character limit: 20 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
string

Specifies whether the refund is a refund payment or a credit balance. This field is only required if you create a non-referenced refund. If you creating an non-referenced refund, then set this value to CreditBalance. Note: If you have the Invoice Settlement feature enabled, the value of this field can only be set to Payment. Character limit: 13 Values:

  • Payment
  • CreditBalance
Type
required
string

Specifies if the refund is electronic or external. Character limit: 10 Values:

  • Electronic
  • External
IntegrationId__NS
string <= 255 characters

ID of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

IntegrationStatus__NS
string <= 255 characters

Status of the refund's synchronization with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

Origin__NS
string <= 255 characters

Origin of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

SyncDate__NS
string <= 255 characters

Date when the refund was synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

SynctoNetSuite__NS
string <= 255 characters

Specifies whether the refund should be synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

property name*
additional property
any

Custom fields of the Refund object. The name of each custom field has the form customField__c. Custom field names are case sensitive. See Manage Custom Fields for more information.

Responses
200
400
401
post/v1/object/refund
Request samples
application/json
{
  • "AccountId": "2c93808457d787030157e03190e748ea",
  • "Amount": 1.1,
  • "Comment": "this is comments",
  • "PaymentId": "2c93808457d787030157e03197714910",
  • "ReasonCode": "Standard Refund",
  • "RefundInvoicePaymentData": {
    },
  • "SoftDescriptor": "thisSD",
  • "SoftDescriptorPhone": "contact@example.com",
  • "SourceType": "Payment",
  • "Type": "Electronic"
}
Response samples
application/json
{
  • "Success": true,
  • "Id": "2c93808457d787030157e03198c84918"
}