​
Overview

A return occurs when a completed payment is sent back by the receiving institution. This is not something you initiate — it happens externally. Common reasons include incorrect account details, closed accounts, or insufficient funds at the receiving bank.

​
ACH Return Codes

CodeReasonDescription
R01Insufficient fundsReceiving account had insufficient funds
R02Account closedReceiving account has been closed
R03No account / unable to locateAccount number does not match
R04Invalid account numberAccount number structure is invalid
R08Payment stoppedReceiver placed a stop payment
R10Customer advises not authorizedReceiver claims the payment was not authorized
R16Account frozenReceiving account is frozen
R29Corporate customer advises not authorizedCorporate receiver did not authorize

​
SWIFT Return Reasons

ReasonDescription
AC04Account closed
AC06Account blocked
AM05Duplicate payment
BE04Missing creditor address
RC01Incorrect BIC
FOCRFollowing cancellation request

​
Return Flow

When a payment is returned:
  1. The payment status transitions from completed to returned.
  2. A payment.returned webhook fires with the return reason.
  3. The returned funds are credited back to the source account.
  4. You must decide how to handle the return by submitting a return action.

​
Handling Return Actions

When a payment is returned, you have three options:
ActionDescriptionWhen to use
acceptAccept the return. The returned funds remain in your account. No further action.The return is legitimate (e.g., wrong account, closed account).
contestDispute the return with the receiving institution.You believe the return is incorrect (e.g., R10 claim that you have authorization for).
repairCorrect the payment details and resubmit. Creates a new payment with corrected information.The return was due to incorrect details (e.g., wrong account number, missing info).

​
Code Example: Handle a Return

curl -X POST https://sandbox.api.openfx.com/v1/payments/pmt_01953e1a5f4b7005/actions/return-action \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "accept",
    "reason": "Counterparty confirmed the account is closed. Will send to their new account."
  }'

​
Contesting a Return

{
  "action": "contest",
  "reason": "We have signed authorization from the account holder. ACH mandate reference: MAND-2026-0042."
}

​
Repairing a Return

When you repair a return, you provide corrected payment details. The API creates a new payment with the corrected information: 
{
  "action": "repair",
  "reason": "Account number was incorrect. Updated payment method with correct details.",
  "correctedPaymentMethodId": "pm_01953e1a5f4b7301"
}

1. Receive payment.returned webhook
   |
2. Retrieve payment to get return details
   |  GET /payments/{id}
   |
3. Evaluate the return reason
   |
4. Decide on action:
   +-- Legitimate return -> accept
   +-- Incorrect return -> contest
   +-- Fixable error -> repair (after updating payment method)
   |
5. Submit return action
   |  POST /payments/{id}/actions/return-action
   |
6. If repair -> monitor the new payment lifecycle

​
Return vs. Reversal

ScenarioWho initiatesWhenPayment statusFunds
ReturnReceiving institutionAfter deliveryreturnedReturned to source account
ReversalOpenFX or networkAfter delivery (fraud, error)reversedReversed to source account
Reversals are initiated by the platform or network, not by you. They are typically related to fraud detection or operational errors. You do not need to take action on a reversal — the funds are automatically credited back.

​
API Reference