Skip to content

Webhooks

If you specify a webhook URL in the /transfer-to/bills/initiate endpoint, every time a transaction status changes due to a response connectFi has received, the system will make a single POST call to the specified URL with the following body. A webhook is not called when a transaction changes from "Initiated" to "Processing" status. When a webhook is received, your webhook server is expected to return a 200 status response (no response body is required in the response).

Example Webhook for "Sent" Status Change 

{
  "reference": "extTrnBill218", //external transaction ID in your system
  "cFiTransactionId": "CLIENTID_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
  "merchantId": "10000001",
  "cFiTraceNumber": "000000000000008",
  "status": "Sent", //current status of the transaction
  "amount": 10.93,
  "currency": "USD", //currency code
  "dtsCreated": "2023-05-12T14:27:33.684Z", //date created 
  "billerId": "9000005588"

}

Example Webhook for "Complete" Status Change 

{
  "reference": "extTrnBill218", //external transaction ID in your system
  "cFiTransactionId": "CLIENTID_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
  "merchantId": "10000001",
  "cFiTraceNumber": "000000000000008",
  "status": "Complete", //current status of the transaction
  "amount": 10.93,
  "currency": "USD", //currency code
  "dtsCreated": "2023-05-12T14:27:33.684Z", //date created 
  "billerId": "9000005588",
  "dtsSent": "2024-06-05T15:09:54.304Z",
  "processing": {
    "dateProcessed": "2024-03-05",
    "isReversal": false,
    "remarks": "",
    "responseCode": "",
    "status": "Completed",
    "traceId": "183491000078" //Trace number received from processor in acknowledgement of transaction details receipt. 
  }
}

Example Webhook for "Settled" Status Change 

{
  "reference": "extTrnBill218", //external transaction ID in your system
  "cFiTransactionId": "CLIENTID_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
  "merchantId": "10000001",
  "cFiTraceNumber": "000000000000008",
  "status": "Settled", //current status of the transaction
  "amount": 10.93,
  "currency": "USD", //currency code
  "dtsCreated": "2023-05-12T14:27:33.684Z", //date created 
  "billerId": "9000005588",
  "dtsSent": "2024-06-05T15:09:54.304Z",
  "processing": {
    "dateProcessed": "2024-03-05",
    "isReversal": false,
    "remarks": "",
    "responseCode": "",
    "status": "Completed",
    "traceId": "183491000078" //Trace number received from processor in acknowledgement of transaction details receipt. 
  },
  "dateSettled": "2024-06-05",
  "settled": {
    "networkFee": -0.12,
    "settledAmount": -10.93,
    "settlementDate": "2024-03-05",
    "status": "Complete"
  }
}

Example Webhook for "Declined" Status Change 

{
  "reference": "extTrnBill218", //external transaction ID in your system
  "cFiTransactionId": "CLIENTID_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
  "merchantId": "10000001",
  "cFiTraceNumber": "000000000000008",
  "status": "Declined", //current status of the transaction
  "amount": 10.93,
  "currency": "USD", //currency code
  "dtsCreated": "2023-05-12T14:27:33.684Z", //date created 
  "billerId": "9000005588",
  "dtsSent": "2024-06-05T15:09:54.304Z",
  "processing": {
    "dateProcessed": "2024-03-05",
    "isReversal": false,
    "remarks": "", //if processing.status is "Failed", remarks contains a description of the reason for failure
    "responseCode": "", //if processing.status is "Failed", responseCode indicating reason for failure is present here
    "status": "Completed", //or "Failed"
    "traceId": "183491000078" //Trace number received from processor in acknowledgement of transaction details receipt. 
  },
  "dateSettled": "2024-06-05", //dateSettled or may not be present, depending on when the transaction was Declined.
  "settled": { //settled object may or may not be present, depending on when the transaction was Declined
    "networkFee": -0.12,
    "settledAmount": -10.93,
    "settlementDate": "2024-03-05",
    "status": "Complete"
  },
  "dateException": "2024-06-22", //dateException may or may not be present, depending on when the transaction was Declined.
  "exception": { //exception object may or may not be present, depending on when the transaction was Declined. An exception is possible, even after funds have settled and may indicate that the funds were returned. See "exceptionCode" and "exceptionDescription" for details about the exception.
    "fileName": "1234_1234_20240622_exceptions_v2-5.csv",
    "exceptionAmount": 10.93,
    "exceptionCurrency": "USD",
    "networkFee": 0,
    "exceptionCode": "R02",
    "exceptionDescription": "Customer account closed-Merchant paid",
    "exceptionDate": "2024-06-22",
  }
}

Example Webhook for "Cancelled" Status Change 

{
  "reference": "extTrnBill218", //external transaction ID in your system
  "cFiTransactionId": "CLIENTID_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
  "merchantId": "10000001",
  "cFiTraceNumber": "000000000000008",
  "status": "Cancelled", //A "Cancelled" status indicates that you (the client) cancelled the transaction after initiation but before the transaction was "Sent"
  "amount": 10.93,
  "currency": "USD", //currency code
  "dtsCreated": "2023-05-12T14:27:33.684Z", //date created 
  "billerId": "9000005588"
}