Reversal: return an accepted debit

Reversal returns the customer's money when a debit cannot be completed. The institution must first find an accepted original debit, confirm that every reference and amount matches, and check that the debit has not already been reversed.

Before you begin

• Implement Secure every request and response.
• Follow Format identifiers and date-times.
• Read Understand common payment fields.
• Read Understand code values.
• Store accepted debits by message, instruction, end-to-end, transaction, and clearing references.
• Store the original amount, currency, parties, settlement date, and reversal state.

Endpoint and headers

Create an HTTPS POST endpoint and provide its complete URL to Blinc. For example:

https://sandbox.examplebank.com/blinc/reversal

Every request must contain Content-Type: application/json, Accept: application/json, x-timestamp, and x-signature. Every response, including a business rejection, must contain Content-Type: application/json, x-timestamp, and x-signature. See Secure every request and response for what each header protects and how to validate it. Decrypt first, then verify the signature against the exact recovered plaintext.

Decrypted request

{
  "GrpHdr": {
    "MsgId": "00000120260817140000000000000000050",
    "CreDtTm": "2026-08-17T14:00:00.000Z",
    "NbOfTxs": 1,
    "SttlmInf": {
      "SttlmMtd": "CLRG",
      "ClrSys": {
        "Prtry": "NIP"
      },
      "ClrChanl": "RTNS"
    }
  },
  "OrgnlGrpInf": {
    "OrgnlMsgId": "00000120260817101530123000000000001",
    "OrgnlMsgNmId": "pacs.003.001.11"
  },
  "TxInf": {
    "OrgnlEndToEndId": "DD-E2E-0001",
    "OrgnlInstdAmt": {
      "Amt": 1500.0,
      "Ccy": "NGN"
    },
    "RvsldIntrBkSttlmAmt": {
      "Amt": 1500.0,
      "Ccy": "NGN"
    },
    "IntrBkSttlmDt": "2026-08-17T14:00:00.000Z",
    "RvslRsnInf": {
      "Orgtr": {
        "Nm": "Blinc"
      },
      "Rsn": {
        "Cd": "TECH"
      },
      "AddtlInf": "Debit Authorization response was not received within the timeout window."
    },
    "OrgnlTxRef": {
      "Dbtr": {
        "Nm": "Ada Okafor",
        "Id": {
          "Othr": {
            "Id": "12345678901",
            "SchmeNm": {
              "Cd": "BVN"
            }
          }
        }
      },
      "Cdtr": {
        "Nm": "Example Store",
        "Id": {
          "Othr": {
            "Id": "CREDITOR-001",
            "SchmeNm": {
              "Cd": "BLINC"
            }
          }
        }
      }
    }
  }
}

Return the money safely

1. Decrypt the body and verify the institutional signature headers.
2. Validate the delivery timestamp, message creation time, message ID, and replay state.
3. Find the original accepted debit using OrgnlMsgId and OrgnlEndToEndId.
4. Confirm the message family identifies Debit Authorization.
5. Compare the original amount, reversal amount, currency, settlement date, debtor, and creditor with the stored debit.
6. Require a full reversal. Partial reversals are not part of this contract.
7. If the same Reversal was already accepted, send the same outcome without returning the money a second time.
8. If the identifiers were reused with different content, reject the request.
9. Return the customer's money exactly once, record the outcome, then sign and encrypt the response.

Request field reference

Response

Return the common signed and encrypted payment response. Use a new 35-digit response GrpHdr.MsgId, copy the request ID into GrpHdr.OrgnlMsgId, and copy the original debit references into TxInfAndSts.

{
  "GrpHdr": {
    "MsgId": "00000120260816103001000000000000103",
    "CreDtTm": "2026-08-16T10:30:01.000Z",
    "OrgnlMsgId": "12345620260816103000000000000000004",
    "OrgnlMsgNmId": "pacs.007.001.09"
  },
  "TxInfAndSts": {
    "OrgnlInstrId": "DD-INSTR-0001",
    "OrgnlEndToEndId": "DD-E2E-0001",
    "OrgnlTxId": "DD-TX-0001",
    "TxSts": "ACSC",
    "StsRsnInf": null,
    "SplmtryData": {
      "PlcAndNm": "AdditionalDetails",
      "Envlp": { "CustomParam": { "ReversalReference": "REV-POST-0001" } }
    }
  }
}

ACSC means the reversal was accepted and recorded. RJCT means it was rejected. On rejection, populate StsRsnInf.Orgtr.Nm, StsRsnInf.Rsn.Cd, and StsRsnInf.AddtlInf with the decision owner, stable reason code, and corrective explanation. Every Orgnl... response field must identify the request or original debit it names; never generate replacement original IDs.

Common mistakes

Test before certification

• An accepted original debit reverses once and returns ACSC.
• The same Reversal request delivered again returns the earlier outcome without returning the money a second time.
• Unknown, rejected, cancelled, or already reversed debit returns RJCT.
• Mismatched amount, currency, parties, message family, or identifiers returns RJCT.
• A partial amount returns RJCT.
• Invalid encryption, signature, timestamp, or replay state fails before any ledger change.

Next

If the institution is a payment facilitator receiving successful-credit notifications, continue with Notify the payment facilitator about a successful credit. If you are an acquiring institution that sends money to beneficiaries, continue with Send money to a beneficiary. Otherwise, go to Return clear errors and handle repeated deliveries.