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

Required

PaymentInitiationPaymentReverseRequest defines the request schema for /payment_initiation/payment/reverse

Parameters

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
required, string
The ID of the payment to reverse
idempotency_key
required, string
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
required, string
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
object
The amount and currency of a payment
counterparty_date_of_birth
string
The counterparty’s birthdate, in ISO 8601 (YYYY-MM-DD) format.
counterparty_address
object
The optional address of the payment recipient’s bank account. Required by most institutions outside of the UK.
street
required, array[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.
city
required, string
The city where the recipient is located. Maximum of 35 characters.
postal_code
required, string
The postal code where the recipient is located. Maximum of 16 characters.
country
required, string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Response

PaymentInitiationPaymentReverseResponse defines the response schema for /payment_initation/payment/reverse

Response Properties

refund_id
required, string
A unique ID identifying the refund
status
required, string
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
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.