Skip to content

Initiate Transaction

Request URL

POST /transfer-to/bills/initiate

Description

Making a payment is a 3-step process. You need to:

  1. Initiate a transaction using /transfer-to/bills/initiate.
  2. Store the returned cFiTransactionId locally.
  3. Then request execution of the transaction using /transfer-to/bills/execute.

This endpoint creates a new transaction with "Initiated" status. It will not get executed until you request execution see Executing a Transaction.

For reversals, the reversal amount must not exceed the original transaction amount that you wish to reverse. Note: Bill payment reversals are an option that is available by additional agreement only.

The /transfer-to/bills/initiate endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transactions. It is important to note that transactions submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values (unless the specified biller has an internal policy to reject multiple payments in the same billing cycle). For example, the following transactions are not considered duplicates.

{
    "billerId": "0123456789",
    "accountNumber": "0123456789",
    "legalName" : "Acme Inc",
    "firstName" : "Joe",
    "lastName" : "Doe",
    "amount": 100.01,
    "currency": "USD",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/EXT_REFERENCE_ID1",
    "reference": "EXT_REFERENCE_ID1", //Different reference IDs
    "narrative": "Both of these transactions will post"
}
{
    "billerId": "0123456789",
    "accountNumber": "0123456789",
    "legalName" : "Acme Inc",
    "firstName" : "Joe",
    "lastName" : "Doe",
    "amount": 100.01,
    "currency": "USD",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/EXT_REFERENCE_ID1",
    "reference": "EXT_REFERENCE_ID2", //Different reference IDs
    "narrative": "Both of these transactions will post"
}

Schema

Property table for schema 1 for transfer-to/bills/initiate

Property Description Required Schema
billerId The biller ID in connectFi Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
batchId The batch ID No {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "$id": "common-reference"
}
accountNumber The account number No {
  "type": "string",
  "minLength": 1,
  "maxLength": 50
}
accountNumberEncrypted The customer's account number in the biller's system that has been encrypted (Note: Use either accountNumber, for non-sensitive account numbers, or accountNumberEncrypted, for sensitive account numbers. You may not use both accountNumber and accountNumberEncrypted in the same transaction.) No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 500,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr500Req"
}
legalName The legal name of the payer. (Note: If the payer is a business, the "legalName" property is required instead of the "firstName" and "lastName" properties) Yes {
  "type": "string",
  "maxLength": 22,
  "minLength": 1
}
narrative A brief description No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "$id": "common-commonStr500"
}
deliveryTimeCode A delivery time code, acceptable values are "S" (for Same day) or "N" (for Next day). Requests received after 9:30AM ET will be processed as Next day, even if marked "S" Yes {
  "type": "string",
  "enum": [ "I", "S", "N" ]
}
amount Amount Yes {
  "type": "number",
  "exclusiveMinimum": 0,
  "amountPrecision": 2,
  "$id": "common-amount"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "$id": "common-currency"
}
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"
}
reference An external alphanumeric reference ID for the entity in your system Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "$id": "common-reference"
}
isReversal Indicates if this transaction is a reversal (or return) of a previous transaction. No {
  "type": "boolean"
}

Property table for schema 2 for transfer-to/bills/initiate

Property Description Required Schema
billerId The biller ID in connectFi Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
batchId The batch ID No {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "$id": "common-reference"
}
accountNumber The account number No {
  "type": "string",
  "minLength": 1,
  "maxLength": 50
}
accountNumberEncrypted The customer's account number in the biller's system that has been encrypted (Note: Use either accountNumber, for non-sensitive account numbers, or accountNumberEncrypted, for sensitive account numbers. You may not use both accountNumber and accountNumberEncrypted in the same transaction.) No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 500,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr500Req"
}
firstName First (given) name Yes {
  "type": "string",
  "maxLength": 22,
  "minLength": 1
}
lastName Last (family) name Yes {
  "type": "string",
  "maxLength": 22,
  "minLength": 1
}
narrative A brief description No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "$id": "common-commonStr500"
}
deliveryTimeCode A delivery time code, acceptable values are "S" (for Same day) or "N" (for Next day). Requests received after 9:30AM ET will be processed as Next day, even if marked "S" Yes {
  "type": "string",
  "enum": [ "I", "S", "N" ]
}
amount Amount Yes {
  "type": "number",
  "exclusiveMinimum": 0,
  "amountPrecision": 2,
  "$id": "common-amount"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "$id": "common-currency"
}
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"
}
reference An external alphanumeric reference ID for the entity in your system Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "$id": "common-reference"
}
isReversal Indicates if this transaction is a reversal (or return) of a previous transaction. No {
  "type": "boolean"
}

Request Body

