---
title: "Reverse an existing payment"
method: POST
path: "/payment_initiation/payment/reverse"
tags: ["plaid"]
---

# Reverse an existing payment

`POST /payment_initiation/payment/reverse`

Reverse a settled payment from a Plaid virtual account.

The original payment must be in a settled state to be refunded.
To refund partially, specify the amount as part of the request.
If the amount is not specified, the refund amount will be equal to all
of the remaining payment amount that has not been refunded yet.

The refund will go back to the source account that initiated the payment.
The original payment must have been initiated to a Plaid virtual account
so that this account can be used to initiate the refund.

Providing counterparty information such as date of birth and address increases
the likelihood of refund being successful without human intervention.

## Request body

- PaymentInitiationPaymentReverseRequest — PaymentInitiationPaymentReverseRequest defines the request schema for `/payment_initiation/payment/reverse`
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
  - `payment_id` string, required — The ID of the payment to reverse
  - `idempotency_key` string, required — A random key provided by the client, per unique wallet transaction. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.
  - `reference` string, required — A reference for the refund. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces.
  - `amount` PaymentAmountToRefund, nullable — An amount to refund the payment partially. If this amount is not specified, the payment is refunded fully for the remaining amount.
    - `currency` 'GBP' | 'EUR' | 'PLN' | 'SEK' | 'DKK' | 'NOK', required — The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.
    - `value` number, double, required — The amount of the payment. Must contain at most two digits of precision e.g. `1.23`.
  - `counterparty_date_of_birth` string, date, nullable — The counterparty's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format.
  - `counterparty_address` PaymentInitiationAddress, nullable — The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    - `street` string[], required — An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.
    - `city` string, required — The city where the recipient is located. Maximum of 35 characters.
    - `postal_code` string, required — The postal code where the recipient is located. Maximum of 16 characters.
    - `country` string, required — The ISO 3166-1 alpha-2 country code where the recipient is located.

## Response `200`

OK

- PaymentInitiationPaymentReverseResponse — PaymentInitiationPaymentReverseResponse defines the response schema for `/payment_initiation/payment/reverse`
  - `refund_id` string, required — A unique ID identifying the refund
  - `status` 'AUTHORISING' | 'INITIATED' | 'EXECUTED' | 'SETTLED' | 'BLOCKED' | 'FAILED', required — The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status.
  - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

## Other responses

- `default` — Error response

---

[API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/64c4514ea59b/schema)