Reverse Transaction

Request URL

POST /transfer-to/bills/reversal

Description

Bill payment reversal requests are an option that is available by additional agreement only. The Sponsor Bank requires reversal requests to be within 5 business days of the original transaction. In addition, the following criteria must be met:

The original bill payment to be reversed, indicated by the cFiTransactionId field, must currently be in a "Settled" status.
The original bill payment to be reversed must not be a reversal itself.
The combined amounts of any reversals for a particular bill payment must not exceed the amount of the original parent transaction.
A new, unique reference must be provided for the reversal transaction.
Note: After initiating a bill payment reversal request, the request will automatically be executed. You do not need to request execution of the reversal request through the /transfer-to/bills/execute endpoint.
Note: Please be aware that some billers do not accept or support reversal requests. Similar to a bill payment transaction request, billers may decline a reversal request.

If an amount is not specified in the bill payment reversal request, then the original bill payment amount will be used by default. The original billerId, accountNumber or accountNumberEncrypted, legalName (if applicable), firstName and lastName (if applicable), deliveryTimeCode, and currency will also be included by default. If specified in the reversal request, the description field will be used to populate the "narrative" property of the reversal. A webhookUrl may also be included in order to receive status updates for the reversal transaction.

Schema

Property table for transfer-to/bills/reversal

Property	Description	Required	Schema
cFiTransactionId	The transaction ID in the connectFi system	Yes	{ "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "$id": "common-id" }
reference	An external alphanumeric reference ID for the entity in your system	No	{ "type": "string", "pattern": "^[0-9a-zA-Z]+$", "minLength": 1, "maxLength": 32, "$id": "common-reference" }
amount	Amount	No	{ "type": "number", "exclusiveMinimum": 0, "amountPrecision": 2, "$id": "common-amount" }
webhookUrl	If you specify a webhookUrl in this request, the system will perform a callback to your webhookUrl to notify you of specified asynchronous status changes.	No	{ "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 500, "nullable": true, "$id": "common-commonStr500" }
description	Description	No	{ "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 500, "nullable": true, "$id": "common-commonStr500" }

Request Body

{
    "cFiTransactionId": "CLIENTID_MR6Cn31Gw3ESrlib",
    "reference": "UNIQUEREVERSALID",
    "amount": 1.08, 
    "webhookUrl": "https://your_webhook_url/UNIQUE_REVERSAL_ID",
    "description": "Reversal request"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "cFiTransactionId": "CLIENTID_MR6Cn31Gw3ESrlib",
    "reference": "UNIQUEREVERSALID",
    "amount": 1.08, 
    "webhookUrl": "https://your_webhook_url/UNIQUE_REVERSAL_ID",
    "description": "Reversal request"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/transfer-to/bills/reversal',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-token': "A long random string token received from /auth/get-token request"
  },
  data
};

let result;
try {
  result = await axios.request(config);
  if (result.status === 200) {
    console.log(JSON.stringify(result.data));
  }
} catch (err) {
  console.log({
    errCode: err.code,
    responseStatus: err.response && err.response.status,
    data: err.response && JSON.stringify(err.response.data)
  });
}

cURL

curl --location "CONNECTFI_BASE_URL/transfer-to/bills/reversal" --data "{\"cFiTransactionId\":\"CLIENTID_MR6Cn31Gw3ESrlib\",   \"reference\":\"UNIQUEREVERSALID\",   \"amount\":1.08,    \"webhookUrl\":\"https://your_webhook_url/UNIQUE_REVERSAL_ID\",   \"description\":\"Reversal request\"}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"

Successful Response Examples

200 SUCCESSFUL RESPONSE

HEADERS

Header	Value
Content-Type	application/json
x-connectfi-token	A long random string token received from /auth/get-token request

REQUEST BODY

{
    "cFiTransactionId": "CLIENTID_MR6Cn31Gw3ESrlib",
    "reference": "UNIQUEREVERSALID",
    "amount": 1.08, 
    "webhookUrl": "https://your_webhook_url/UNIQUE_REVERSAL_ID",
    "description": "Reversal request"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAggregatorId": "CLIENTID",
        "reference": "UNIQUEREVERSALID",
        "cFiTransactionId": "CLIENTID_7gqtr3xhsfL9Q1thLR1uPo",
        "cFiParentId": "CLIENTID_MR6Cn31Gw3ESrlib",
        "merchantId": "10000001",
        "cFiTraceNumber": "000000000020581",
        "status": "Processing",
        "amount": 1.08,
        "currency": "USD",
        "dtsCreated": "2024-10-24T13:29:01.886Z",
        "billerId": "9000005588",
        "batchId": "2i31SNWiKJHEcpPyEXwjS2",
        "statusChangeHistory": [
            {
                "login": "CLIENTID",
                "initiatorId": "6sOqx76nrAjAXfCUusDlZM",
                "initiatorType": "user",
                "status": "Initiated",
                "dtsCreatedAt": "2024-10-24T13:29:01.886Z",
                "dtsUpdatedAt": "2024-10-24T13:29:01.886Z"
            },
            {
                "login": "CLIENTID",
                "initiatorId": "6sOqx76nrAjAXfCUusDlZM",
                "initiatorType": "user",
                "status": "Processing",
                "dtsCreatedAt": "2024-10-24T13:29:01.916Z",
                "dtsUpdatedAt": "2024-10-24T13:29:01.916Z"
            }
        ],
        "firstName": "Joe",
        "lastName": "Doe",
        "accountNumber": "5218760036248552",
        "billerName": "CitiBusiness",
        "isReversal": true
    },
    "requestId": "eeadd540920b11ef93c409b8ecd80f12"
}