{
    "amount": 7.15,
    "currency": "USD",
    "reference": "UNIQUE_REFERENCE_ID",
    "billerId": "9000005588",
    "accountNumberEncrypted": "cM+tJN2eJ8mjMRbBVruQ4Y6lAm8wfJ8q9p+JMnsbBfouNfNXGZXDAtSwKQCP0tF/xS1bH1OxW74adeMHebZ/s+wy4icqF/vt5ncPdw/ZYUNuQpqBIWDQGnFrWje19sNpwPup65BXMQ2MVYR8YURdQ7luukrU1hFIcNZ02iLNmeWScOloPXqnInspTmKaArk+G8WiK7iiAmCjJzyHlIJxLVbj+5cg/d5DLjItPp34LsmBtSCwHEtdlpN0bC78JQy96AkpEWnacnFG7Da+9e5ZBRMRbvrldkJHtM8uqErxV/1ZB1rPy91yq4jhknyyrpauZFCZSlsnFfaXtiexO0I7kg==",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/UNIQUE_REFERENCE_ID",
    "narrative": "Your message here"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "amount": 7.15,
    "currency": "USD",
    "reference": "UNIQUE_REFERENCE_ID",
    "billerId": "9000005588",
    "accountNumberEncrypted": "cM+tJN2eJ8mjMRbBVruQ4Y6lAm8wfJ8q9p+JMnsbBfouNfNXGZXDAtSwKQCP0tF/xS1bH1OxW74adeMHebZ/s+wy4icqF/vt5ncPdw/ZYUNuQpqBIWDQGnFrWje19sNpwPup65BXMQ2MVYR8YURdQ7luukrU1hFIcNZ02iLNmeWScOloPXqnInspTmKaArk+G8WiK7iiAmCjJzyHlIJxLVbj+5cg/d5DLjItPp34LsmBtSCwHEtdlpN0bC78JQy96AkpEWnacnFG7Da+9e5ZBRMRbvrldkJHtM8uqErxV/1ZB1rPy91yq4jhknyyrpauZFCZSlsnFfaXtiexO0I7kg==",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/UNIQUE_REFERENCE_ID",
    "narrative": "Your message here"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/transfer-to/bills/initiate',
  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/initiate" --data "{\"amount\":7.15,\"currency\":\"USD\",\"reference\":\"UNIQUE_REFERENCE_ID\",\"billerId\":\"9000005588\",\"accountNumberEncrypted\":\"cM+tJN2eJ8mjMRbBVruQ4Y6lAm8wfJ8q9p+JMnsbBfouNfNXGZXDAtSwKQCP0tF/xS1bH1OxW74adeMHebZ/s+wy4icqF/vt5ncPdw/ZYUNuQpqBIWDQGnFrWje19sNpwPup65BXMQ2MVYR8YURdQ7luukrU1hFIcNZ02iLNmeWScOloPXqnInspTmKaArk+G8WiK7iiAmCjJzyHlIJxLVbj+5cg/d5DLjItPp34LsmBtSCwHEtdlpN0bC78JQy96AkpEWnacnFG7Da+9e5ZBRMRbvrldkJHtM8uqErxV/1ZB1rPy91yq4jhknyyrpauZFCZSlsnFfaXtiexO0I7kg==\",\"firstName\":\"Joe\",\"lastName\":\"Doe\",   \"deliveryTimeCode\": \"N\",   \"webhookUrl\":\"https://your_webhook_url/UNIQUE_REFERENCE_ID\",   \"narrative\":\"Your message here\"}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"

Successful Response Examples

200 TRANSFER-TO/BILLS/INITIATE ACCOUNTNUMBERENCRYPTED ENCRYPTED 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

{
    "amount": 7.15,
    "currency": "USD",
    "reference": "extTrnBill300",
    "billerId": "9000005588",
    "accountNumberEncrypted": "cM+tJN2eJ8mjMRbBVruQ4Y6lAm8wfJ8q9p+JMnsbBfouNfNXGZXDAtSwKQCP0tF/xS1bH1OxW74adeMHebZ/s+wy4icqF/vt5ncPdw/ZYUNuQpqBIWDQGnFrWje19sNpwPup65BXMQ2MVYR8YURdQ7luukrU1hFIcNZ02iLNmeWScOloPXqnInspTmKaArk+G8WiK7iiAmCjJzyHlIJxLVbj+5cg/d5DLjItPp34LsmBtSCwHEtdlpN0bC78JQy96AkpEWnacnFG7Da+9e5ZBRMRbvrldkJHtM8uqErxV/1ZB1rPy91yq4jhknyyrpauZFCZSlsnFfaXtiexO0I7kg==",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/extTrnBill300",
    "narrative": "Your message here"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "extTrnBill300",
        "cFiTransactionId": "CLIENTID_7aPxTlvNmzwPZKZEQSXGIW",
        "merchantId": "10000001",
        "cFiTraceNumber": "000000000006985",
        "status": "Initiated",
        "amount": 7.15,
        "currency": "USD",
        "dtsCreated": "2023-11-02T11:42:37.329Z"
    },
    "requestId": "ebb6b150797411eeb5658f28ab5fe311"
}

200 TRANSFER-TO/BILLS/INITIATE ACCOUNTNUMBER UNENCRYPTED 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

{
    "amount": 1.01,
    "currency": "USD",
    "reference": "extTrnBill400",
    "billerId": "0003000666",
    "accountNumber": "123456789",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/extTrnBill400",
    "narrative": "Your message here"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "extTrnBill400",
        "cFiTransactionId": "CLIENTID_1ziBaW6k8W1ZNXNAmFDovo",
        "merchantId": "10000001",
        "cFiTraceNumber": "000000000006989",
        "status": "Initiated",
        "amount": 1.01,
        "currency": "USD",
        "dtsCreated": "2023-11-02T11:44:37.831Z"
    },
    "requestId": "338df560797511eeb5658f28ab5fe311"
}

200 TRANSFER-TO/BILLS/INITIATE ACCOUNTNUMBER UNENCRYPTED SUCCESSFUL RESPONSE REVERSAL

HEADERS

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

REQUEST BODY

{
    "amount": 1.01,
    "currency": "USD",
    "reference": "extTrnBill400",
    "billerId": "0003000666",
    "accountNumber": "123456789",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/extTrnBill400",
    "narrative": "Your message here",
    "isReversal": true
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "extTrnBill400",
        "cFiTransactionId": "CLIENTID_1ziBaW6k8W1ZNXNAmFDovo",
        "status": "Initiated",
        "amount": 1.01,
        "currency": "USD",
        "dtsCreated": "2023-11-02T11:44:37.831Z"
    },
    "requestId": "338df560797511eeb5658f28ab5fe311"
}