Refund Transaction

POST

/api/Transactions/{id}/refund

curl --request POST \
  --url https://example.com/api/Transactions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "merchantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "amount": 1, "reason": "example" }'

Issues a full or partial refund for an approved transaction. A new (negative-amount) refund transaction is created and the original is marked Refunded.

POST /api/transactions/{id}/refund
{
    "amount": 12.50,
    "reason": "Customer cancelled within trial"
}

Authorizations

• Bearer

Parameters

Path Parameters

id

required

string format: uuid

The transaction’s identifier.

Header Parameters

Idempotency-Key

required

string

<= 255 characters

Required. A unique value (a UUID is ideal) per logical operation; reuse it when retrying that operation. A retry with the same key and body replays the original response instead of running twice. A 4xx frees the key, so the operation can be corrected and retried on it. A 5xx does not: the attempt may already have moved money, so retries with that key replay a problem+json saying the outcome is unknown, and a genuinely fresh attempt needs a new key. Missing → 400.

Request Body

Refund payload.

object

id

string format: uuid

merchantId

string format: uuid

amount

number format: double

nullable >= 0.01

reason

string

nullable <= 500 characters

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "merchantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "amount": 1,
  "reason": "example"
}

object

id

string format: uuid

merchantId

string format: uuid

amount

number format: double

nullable >= 0.01

reason

string

nullable <= 500 characters

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "merchantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "amount": 1,
  "reason": "example"
}

object

id

string format: uuid

merchantId

string format: uuid

amount

number format: double

nullable >= 0.01

reason

string

nullable <= 500 characters

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "merchantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "amount": 1,
  "reason": "example"
}

Responses

201

Refund recorded.

Media type application/json

object

id

string format: uuid

merchantId

string format: uuid

memberId

string format: uuid

nullable

memberName

string

nullable

subscriptionId

string format: uuid

nullable

invoiceId

string format: uuid

nullable

paymentMethodId

string format: uuid

nullable

status

string

Allowed values: Processing Approved Declined Refunded Voided

amount

number format: double

currency

string

nullable

reference

string

nullable

description

string

nullable

declineCode

string

nullable

cardInfo

string

nullable

processedAt

string format: date-time

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

Example

{
  "status": "Processing"
}

400

Validation failed - check the errors object.

Media type application/json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

No transaction with the given ID exists.

Media type application/json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

409

The transaction can’t be refunded: it isn’t an approved charge, it never reached the gateway, or the amount exceeds what is still refundable.

Media type application/json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

422

The gateway declined the refund or could not confirm it. Nothing was recorded and the original charge is unchanged.

Media type application/json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}