Create a Refund
post
/refund
Creates a refund.
Request
There are no request parameters for this operation.
Supported Media Types
- application/json;charset=utf-8
Root Schema : Refund Create
Type:
object
Title:
Refund Create
A refund for a payment, used in the create refund request. The paymentMethod specified must be the one assigned to the bill unit. If you specify a different payment method, the one assigned to the bill unit will be refunded instead.
Show Source
The id, href, status, statusDate, and refundDate properties are not used in the create request.
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
account(required): object
Account Ref
Title:
Account Ref
An account's reference. -
amount: object
Money
Title:
Money
An amount of money. -
authorizationCode: string
Title:
Authorization code
An authorization code from an external payment gateway. -
channel: object
Channel Ref
Title:
Channel Ref
A reference to a channel. -
correlatorId: string
Title:
correlator ID
An refund correlation ID from a client application. -
description: string
Title:
Refund Description
The refund's description. -
name: string
Title:
Refund Name
The refund's name. -
payment: object
Payment Ref
Title:
Payment Ref
A payment captured as a reference on an order. Used when a payment is made immediately on an order rather than at a later billing date. -
paymentMethod(required): object
Payment Method Ref Or Value
Title:
Payment Method Ref Or Value
A link to the resource containing information about the payment method. -
refundDate: string
(date-time)
Title:
Refund Date
The date when the refund was made. -
requestor: object
Related Party
Title:
Related Party
A party related to another object. -
taxAmount: object
Money
Title:
Money
An amount of money. -
totalAmount(required): object
Money
Title:
Money
An amount of money.
Nested Schema : Account Ref
Type:
object
Title:
Account Ref
An account's reference.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
description: string
Title:
Account Description
The account's description. -
href: string
Title:
Account Href
The account's href. -
id(required): string
Title:
Account ID
The account's ID. -
name: string
Title:
Account Name
The account's name.
Nested Schema : Money
Type:
object
Title:
Money
An amount of money.
Show Source
-
unit: string
Title:
Currency
An ISO 4217 three letter currency code. -
value: number
(float)
Title:
Amount
A positive floating point number.
Nested Schema : Channel Ref
Type:
object
Title:
Channel Ref
A reference to a channel.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
href: string
Title:
Channel Href
The channel's href. -
id(required): string
Title:
Channel ID
The channel's ID. -
name: string
Title:
Channel Name
The channel's name.
Nested Schema : Payment Ref
Type:
object
Title:
Payment Ref
A payment captured as a reference on an order. Used when a payment is made immediately on an order rather than at a later billing date.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
amount: object
Money
Title:
Money
An amount of money. -
href: string
Title:
Payment Href
The payment reference's href. -
id(required): string
Title:
Payment ID
The payment reference's ID. -
name: string
Title:
Payment Name
The payment reference's name.
Nested Schema : Payment Method Ref Or Value
Type:
object
Title:
Payment Method Ref Or Value
A link to the resource containing information about the payment method.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The payment method's type, further refined from the @type value. To create a payment when @type is PaymentMethodRef, this is required, and valid values are tokenizedCard, bankAccountDebit, and bankCard. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type(required): string
Title:
Type
The payment method's type. Valid values are PaymentMethodRef for a credit or debit card, Cash, or Check. When the value is PaymentMethodRef, the payment method specified must be the one assigned to the bill unit. If you specify a different payment method, the one assigned to the bill unit will be used instead. -
account: array
account
Accounts associated with the payment method.
-
description: string
Title:
Payment Method Description
The payment method's description. -
href: string
Title:
Payment Method Href
The payment method's href. -
id(required): string
Title:
Payment Method ID
The payment method's ID. -
isPreferred: boolean
Title:
Payment Method Preferred
Whether this is the preferred payment method (true) or not (false). -
name: string
Title:
Payment Method Name
The payment method's name. - relatedParty: object Related Party
-
status: string
Title:
Status
The payment method's status. -
statusDate: string
(date-time)
Title:
Status Date
The date the payment method's status was recorded. -
validFor: object
Time Period
Title:
Time Period
A period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Nested Schema : Related Party
Type:
object
Title:
Related Party
A party related to another object.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType(required): string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
href: string
Title:
Related Party Href
The related party's href. -
id(required): string
Title:
Related Party ID
The related party's ID. -
name(required): string
Title:
Related Party Name
The related party's name. -
role: string
Title:
Related Party Role
The related party's role.
Nested Schema : account
Type:
array
Accounts associated with the payment method.
Show Source
-
Array of:
object Account Ref
Title:
Account Ref
An account's reference.
Nested Schema : Time Period
Type:
object
Title:
Time Period
A period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Show Source
-
endDateTime: string
(date-time)
Title:
End Time Period
The end of the time period in IETC-RFC-3339 format. -
startDateTime: string
(date-time)
Title:
Start Time Period
The start of the time period in IETC-RFC-3339 format. If you specify this, you must also specify endDateTime.
Response
Supported Media Types
- application/json;charset=utf-8
201 Response
Created
Root Schema : Refund
Type:
object
Title:
Refund
A refund for a payment.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
account(required): object
Account Ref
Title:
Account Ref
An account's reference. -
amount: object
Money
Title:
Money
An amount of money. -
authorizationCode: string
Title:
Authorization code
An authorization code from an external payment gateway. -
channel: object
Channel Ref
Title:
Channel Ref
A reference to a channel. -
correlatorId: string
Title:
correlator ID
An refund correlation ID from a client application. -
description: string
Title:
Refund Description
The refund's description. -
href: string
Title:
Refund Href
The refund's href. -
id: string
Title:
Refund ID
The refund's ID. -
name: string
Title:
Refund Name
The refund's name. -
payment: object
Payment Ref
Title:
Payment Ref
A payment captured as a reference on an order. Used when a payment is made immediately on an order rather than at a later billing date. -
paymentMethod(required): object
Payment Method Ref Or Value
Title:
Payment Method Ref Or Value
A link to the resource containing information about the payment method. -
refundDate: string
(date-time)
Title:
Refund Date
The date when the refund was made. -
requestor: object
Related Party
Title:
Related Party
A party related to another object. -
status: string
Title:
Refund Status
The refund's status. -
statusDate: string
(date-time)
Title:
Status Date
The date when the refund's status was recorded. -
taxAmount: object
Money
Title:
Money
An amount of money. -
totalAmount: object
Money
Title:
Money
An amount of money.
Nested Schema : Account Ref
Type:
object
Title:
Account Ref
An account's reference.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
description: string
Title:
Account Description
The account's description. -
href: string
Title:
Account Href
The account's href. -
id(required): string
Title:
Account ID
The account's ID. -
name: string
Title:
Account Name
The account's name.
Nested Schema : Money
Type:
object
Title:
Money
An amount of money.
Show Source
-
unit: string
Title:
Currency
An ISO 4217 three letter currency code. -
value: number
(float)
Title:
Amount
A positive floating point number.
Nested Schema : Channel Ref
Type:
object
Title:
Channel Ref
A reference to a channel.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
href: string
Title:
Channel Href
The channel's href. -
id(required): string
Title:
Channel ID
The channel's ID. -
name: string
Title:
Channel Name
The channel's name.
Nested Schema : Payment Ref
Type:
object
Title:
Payment Ref
A payment captured as a reference on an order. Used when a payment is made immediately on an order rather than at a later billing date.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
amount: object
Money
Title:
Money
An amount of money. -
href: string
Title:
Payment Href
The payment reference's href. -
id(required): string
Title:
Payment ID
The payment reference's ID. -
name: string
Title:
Payment Name
The payment reference's name.
Nested Schema : Payment Method Ref Or Value
Type:
object
Title:
Payment Method Ref Or Value
A link to the resource containing information about the payment method.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType: string
Title:
Referred Type
The payment method's type, further refined from the @type value. To create a payment when @type is PaymentMethodRef, this is required, and valid values are tokenizedCard, bankAccountDebit, and bankCard. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON-Schema file that defines additional attributes and relationships. -
@type(required): string
Title:
Type
The payment method's type. Valid values are PaymentMethodRef for a credit or debit card, Cash, or Check. When the value is PaymentMethodRef, the payment method specified must be the one assigned to the bill unit. If you specify a different payment method, the one assigned to the bill unit will be used instead. -
account: array
account
Accounts associated with the payment method.
-
description: string
Title:
Payment Method Description
The payment method's description. -
href: string
Title:
Payment Method Href
The payment method's href. -
id(required): string
Title:
Payment Method ID
The payment method's ID. -
isPreferred: boolean
Title:
Payment Method Preferred
Whether this is the preferred payment method (true) or not (false). -
name: string
Title:
Payment Method Name
The payment method's name. - relatedParty: object Related Party
-
status: string
Title:
Status
The payment method's status. -
statusDate: string
(date-time)
Title:
Status Date
The date the payment method's status was recorded. -
validFor: object
Time Period
Title:
Time Period
A period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Nested Schema : Related Party
Type:
object
Title:
Related Party
A party related to another object.
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@referredType(required): string
Title:
Referred Type
The object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
href: string
Title:
Related Party Href
The related party's href. -
id(required): string
Title:
Related Party ID
The related party's ID. -
name(required): string
Title:
Related Party Name
The related party's name. -
role: string
Title:
Related Party Role
The related party's role.
Nested Schema : account
Type:
array
Accounts associated with the payment method.
Show Source
-
Array of:
object Account Ref
Title:
Account Ref
An account's reference.
Nested Schema : Time Period
Type:
object
Title:
Time Period
A period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Show Source
-
endDateTime: string
(date-time)
Title:
End Time Period
The end of the time period in IETC-RFC-3339 format. -
startDateTime: string
(date-time)
Title:
Start Time Period
The start of the time period in IETC-RFC-3339 format. If you specify this, you must also specify endDateTime.
400 Response
Bad Request
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
401 Response
Unauthorized
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
403 Response
Forbidden
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
405 Response
Method Not allowed
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
409 Response
Conflict
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
500 Response
Internal Server Error
Root Schema : Error
Type:
object
Title:
Error
Used when an API returns an error, typically with a HTTP error response-code such as 401 (Unauthorized) or 500 (Internal Server Error).
Show Source
-
@baseType: string
Title:
Base Type
The object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema Location
A URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
Type
The object's subclass. -
code(required): string
Title:
Error Code
An application's error code, defined in the API or a common list. -
message: string
Title:
Error Message
More details and corrective actions related to the error. -
reason(required): string
Title:
Reason
The reason for the error. -
referenceError: string
(uri)
Title:
Reference Error
A URI to documentation describing the error. -
status: string
Title:
Error Status
The HTTP Error code extension
Examples
The following example shows how to create a refund by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.
The -d option specifies the file to attach as the request body.
curl -X POST 'http://host:port/brm/payment/version/refund' -d @refundCreate.json
Example of Request Body
The following is an example of the contents of the refundCreate.json file sent as the request body.
{ "@type": "RefundCreate", "account": { "id": "0.0.0.1+-account+84808" }, "paymentMethod": { "id": "0.0.0.1+-payinfo-dd+249648", "@type": "PaymentMethodRef" }, "totalAmount": { "value": 10, "unit": "USD" }, "description": "Refunding service fee." }
Example of Response Body
The following example shows the contents of the response body in JSON format.
{ "id": "0.0.0.1+-item-refund+82547", "href": "http://host:port/brm/payment/version/refund/0.0.0.1+-item-refund+82547", "authorizationCode": null, "correlatorId": "R1-30", "description": "Item refund", "name": "Billing Event Log", "refundDate": "2025-12-09T00:38:15-08:00", "status": "Success", "statusDate": "2025-12-09T00:38:15-08:00", "account": { "id": "0.0.0.1+-account+84808", "href": null, "description": null, "name": "Grace Wang", "@baseType": null, "@schemaLocation": null, "@type": null, "@referredType": "billingAccount" }, "amount": null, "channel": { "id": "0", "href": null, "name": "Unspecified", "@baseType": null, "@schemaLocation": null, "@type": null, "@referredType": null }, "payment": null, "paymentMethod": { "id": "0.0.0.1+-payinfo-dd+249648", "href": null, "description": null, "isPreferred": true, "name": "Grace Wang's Direct Debit Account", "status": null, "statusDate": null, "account": "0.0.0.1+-account+104221", "relatedParty": null, "validFor": null, "@baseType": "PaymentMethodRefOrValue", "@schemaLocation": null, "@type": "PaymentMethodRef", "@referredType": null }, "requestor": null, "taxAmount": null, "totalAmount": { "unit": "USD", "value": 10.0 }, "@baseType": "Refund", "@schemaLocation": null, "@type": "Refund" }