Reverse a payment

This request is used to reverse a payment that has already been processed.

The required fields and their behavior depend on the type of payment being reversed (such as ACH, Fedwire, FedNow, RTP).

Important business rules:

  • Only outgoing (OUT) credit payments can be reversed.
  • The payment must be in PROCESSED status.
  • Debit payments are not eligible for reversal in FedNow, Fedwire, and RTP payment types.
  • For FedNow and RTP payments, the request will be rejected when returnStatus == "RETURN_REQUEST_SENT".
  • Reversal is not supported for SWIFT payment types.
SecurityoAuth2
Request
path Parameters
paymentUID
required
string

Payment Unique Identifier.

Request Body schema: application/json
reversalNotes
string

A brief explanation for why the payment is being reversed.

How this field is used:

  • ACH payments: This field is not used and will be ignored.

  • Fedwire, FedNow and RTP payments: This field is optional. If not provided, the system will automatically use "Customer Initiated" as the reason.

reversalCode
string

A standardized reason code that explains why the payment is being reversed.

When this field is required:

  • Required for Fedwire, FedNow, and RTP payments.
  • Not used for ACH.

The value must be one of the following codes:

  • AC03 : Invalid account number
  • AGNT : Requested by bank/agent
  • AM09 : Incorrect amount
  • CUST : Requested by customer
  • CUTA : Unable to apply funds
  • DUPL : Duplicate payment
  • FRAD : Suspected fraud
  • NARR : General explanation
  • TECH : Technical issue
  • UPAY : Overpayment

If an invalid code is provided, the request will be rejected.

Enum: "AC03" "AGNT" "AM09" "CUST" "CUTA" "DUPL" "FRAD" "NARR" "TECH" "UPAY"
initiatingParty
string

The name of the system initiating the reversal request.

This field applies only to FedNow payments:

  • If not provided, the system will automatically set it to "API".

For all other payment types (ACH, Fedwire, RTP), this field is ignored.

Responses
200

OK

400

Bad request

401

You are not authorized to access the resource

403

Accessing the resource you were trying to reach is forbidden

404

The resource you were trying to reach is not found

500

Internal server error

503

Service unavailable

default

Successful

put/v3/payments/{paymentUID}/reverse
Request samples
application/json
{
  • "reversalNotes": "Duplicate payment - please recall funds",
  • "reversalCode": "CUST",
  • "initiatingParty": "API Customer"
}
Response samples
application/json
[
  • {
    }
]