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.

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,
  "description": "common-commonStr50Req"
}
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,
  "description": "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,
  "description": "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,
  "description": "common-amount"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "description": "common-currency"
}
webhookUrl webhookUrl No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "description": "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,
  "description": "common-reference"
}
isReversal Set as true if this transaction should be a reversal (or return) of a previous transaction. Make sure that the reversal amount does 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. 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,
  "description": "common-commonStr50Req"
}
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,
  "description": "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,
  "description": "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,
  "description": "common-amount"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "description": "common-currency"
}
webhookUrl webhookUrl No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "description": "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,
  "description": "common-reference"
}
isReversal Set as true if this transaction should be a reversal (or return) of a previous transaction. Make sure that the reversal amount does 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. 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"
}