Refund a Payment

Refund a payment by refunding its underlying Transaction. Lydian recalculates the correct amount of the underlying crypto asset to return, accounting for the current exchange rate and network gas fee.

Prerequisites

  • An API Key (ak_...) — refunds are a server-to-server operation. See Authentication & Environments.
  • The X-MID header identifying the merchant the transaction belongs to.
  • A transaction that has succeeded (status 1). Only a completed payment can be refunded — see Payment Lifecycle & Statuses.

How refunds fit the payment lifecycle

A refund reverses the flow of funds after a transaction has been paid. Because crypto amounts and exchange rates move over time, Lydian converts the refund at the current rate and reduces the returned amount by the current gas fee.

For example, if a customer paid $100 in TRX two weeks ago, the refund is calculated using today's exchange rate and gas fee before returning the resulting amount in TRX.

Use the optional gasFeePayer field (merchant or customer) to control who absorbs the network fee. When omitted, the refund amount is reduced by the current gas fee.

Create the refund

Send a refund request against the transaction. See Create A Refund for the full request and response schema.

POST
/account/{accountID}/transaction/{transactionID}/refund
curl --location '{API_BASE_URL}/account/{ACCOUNT_ID}/transaction/{TRANSACTION_ID}/refund' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MID}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": {AMOUNT_IN_FLOAT},
    "gasFeePayer": "merchant"
}'

The response is an array of refund objects, each with a refundID and the assetAmount returned.

Check the result

The refund appears in the transaction's refunds array — retrieve it with GET /transaction/{transactionID}. For the exact refund request and response fields, see the Refunds API reference.