---
title: "Refund a transaction"
method: POST
path: "/pay/v3/refund"
tags: ["Ecommerce"]
---

# Refund a transaction

`POST /pay/v3/refund`

Allows you to refund all or part of a previous credit card, debit card, or echeck transaction using the Nexio Payment ID. In order to refund a transaction, it must have already settled.

The entire process for refunding a transaction is as follows: 
1. Run a transaction using the [Run card transaction](https://docs.nexiopay.com/reference/runcardtransaction) or [Run echeck transaction](https://docs.nexiopay.com/reference/runechecktransaction) endpoint.
2. Retrieve the `id` from the response. This is the Nexio Payment ID.
3. Use the dashboard from the gateway connection that processed the transaction to manually settle the transaction if that is possible (or wait for the transaction to settle). Note that you can use the [Nexio mock gateway](https://docs.nexiopay.com/docs/nexio-mock-gateway-integration-guide) and the `paymentOptionTag` of `nexioAuto` to immediately make a transaction settle. 
4. Include the payment `id` in the body of your request for this endpoint, along with an `amount` that is less than or equal to the original transaction amount. Note that some gateway connections allow multiple refunds per transaction. In this situation, you should ensure that the total of all refunds does not exceed the amount charged in the original transaction.

If you do not know the `paymentId` or the maximum `amount` to refund, you can get an array of possible transactions that have settled with the [View transactions](https://docs.nexiopay.com/reference/viewtransactions) endpoint and at least the following query filters:<br/>`transactionStatus=20`<br/>`plugin=`

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you can use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).<br/><br/>You can also use the following test account. Copy the value and paste it into the appropriate space in the Try It section to the right.
> username: `docs@nexiopay.com`
> password: `JZdzoXpdDeH6VA`<br/><br/>Include the ID and a refund amount, as indicated above. You may also include a description of why you are issuing the refund.

<div style="display:none;">

## Request parameters
- id
- data
- data.amount
- refundReason

## Response parameters
- id
- merchantId
- transactionDate
- authCode
- transactionStatus
- transactionType
- currency
- amount
- message
- data
- data.currency
- data.settlementCurrency
- data.amount
- gatewayResponse
- gatewayResponse.gatewayName
- gatewayResponse.refNumber
- recurringData
- recurringData.recurringId
- recurringData.recurringIdType

</div>

## Request body

- object — Transaction data
  - `id` string, required — The Nexio Payment ID. To refund a transaction through this endpoint it must have been captured through the Nexio Payment API. The transaction must also have already settled.
  - `data` object, required
    - `amount` number, required — The amount of the transaction you want to refund, in the transaction currency. This value may be less than or equal to the original transaction `amount`, but it may not exceed it. This also means that if you make more than one refund to a single transaction where each is less than the original `amount`, you need to ensure that the total of all refunds does not exceed the original `amount`. The system returns a `435` error code if the refund amount exceeds the original `amount`.
  - `refundReason` string — Specifies information about why the refund is being issued. The gateway or connection may not use or return this value.

## Response `200`

Success

- object
  - `id` Id — unresolved $ref
  - `merchantId` MerchantId — unresolved $ref
  - `authCode` AuthCode — unresolved $ref
  - `transactionType` string — The [transaction type](https://docs.nexiopay.com/docs/constant-transaction-values#transaction-type-transactiontype). If the refund was successful, this value will be `refund`.
  - `transactionDate` TransactionDate — unresolved $ref
  - `transactionStatus` string — The [transaction status](https://docs.nexiopay.com/docs/constant-transaction-values#transaction-status-transactionstatus).
  - `message` Message — unresolved $ref
  - `refundReason` string — Indicates the information specified when submitting the refund request. This parameter is only returned when included in the refund request, and only when returned by the gateway or connection.
  - `amount` number — The amount that was refunded, expressed as a negative number.
  - `currency` Currency — unresolved $ref
  - `data` object — Transaction data for the refund.
    - `amount` Amount — unresolved $ref
    - `currency` Currency — unresolved $ref
    - `settlementCurrency` SettlementCurrency — unresolved $ref
  - `gatewayResponse` GatewayResponse — unresolved $ref
  - `recurringData` object — When the original transaction used raw card information and may have recurring or subsequent transactions, the system returns this object.
    - `recurringId` string — The ID that references the previous transaction authorization. Save this value to use in subsequent transactions every time you run a transaction with raw card information.
    - `recurringIdType` string — The type of recurring ID, in relation to the original authorization. Will be either `networkTransactionId` (meaning that a card brand issued the identifier and therefore you can potentially use it across multiple gateways or connections) or `gatewayRecurringId` (meaning that the gateway or connection issued the identifier and you can only use it with that specific gateway or connection).
  - `random-nnnnnnn` RandomNnnn — unresolved $ref

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)