Skip to main content
POST
Create a new refund transaction

Authorizations

X-API-KEY
string
header
required

The authorization key obtained from MarketONE.

Headers

X-B3-TraceId
string

The TraceId indicates the overall ID of the trace. Every span in a trace shares this ID. The X-B3-TraceId header is encoded as 32 or 16 lower-hex characters. For example, a 128-bit TraceId header might look like 463ac35c9f6413ad48485a3953bb6124.

X-B3-SpanId
string

The SpanId is 64-bit in length and indicates the position of the current operation in the trace tree. The value should not be interpreted; it may or may not be derived from the value of the TraceId. The X-B3-SpanId header is encoded as 16 lower-hex characters. For example, a SpanId header might look like a2fb4a1d1a96d312. Unless propagating only the Sampling State, the X-B3-SpanId header is required.

X-B3-ParentSpanId
string

The ParentSpanId is 64-bit in length and indicates the position of the parent operation in the trace tree. When the span is the root of the trace tree, there is no ParentSpanId. The X-B3-ParentSpanId header may be present on a child span and must be absent on the root span. It is encoded as 16 lower-hex characters. For example, a ParentSpanId header might look like 0020000000000001.

Path Parameters

id
string
required

The id parameter is the transaction ID on which the original transaction was processed.

Maximum string length: 36

Body

application/json

A new Refund; required attributes are id, refund items, product code passed in as 'code' for transaction item. Original transaction id is passed as a request parameter.

The Refund object provides a way to reverse a charge, refunding money to the customer. You can create, and retrieve individual Refunds; as well as list all existing Refunds. Refunds require a transaction – a refund can only be executed against an existing, successfully captured transaction. Refunds can be issued for any valid amount (in the currency of the original transaction) up to the as-yet un-refunded balance of the original transaction. You can issue any number of refunds on a given transaction (until it has been fully refunded).

id
string

A unique identifier.

Maximum string length: 128
created
string<date-time>

The date/time at which the refund was requested.

amount
number

Amount of the refund. Must be positive (non-zero) and less than or equal to the as-yet-un-refunded balance of the specified transaction. Ignored if refundItems are specified.

currency
string

The ISO 4217 Currency Code of this transaction; defaults to USD.

note
string

Free-form specified note about refund.

reasonCode
enum<string>

Reason code for refund.

Available options:
fraud,
purchase-not-approved,
entitlement-error,
billing-error,
account-cancelled,
general-error
partnerSubscriptionId
string

A unique identifier.

Maximum string length: 128
refund_distribution_strategy
enum<string>

Defines strategy for distributing refund amount across the original TransactionItems. Default is None.

Available options:
SpecifiedItems,
None
refund_items
object[]

For item-level refunds, specifies the transaction items to refund with details.

metadata
object

A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Response

Successfully created Refund Transaction

The transaction response entity relates to the payment request that can be initiated either by the digital partner in the case of direct carrier billing (BILLING), or the backend billing system of the service provider at the end of every billing cycle.

id
string
required

A unique identifier.

Maximum string length: 128
status
string
required

Status of the transaction once processed (mandatory on the response)

extConfirmationId
string

Transaction identifier

Maximum string length: 36
metadata
object

A set of key/value pairs that you can attach to an object. Useful for storing additional information.