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:
objectTitle:
Refund CreateA 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
account(required): object
Account Ref
Title:
Account RefAn account's reference. -
amount: object
Money
Title:
MoneyAn amount of money. -
authorizationCode: string
Title:
Authorization codeAn authorization code from an external payment gateway. -
channel: object
Channel Ref
Title:
Channel RefA reference to a channel. -
correlatorId: string
Title:
correlator IDAn refund correlation ID from a client application. -
description: string
Title:
Refund DescriptionThe refund's description. -
name: string
Title:
Refund NameThe refund's name. -
payment: object
Payment Ref
Title:
Payment RefA 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 ValueA link to the resource containing information about the payment method. -
refundDate: string
(date-time)
Title:
Refund DateThe date when the refund was made. -
requestor: object
Related Party
Title:
Related PartyA party related to another object. -
taxAmount: object
Money
Title:
MoneyAn amount of money. -
totalAmount(required): object
Money
Title:
MoneyAn amount of money.
Nested Schema : Account Ref
Type:
objectTitle:
Account RefAn account's reference.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
description: string
Title:
Account DescriptionThe account's description. -
href: string
Title:
Account HrefThe account's href. -
id(required): string
Title:
Account IDThe account's ID. -
name: string
Title:
Account NameThe account's name.
Nested Schema : Money
Type:
objectTitle:
MoneyAn amount of money.
Show Source
-
unit: string
Title:
CurrencyAn ISO 4217 three letter currency code. -
value: number
(float)
Title:
AmountA positive floating point number.
Nested Schema : Channel Ref
Type:
objectTitle:
Channel RefA reference to a channel.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Channel HrefThe channel's href. -
id(required): string
Title:
Channel IDThe channel's ID. -
name: string
Title:
Channel NameThe channel's name.
Nested Schema : Payment Ref
Type:
objectTitle:
Payment RefA 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 TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
amount: object
Money
Title:
MoneyAn amount of money. -
href: string
Title:
Payment HrefThe payment reference's href. -
id(required): string
Title:
Payment IDThe payment reference's ID. -
name: string
Title:
Payment NameThe payment reference's name.
Nested Schema : Payment Method Ref Or Value
Type:
objectTitle:
Payment Method Ref Or ValueA link to the resource containing information about the payment method.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe 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 LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type(required): string
Title:
TypeThe 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 DescriptionThe payment method's description. -
href: string
Title:
Payment Method HrefThe payment method's href. -
id(required): string
Title:
Payment Method IDThe payment method's ID. -
isPreferred: boolean
Title:
Payment Method PreferredWhether this is the preferred payment method (true) or not (false). -
name: string
Title:
Payment Method NameThe payment method's name. - relatedParty: object Related Party
-
status: string
Title:
StatusThe payment method's status. -
statusDate: string
(date-time)
Title:
Status DateThe date the payment method's status was recorded. -
validFor: object
Time Period
Title:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Nested Schema : Related Party
Type:
objectTitle:
Related PartyA party related to another object.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType(required): string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Related Party HrefThe related party's href. -
id(required): string
Title:
Related Party IDThe related party's ID. -
name(required): string
Title:
Related Party NameThe related party's name. -
role: string
Title:
Related Party RoleThe related party's role.
Nested Schema : account
Type:
arrayAccounts associated with the payment method.
Show Source
-
Array of:
object Account Ref
Title:
Account RefAn account's reference.
Nested Schema : Time Period
Type:
objectTitle:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Show Source
-
endDateTime: string
(date-time)
Title:
End Time PeriodThe end of the time period in IETC-RFC-3339 format. -
startDateTime: string
(date-time)
Title:
Start Time PeriodThe 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:
objectTitle:
RefundA refund for a payment.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
account(required): object
Account Ref
Title:
Account RefAn account's reference. -
amount: object
Money
Title:
MoneyAn amount of money. -
authorizationCode: string
Title:
Authorization codeAn authorization code from an external payment gateway. -
channel: object
Channel Ref
Title:
Channel RefA reference to a channel. -
correlatorId: string
Title:
correlator IDAn refund correlation ID from a client application. -
description: string
Title:
Refund DescriptionThe refund's description. -
href: string
Title:
Refund HrefThe refund's href. -
id: string
Title:
Refund IDThe refund's ID. -
name: string
Title:
Refund NameThe refund's name. -
payment: object
Payment Ref
Title:
Payment RefA 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 ValueA link to the resource containing information about the payment method. -
refundDate: string
(date-time)
Title:
Refund DateThe date when the refund was made. -
requestor: object
Related Party
Title:
Related PartyA party related to another object. -
status: string
Title:
Refund StatusThe refund's status. -
statusDate: string
(date-time)
Title:
Status DateThe date when the refund's status was recorded. -
taxAmount: object
Money
Title:
MoneyAn amount of money. -
totalAmount: object
Money
Title:
MoneyAn amount of money.
Nested Schema : Account Ref
Type:
objectTitle:
Account RefAn account's reference.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
description: string
Title:
Account DescriptionThe account's description. -
href: string
Title:
Account HrefThe account's href. -
id(required): string
Title:
Account IDThe account's ID. -
name: string
Title:
Account NameThe account's name.
Nested Schema : Money
Type:
objectTitle:
MoneyAn amount of money.
Show Source
-
unit: string
Title:
CurrencyAn ISO 4217 three letter currency code. -
value: number
(float)
Title:
AmountA positive floating point number.
Nested Schema : Channel Ref
Type:
objectTitle:
Channel RefA reference to a channel.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Channel HrefThe channel's href. -
id(required): string
Title:
Channel IDThe channel's ID. -
name: string
Title:
Channel NameThe channel's name.
Nested Schema : Payment Ref
Type:
objectTitle:
Payment RefA 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 TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
amount: object
Money
Title:
MoneyAn amount of money. -
href: string
Title:
Payment HrefThe payment reference's href. -
id(required): string
Title:
Payment IDThe payment reference's ID. -
name: string
Title:
Payment NameThe payment reference's name.
Nested Schema : Payment Method Ref Or Value
Type:
objectTitle:
Payment Method Ref Or ValueA link to the resource containing information about the payment method.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType: string
Title:
Referred TypeThe 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 LocationA URI to a JSON-Schema file that defines additional attributes and relationships. -
@type(required): string
Title:
TypeThe 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 DescriptionThe payment method's description. -
href: string
Title:
Payment Method HrefThe payment method's href. -
id(required): string
Title:
Payment Method IDThe payment method's ID. -
isPreferred: boolean
Title:
Payment Method PreferredWhether this is the preferred payment method (true) or not (false). -
name: string
Title:
Payment Method NameThe payment method's name. - relatedParty: object Related Party
-
status: string
Title:
StatusThe payment method's status. -
statusDate: string
(date-time)
Title:
Status DateThe date the payment method's status was recorded. -
validFor: object
Time Period
Title:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Nested Schema : Related Party
Type:
objectTitle:
Related PartyA party related to another object.
Show Source
-
@baseType: string
Title:
Base TypeThe object's superclass. -
@referredType(required): string
Title:
Referred TypeThe object's type in the target system, if baseType and type need further disambiguation. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
href: string
Title:
Related Party HrefThe related party's href. -
id(required): string
Title:
Related Party IDThe related party's ID. -
name(required): string
Title:
Related Party NameThe related party's name. -
role: string
Title:
Related Party RoleThe related party's role.
Nested Schema : account
Type:
arrayAccounts associated with the payment method.
Show Source
-
Array of:
object Account Ref
Title:
Account RefAn account's reference.
Nested Schema : Time Period
Type:
objectTitle:
Time PeriodA period of time. You can specify only endDateTime or both endDateTime and startDateTime.
Show Source
-
endDateTime: string
(date-time)
Title:
End Time PeriodThe end of the time period in IETC-RFC-3339 format. -
startDateTime: string
(date-time)
Title:
Start Time PeriodThe 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:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
401 Response
Unauthorized
Root Schema : Error
Type:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
403 Response
Forbidden
Root Schema : Error
Type:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
405 Response
Method Not allowed
Root Schema : Error
Type:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
409 Response
Conflict
Root Schema : Error
Type:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe HTTP Error code extension
500 Response
Internal Server Error
Root Schema : Error
Type:
objectTitle:
ErrorUsed 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 TypeThe object's superclass. -
@schemaLocation: string
(uri)
Title:
Schema LocationA URI to a JSON schema file that defines additional attributes and relationships. -
@type: string
Title:
TypeThe object's subclass. -
code(required): string
Title:
Error CodeAn application's error code, defined in the API or a common list. -
message: string
Title:
Error MessageMore details and corrective actions related to the error. -
reason(required): string
Title:
ReasonThe reason for the error. -
referenceError: string
(uri)
Title:
Reference ErrorA URI to documentation describing the error. -
status: string
Title:
Error StatusThe 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"
}