Bill Payment
This service offers bill payments via MasterCard Remote Payment and Presentment Service (RPPS).
| Endpoint or Section | Action |
|---|---|
| Overview | A brief description of the RPPS bill pay service |
| /transfer-to/bills/billers/download | Download a list of MasterCard RPPS billers |
| Encrypting Account Data | Details on encryption of account numbers |
| Public Encryption Keys | Public encryption keys necessary for account number encryption when using RPPS for card payments |
| /transfer-to/bills/initiate | Initiate a bill payment transaction |
| /transfer-to/bills/execute | Execute a bill payment transaction |
| /transfer-to/bills/query | Query details of one or more bill payment transactions |
| /transfer-to/bills/list | List transactions by search criteria |
| /transfer-to/bills/summary | Summarize RPPS settlement data for a specified date |
| Webhooks | Information about optional webhookUrls |
| Possible Status Values | Explanation of possible status values for the bill payment transaction |
Overview
The MasterCard Remote Payment and Presentment Service (RPPS), governed by MasterCard International, is a fully electronic solution for bill payment processing that provides electronic routing, posting, and next-day settlement of financial transactions.
Bill payment requests received and executed by 5:30 pm ET will be sent to processing the same day and settled the next day.
Billers can return any payment sent through the RPPS network. Each returned payment includes a return code that provides the reason the payment is being returned. Payments may be returned if the Biller is unable to post the payment, as may occur if an invalid account number or closed account number is used. MasterCard RPPS also allows partial returns. These may be used for various reasons, such as discounts, commissions, rebates, or fees.
List of Billers
Request method and URL:
GET /transfer-to/bills/billers/download
Description:
Requests to this endpoint return a large JSON file with all of the billers available for Mastercard RPPS. It is recommended that this file be downloaded no more than once per day.
Request headers:
{
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body: None
Possible responses:
200 (HTTP response status code) -- Success, a list of billers and associated data is returned
{
[ //Very large list of billers in JSON format
{
"recordType": "0",
"billerKey": "458909",
"record_effective_date": "2022-08-25",
"biller_id": "0011460198",
"live_date": "2022-05-31",
"routing_number": "",
"biller_name": "Clear Lake CWAHC WCID 161",
"biller_class": "Electric / Gas / Power / Water",
"biller_type": "Core",
"line_of_business": "RB",
"file_format": "",
"accepts_prenotes": "N",
"accepts_guaranteed_payments_only": "Y",
"accepts_DMP_prenotes": "",
"accepts_DMP_payments_only": "",
"average_response_time": "",
"accept_CDP_prenotes": "",
"accept_CDV_prenotes": "",
"accept_CDD_prenotes": "",
"accept_CDF_prenotes": "",
"accept_CDN_prenotes": "",
"accept_FBD_prenotes": "",
"accept_FBC_prenotes": "",
"return_CDR": "",
"return_CDT": "",
"return_CDA": "",
"return_CDV": "",
"return_CDC": "",
"return_CDM": "",
"require_addenda_with_reversals": "N",
"country_code": "USA",
"state_code": "TX",
"check_digit_routine": "N",
"currency_code": "840",
"territory_code": "Regional",
"previous_biller_name": "",
"note": "",
"accepts_exception_payments": "N",
"total_addresses": "1",
"total_masks": "8",
"total_AKAs": "8",
"total_contacts": "5",
"addresses": [ //Array of biller address objects (example below)
],
"masks": [ //Array of mask objects (examples and explanation below)
],
"akas": [ //Array of aka objects, names (A.K.A) that the biller may use (example below)
],
"contacts": [ //Array of biller contact objects (example below)
],
"phones": [ //Array of biller phone objects (example below)
]
},
// List of billers continued....
]
}
Biller address object
{
"recordType": "1",
"address_key": "182059",
"record_effective_date": "2022-05-31",
"address_type": "Standard",
"address_line1": "900 Bay Area Blvd",
"address_line2": "",
"city": "Houston",
"state": "TX",
"country_code": "USA",
"postal_code": "77058-2604"
}
Biller mask object example
Some records may contain input masks for customer's account in biller's system. In this example, account numbers a biller can accept are 15 characters long, will start with 960315,and be followed by 9 Numeric digits.
*=Alpha, #=Numeric, @=Alpha or Numeric, !=Special Character
{
"recordType": "2",
"mask_key": "851880",
"record_effective_date": "2022-08-01",
"mask_length": "15",
"mask": "960315#########",
"exception_mask": "N"
}
Masks explained
*=Alpha, #=Numeric, @=Alpha or Numeric, !=Special Character
| Mask | Explanation | Example accountNumber |
|---|---|---|
| "mask": "@#######" | 1 alphanumeric character, followed by 7 numeric digits | "a1234567" |
| "mask": "#####" | 5 numeric digits | "12345" |
| "mask": "@@#######" | 2 alphanumeric character, followed by 7 numeric digits | "ab1234567" |
| "mask": "A#########" | The letter A, followed by 9 numeric digits | "A123456789" |
| "mask": "#######-##" | 7 numeric digits, followed by a dash and two more digits | "1234567-12" |
| "mask": "@@@@@@@@" | 8 alphanumeric characters | "a1b2c3d4" |
| "mask": "####**" | 4 numeric digits, followed by 2 alpha characters | "1234ab" |
| "mask": "###!####" | 3 numeric digits, followed by a special character and then 4 more digits | "123!1234" |
| "mask": "***###!@@@" | 3 alpha characters, followed by 3 numeric digits, then a special character, and 3 alphanumeric characters | "abc123!a1b" |
Biller aka object example
{
"recordType": "4",
"aka_key": "295758",
"record_effective_date": "2022-05-31",
"AKA_name": "Water" //Names the biller may go by
}
Biller contact object example
{
"recordType": "5",
"contact_key": "171582",
"record_effective_date": "2022-05-31",
"contact_type": "Scrub File",
"organization_name": "Harris County WCID #161",
"courtesy_title": "",
"fist_name": "Jennifer",
"last_name": "Morrow",
"title": "",
"address_line1": "900 Bay Area Blvd",
"address_line2": "",
"city": "Houston",
"state": "TX",
"country_code": "USA",
"postal_code": "77058-2604",
"email": "j.morrow@clcwa.org"
}
Biller phone object example
{
"recordType": "6",
"phone_key": "166967",
"record_effective_date": "2022-05-31",
"phone_type": "Phone",
"phone_number": "281-488-1146"
}
Encrypting Account Data
In some circumstances, such as with bill payments to card accounts, the account number must be encrypted. The /transfer-to/bills/initiate endpoint requires that sensitive account numbers (such as with card accounts) be encrypted.
Here is a code snippet that performs the encryption using the node.js crypto module. This example uses the public key method SHA-256. There are many other implementations for other languages and platforms (use the Webcrypto library).
The input arguments required by crypto are the user's public key and the account number. The result is an encrypted string with a length of 344 characters.
Make sure to npm install --save crypto fs if you do not have these dependencies already in your project.
The public keys necessary for account number encryption are available at Public Encryption Keys.
Encryption Example using JSON Web Key (JWK)
const fs = require("fs");
const crypto = require("crypto").webcrypto;
const str = "52187600########"; //some account number for billerId 9000005588, replace #'s with digits
const jwkPublicKey = fs.readFileSync("./src/encryption/public_primary.jwk");
(async () => {
const encoded = Buffer.from(str, "utf-8");
const publicKey = await crypto.subtle.importKey("jwk", JSON.parse(jwkPublicKey.toString()), {
name: "RSA-OAEP",
hash: "SHA-256"
}, true, ["encrypt", "wrapKey"]);
const mess = await crypto.subtle.encrypt({ name: "RSA-OAEP" }, publicKey, encoded);
const sendStr = Buffer.from(mess).toString("base64");
console.log(sendStr);
})();
Encryption Example using Privacy Enhanced Mail (PEM) Certificate
const fs = require("fs");
const crypto = require("crypto");
const str = "52187600########"; // billerId 9000005588
const publicKey = fs.readFileSync("public.key", "utf8");
(async () => {
const encoded = Buffer.from(str, "utf-8");
const sendStr = crypto.publicEncrypt({
key: publicKey,
padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
oaepHash: "sha256"
}, Buffer.from(str))
.toString("base64");
console.log(sendStr);
})();
Initiate a Transaction
Request method and URL:
POST /transfer-to/bills/initiate
Description:
Making a payment is a 3-step process. You need to:
- Initiate a transaction using
/transfer-to/bills/initiate. - Store the returned
cFiTransactionIdlocally. - 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://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc",
"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://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc",
"reference": "EXT_REFERENCE_ID2", //Different reference IDs
"narrative": "Both of these transactions will post"
}
The required request body properties are described below:
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| billerId | The biller id in connectFi | string, regex pattern: "^.{1,50}$" | "0123456789" |
| accountNumber | The customer's account number in the biller's system (Note: Use either accountNumber, for non-sensitive account numbers, or accountNumberEncrypted, for sensitive account numbers) | string, regex pattern: "^.{1,50}$" | "0123456789" |
| 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) | string, regex pattern: "^.{1,500}$" | see Encrypting Account Data |
| firstName | The first name of the biller. (Note: If the biller is an individual, the "firstName" property is required instead of "legalName") | string, regex pattern: "^.{1,22}$" | "John" |
| lastName | The last name of the biller. (Note: If the biller is an individual, the "lastName" property is required instead of "legalName") | string, regex pattern: "^.{1,22}$" | "Doe" |
| legalName | The legal name of the biller. (Note: If the biller is a business, the "legalName" property is required instead of the "firstName" and "lastName" properties) | string, regex pattern: "^.{1,22}$" | "Acme Inc." |
| amount | The requested bill payment amount | number > 0 | 11.23 |
| currency | A three character ISO alphabetic code to identify the currency | string, regex pattern: "^[A-Z]{3}$" | "USD" |
| reference | An external reference in your system (1-32 alphanumeric characters) | string, regex pattern: "^[0-9a-zA-Z]+$" | "externalTrnId2314" |
| 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". | string | "N" or "S" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| webhookUrl | URL which will be called after the bill payment. If you specify a webhookUrl in the /transfer-to/bills/initiate request, the system will perform a callback to your webhookUrl every time the wire status changes. Refer to Webhooks for the callback format. | string, regex pattern: "^.{1,500}$" | "https://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc" |
| narrative | A description of the transaction | string, regex pattern: "^.{1,500}$" | "Electricity bill payment" |
| 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. | boolean | true, false, or undefined |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
Initiating a payment transaction using accountNumberEncrypted
{
"amount": 10.93,
"currency": "USD", //currency code
"reference": "extTrnBill214",
"billerId": "0123456789", //biller id in connectFi
"accountNumberEncrypted": "bF828uITj...AWTKi7ekhfOw=9", //long encryption string representing customer's account in biller's system
"firstName": "Joe", // if private individual
"lastName": "Doe", // if private individual
//"legalName": "Acme Inc." //use instead of firstName and lastName if a business
"deliveryTimeCode" : "N", //"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"
"webhookUrl": "https://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc", //optional URL which will be called when transaction status changes
"narrative": "Some description of the transaction"
}
Initiating a payment transaction using accountNumber
{
"amount": 10.93,
"currency": "USD", //currency code
"reference": "extTrnBill217", //transaction reference in your system
"billerId": "0123456789", //biller id in connectFi
"accountNumber": "0123456789", //customer's account in biller's system
"legalName" : "Acme Inc", // if payer is a company OR "firstName", "lastName"
"deliveryTimeCode" : "N", //"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"
"webhookUrl": "https://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc", //optional URL which will be called when transaction status changes
"narrative": "Some description of the transaction"
}
Initiating a return transaction (reversals are available by additional agreement only)
{
"amount": 5.23, //number, must confirm that return amount is less than original transaction amount
"currency": "USD", //currency code
"reference": "extTrnBill201", //transaction reference in client system (must not be the same reference ID used in the original transaction)
"billerId": "0123456789", //biller id in connectFi
"accountNumber": "0123456789", //customer's account in biller's system
"legalName" : "Acme Inc", // if payer is a company OR "firstName", "lastName"
//"firstName" : "Joe", // if private individual
//"lastName" : "Doe", // if private individual
"deliveryTimeCode" : "N", //"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"
"webhookUrl": "https://webhooktest.examplesite/53f3a57e-e8b7-4b1b-af99-fa340c2e2b123abc", //optional URL which will be called when transaction status changes
"narrative": "Partial return of cFiTransactionId: evolve_1ElrTsdi0Qca0EC8m5ChH3", //description of reversal, please include cFiTransactionId of original transaction being reversed
"isReversal": true //true if this transaction is a reversal of a previous transaction
}
Possible responses:
200 (HTTP response status code) -- Request for payment was accepted and initiated. A connectFi ID is assigned to the transaction.
{
"code": "0", //Success
"data": {
"reference": "extTrnBill214", //transaction reference in your system
"cFiTransactionId": "evolve_xIDX3PbT53Ns7drR6Gvx2", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000005",
"status": "Initiated", //current status in connectFi
"amount": 10.93,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T12:46:52.750Z" //date and time created
},
"requestId": "11d45350f0c311ed9bbd56da8a862a98"
}
200 (HTTP response status code) -- Request for reversal was accepted and initiated. A connectFi ID is assigned to the transaction.
Note: Bill payment reversals are an option that is available by additional agreement only.
{
"code": "0", //Success
"data": {
"reference": "extTrnBill201", //transaction reference in client system (must not be the same reference ID used in the original transaction)
"cFiTransactionId": "evolve_1qyGmP5K3HMVtSPbrE4PBf", //transaction id in connectFi for the reversal
"status": "Initiated", //current status of the transaction
"amount": 5.23, //amount of the reversal transaction
"currency": "USD",
"dtsCreated": "2023-04-12T16:43:42.133Z" //date and time created
},
"requestId": "2eea0360d95111ed8ab742063d75cf12"
}
400 (HTTP response status code) -- Incorrect input data:
In this example, the required property "amount" was not included.
{
"requestId": "98244870f0cd11ed9fd756da8a862ca0",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/oneOf/0/required",
"keyword": "required",
"params": {
"missingProperty": "amount"
},
"message": "must have required property 'amount'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "amount"
},
"message": "must have required property 'amount'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Biller not found
In this example, a bill payment initiation for a biller ID not in the connectFi system was attempted.
{
"requestId": "199ff2306da811ee803ff0bab2a47312",
"code": "rppsBillerNotFound",
"context": {
"billerId": "00030006661"
},
"message": "Biller was not found or has been archived."
}
400 (HTTP response status code) -- Reference _____ exists
In this example, a request was made to initiate a bill, but the reference ID in the request is already associated with a previous bill payment request.
{
"requestId": "2cf019506da811ee803ff0bab2a47312",
"code": "transactionReference",
"context": {
"reference": "extTrnBill296",
"status": "Initiated",
"cFiAggregatorId": "evolve",
"cFiTransactionId": "evolve_4XQpMiqTcWPaG5yv8yR0k3",
"amount": 1.01
},
"message": "Entered reference exists for a different transaction."
}
400 (HTTP response status code) -- Need to send only one of accountNumber or accountNumberEncrypted
In this example, both an accountNumber and an accountNumberEncrypted property were included in the request body.
{
"requestId": "4796e9f06da811ee803ff0bab2a47312",
"code": "rppsAccountNumber",
"message": "Need to send only one of accountNumber or accountNumberEncrypted."
}
400 (HTTP response status code) -- AccountNumber must be encrypted
In this example, an accountNumber was included, when an accountNumberEncrypted was required for the instance.
{
"requestId": "3321d2d0f0cd11ed9fd756da8a862ca0",
"code": "rppsAccountNumberEncrypted",
"message": "AccountNumber must be encrypted"
}
Executing a Transaction
Request method and URL:
POST /transfer-to/bills/execute
Description:
This endpoint finalizes and executes a previously initiated transaction for processing. The property "cFiTransactionId" is required for the request body and obtained through the previous endpoint, /transfer-to/bills/initiate.
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
Possible responses:
200 (HTTP response status code) -- Success, the payment has been executed and is processing
{
"code": "0", //Success
"data": {
"reference": "extTrnBill218", //transaction reference in your system
"cFiTransactionId": "evolve_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000008",
"status": "Processing", //current transaction status
"amount": 10.93, //amount of payment requested
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T14:27:33.684Z" //date created
},
"requestId": "80b73a80f0d711ed9bc156da8a861818"
}
400 (HTTP response status code) -- Bill not found
In this example, an attempt was made to execute a bill payment transaction with a cFiTransactionId that does not exist in the connectFi system.
{
"requestId": "788aa6f06da811ee803ff0bab2a47312",
"code": "billNotFound",
"context": {
"cFiTransactionId": "evolve_6gDfQmP35fAGFtuiDKxXx2"
},
"message": "Bill not found."
}
400 (HTTP response status code) -- Missing required property
In this example, an attempt was made to execute a bill payment transaction without a cFiTransactionId property.
{
"requestId": "890196606da811ee803ff0bab2a47312",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": {
"missingProperty": "cFiTransactionId"
},
"message": "must have required property 'cFiTransactionId'"
}
]
}
400 (HTTP response status code) -- Bill status processing error
In this example, a duplicate attempt was made to execute a bill payment transaction. This bill already has a status of "Sent" because a request to execute the bill was already made.
{
"requestId": "dc2ad170774011eeb5658f28ab5fe311",
"code": "rppsBillStatus",
"context": {
"cFiTransactionId": "evolve_3bzlbEvJD9bWQpnQ85glih",
"cFiAggregatorId": "evolve",
"entityStatus": "Sent"
},
"message": "This transaction does not have a valid status for the requested action."
}
Query Transaction Status
Request method and URL:
POST /transfer-to/bills/query
Description:
The status of up to 20 bill payment transactions may be requested at a time (either using the "references" array or the "cFiTransactionIds" array). The array that you include may not be an empty array.
The system will return only the bill payment transactions it could locate. Unknown IDs will be ignored and if no IDs are recognized, an empty array is returned with success code "0".
If the same ID is requested multiple times in the "сFiTransactionIds" or "references" array, the response will only return one object in the data array corresponding to that ID, regardless of how many times it was listed in the request array.
If more than 20 elements are listed in the request array (either "сFiTransactionIds" array or the "references" array), an error will be thrown even if the IDs are not unique. For example, if the cFiTransactionId "spwhl_5dRyPYn4mlXUAOTfhObZlw" is listed 21 times in the request array, the request will fail even though technically only one unique ID was requested.
Either "cFiTransactionIds": [...] should be used or "references": [...], but not both. You cannot combine both types of IDs into a single request.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiTransactionIds | Array of transaction IDs from the connectFi system obtained when each transaction was initialized | array | ["evolve_13c261GGqsFL1yElgKBrnS", "evolve_64gfG7m5Vm199dKU2b9efG", ...] |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| references | Array of external IDs from your system that you entered when initializing the bill payments | array | ["extTrnBill218", "extTrnBill219", ...] |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
Request body (using connectFi transaction IDs)
{
"cFiTransactionIds": ["evolve_13c261GGqsFL1yElgKBrnS", "evolve_64gfG7m5Vm199dKU2b9efG"] //array of transaction IDs in connectFi
}
Request body (using external system references)
{
"references": ["extTrnBill218", "extTrnBill219"] //array of external references from your system
}
Possible responses:
200 (HTTP response status code) -- Success, Transaction statuses are returned
Both request body examples above will return the same two bill payment transactions, although not necessarily in the same order.
{
"code": "0", //Success
"data": [
{
"reference": "extTrnBill218", //external reference from your system
"cFiTransactionId": "evolve_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000008",
"status": "Processing", //current transaction status
"amount": 10.93,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T14:27:33.684Z" //date created
},
{
"reference": "extTrnBill219", //external reference from your system
"cFiTransactionId": "evolve_64gfG7m5Vm199dKU2b9efG", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000009",
"status": "Initiated", //current transaction status
"amount": 7.15,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T15:22:16.734Z" //date created
}
],
"requestId": "d084f510f0d811ed9bc156da8a861818"
}
200 (HTTP response status code) -- Success, сFiTransactionIds/references requested do not exist
In this example, the request was successful but the requested transaction IDs do not exist in connectFi.
{
"code": "0", //Success
"data": [], //no matching transactions
"requestId": "7b57e240f0d911ed9bc156da8a861818"
}
400 (HTTP response status code) -- Array ("references" or "cFiTransactionIds") must NOT have fewer than 1 items
In this example, the references array property or the cFiTransactionIds array property did not contain at least 1 ID. This error will be thrown if the ID array used (either references or cFiTransactionIds) is empty.
{
"requestId": "9190f880f0d911ed9bc156da8a861818",
"code": "requestValidateError",
"context": [
{
"instancePath": "/cFiTransactionIds",
"schemaPath": "#/oneOf/0/properties/cFiTransactionIds/minItems",
"keyword": "minItems",
"params": {
"limit": 1
},
"message": "must NOT have fewer than 1 items"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "references"
},
"message": "must have required property 'references'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Must not have fewer than 1 characters
In this example, the array included in the request body contained at least one empty string, "". Each cFiTransactionId must have between 1 and 32 characters. Each reference ID must have between 1 and 32 characters.
{
"requestId": "b57a1600f0d911ed9bc156da8a861818",
"code": "requestValidateError",
"context": [
{
"instancePath": "/cFiTransactionIds/0",
"schemaPath": "common#/definitions/id/minLength",
"keyword": "minLength",
"params": {
"limit": 1
},
"message": "must NOT have fewer than 1 characters"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "references"
},
"message": "must have required property 'references'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Must not have more than 20 items
In this example, more than 20 reference IDs were included in the "references" array property in the request body. You may not include more than 20 reference IDs or cFiTransactionIds in a single request (even if they are not unique IDs).
{
"requestId": "ce8d0030f0d911ed9bc156da8a861818",
"code": "requestValidateError",
"context": [
{
"instancePath": "/cFiTransactionIds",
"schemaPath": "#/oneOf/0/properties/cFiTransactionIds/maxItems",
"keyword": "maxItems",
"params": {
"limit": 20
},
"message": "must NOT have more than 20 items"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "references"
},
"message": "must have required property 'references'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code)
List Transactions
Request method and URL:
POST /transfer-to/bills/list
Description:
This endpoint will list transactions that match the desired search criteria. Search criteria may be a specific cFiTransaction or reference ID, a date range, a settlement date, an exception date, a status value, or a combination of criteria. You may also specify a maximum number of records to return using the numberOfRecords property (up to 1000) and you may specify a number of records to skip using the skipRecords property. Combine the numberOfRecords property with the skipRecords property to make displaying transaction lists in batches easy. For example, if you want to list transactions in batches of 150, you can set numberOfRecords to 150 and skipRecords to 0 in the first request. Then, increase skipRecords by 150 in each subsequent request to return the next batch and so on.
When making a request, if the number of transactions matching the criteria is greater than the numberOfRecords maximum requested, the response body will indicate that there are additional transactions ("more": true).
If no properties are included, an unfiltered transaction list will be returned (up to a maximum of 1000).
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiTransactionId | Transaction ID from the connectFi system obtained when the transaction was initialized, nullable | string, regex pattern: "^[0-9a-zA-Z_]+$" | "evolve_13c261GGqsFL1yElgKBrnS" |
| reference | The external reference for the transaction in your system (1-32 alphanumeric characters), nullable | string, regex pattern: "^[0-9a-zA-Z]+$" | "externalTrnId2314" |
| dateCreateFrom | A beginning date in ISO Date format, if using a date range to list transactions, nullable | string | "2023-05-10T12:46:31.578Z" |
| dateCreateTo | An ending date in ISO Date format, if using a date range to list transactions, nullable | string | "2023-05-13T12:46:31.578Z" |
| dateSettled | A date in YYYY-MM-DD format, if searching for settled transactions by date, nullable | string | "2023-05-10" |
| dateException | A date in YYYY-MM-DD format, if searching for exceptions by date, nullable | string | "2023-05-10" |
| status | The desired status for which to search, nullable | string | "Initiated", "Processing", "Sent", "Complete", "Settled", "Declined", "Unknown", or "DecryptError" |
| numberOfRecords | The maximum number of desired records to return, nullable | integer <=1000 | 850 |
| skipRecords | The number of records to skip when returning results, nullable | integer | 25 |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
Request body (using connectFi transaction ID)
Request body (using external system references)
Request body (using a date range)
Request body (using a combination of desired search criteria)
{
"dateCreateFrom": "2023-04-01T14:27:33.684Z", //beginning of requested date range
"dateCreateTo": "2023-05-12T14:27:33.684Z", //end of requested date range
"status": "Initiated", //will only return transactions with an "Initiated" status
"numberOfRecords": 15, //will return up to a maximum of 15 records
"skipRecords": 1 //will skip the first transaction found
}
Possible responses:
200 (HTTP response status code) -- Success, Transactions that meet the search criteria will be returned.
{
"code": "0", //Success
"data": {
"total": {
"skipRecords": 1, //the number of records that were skipped
"numberOfRecords": 2, //maximum number of records requested
"more": false //true if the number of records found is greater than the "numberOfRecords" requested
},
"items": [
{
"reference": "extTrnBill215", //external reference from your system
"cFiTransactionId": "evolve_2ZbKXbTaBk07vCwle6WijW", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000006",
"status": "Initiated", //current transaction status
"amount": 10.93,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T14:00:42.386Z" //date created
},
{
"reference": "extTrnBill214", //external reference from your system
"cFiTransactionId": "evolve_xIDX3PbT53Ns7drR6Gvx2", //transaction ID in connectFi
"merchantId": "12345678", //ID required for use of /transfer-to/bills endpoints
"cFiTraceNumber": "000000000000005",
"status": "Initiated", //current transaction status
"amount": 14.23,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T12:46:52.750Z" //date created
}
]
},
"requestId": "4666aa20f0df11ed9bc156da8a861818"
}
200 (HTTP response status code) -- Success, no transactions that meet the search criteria were found.
Note: If the dateCreateTo date is before the dateCreateFrom date, you will receive the same response. Check to make sure the date range is valid if no transactions meet your criteria when transactions are expected.
{
"code": "0",
"data": {
"total": {
"skipRecords": 2,
"numberOfRecords": 0,
"more": false
},
"items": []
},
"requestId": "85f558b0f0e111ed9bc156da8a861818"
}
400 (HTTP response status code) -- numberOfRecords field greater than 1000
In this example, the number of maximum records requested was greater than 1000.
{
"requestId": "1c0cb7006da911ee803ff0bab2a47312",
"code": "greaterNumberOfRecords",
"context": {
"maxNumberOfRecords": 1000
},
"message": "The numberOfRecords field is greater than the request limit"
}
400 (HTTP response status code) -- Must be equal to one of the allowed values
In this example, an invalid status value was requested.
{
"requestId": "1f302f00f0e211ed9bc156da8a861818",
"code": "requestValidateError",
"context": [
{
"instancePath": "/status",
"schemaPath": "#/properties/status/enum",
"keyword": "enum",
"params": {
"allowedValues": [
"Initiated",
"Processing",
"Sent",
"Complete",
"Settled",
"Declined",
"Unknown",
"DecryptError"
]
},
"message": "must be equal to one of the allowed values"
}
]
}
Settlement Summary
Request method and URL:
POST /transfer-to/bills/summary
Description:
This endpoint will return an activity summary for a specified date, along with transactions, exceptions associated with transactions, and extra exceptions (exceptions not associated with transactions). This report will be helpful when reconciling daily RPPS activity.
Since RPPS settlement occurs within the same or next business day of transaction execution, it is not recommended to pull this report for the current day. It is recommended to request this report only once per day for a previous day's date.
A notes array will also be returned containing any messages obtained while generating the summary. For each transaction, the originally requested transaction amount will be compared to the settled amount. A similar reconciliation will occur for each exception and descrepancies will be recorded in the notes array as well.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| date | The requested date in ISO Date format | string | "2023-05-10T12:46:31.578Z" |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
Possible responses:
200 (HTTP response status code) -- Success, a summary will be returned, along with transactions, exceptions, and extraExceptions for the specified date.
{
"code": "0", //Success
"data": {
"cFiAggregatorId": "pgclient",
"date": "2023-04-26", //requested date
"summary": {
"cFiAggregatorId": "pgclient",
"merchantId": "12345678",
"date": "2023-04-26", //requested date
"fileName": "3113_0024_20230426_summary_v2-5.csv",
"purchase": { //summary of purchases (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"convenienceFees": { //summary of convenience fees (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"credits": { //summary of credits (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"refunds": { //summary of refunds (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"disburse": { //summary of disbursements (total number of transactions and total amount)
"transactions": 211,
"amount": -113984.85,
"currency": "USD", //currency code
},
"chargebacks": { //summary of chargebacks (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"adjustments": { //summary of adjustments (total number of transactions and total amount)
"transactions": 3,
"amount": 594.34,
"currency": "USD", //currency code
},
"reserve": { //reserve summary (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"totals": { //overall totals summary (total number of transactions and total amount)
"transactions": 214,
"amount": -298705.51,
"currency": "USD", //currency code
},
"indicativeInterchange": { //indicative interchange summary (total number of transactions and total amount)
"transactions": 214,
"amount": 0,
"currency": "USD", //currency code
},
"actualInterchangeDifference": { //actual interchange difference summary (total number of transactions and total amount)
"transactions": 0,
"amount": 0,
"currency": "USD", //currency code
},
"networkFees": { //network fees summary (total number of transactions and total amount)
"transactions": 211,
"amount": -12.66,
"currency": "USD", //currency code
},
"dtsCreatedAt": "2023-05-13T10:52:21.356Z",
"updatedAt": "2023-05-13T10:52:21.356Z"
},
"transactions": [
{
"reference": "exteralTrnIdb1", //external reference from your system
"cFiTransactionId": "pgclient_2EgxMgHLDHOr88Ynk31234", //transaction ID in connectFi
"merchantId": "12345678",
"cFiTraceNumber": "000000000001234",
"status": "Settled",
"amount": 491.08,
"currency": "USD",
"dtsCreated": "2023-04-25T19:21:12.321Z",
"dtsSent": "2023-04-25T21:30:07.306Z",
"processing": {
"dateProcessed": "2023-04-25",
"isReversal": false,
"remarks": "",
"responseCode": "",
"status": "Completed"
},
"dataSettled": "2023-04-26",
"settled": {
"id": "RPPS12345678926",
"networkFee": -0.06,
"settledAmount": -491.08,
"status": "Complete",
"settlementDate": "2023-04-26"
}
},
{
"reference": "exteralTrnIdce2", //external reference from your system
"cFiTransactionId": "pgclient_2EBsOcGHEX9dZ1qSrq1234", //transaction ID in connectFi
"merchantId": "12345678",
"cFiTraceNumber": "000000000001235",
"status": "Settled",
"amount": 421.78,
"currency": "USD",
"dtsCreated": "2023-04-25T19:21:12.621Z",
"dtsSent": "2023-04-25T21:30:07.306Z",
"processing": {
"dateProcessed": "2023-04-25",
"isReversal": false,
"remarks": "",
"responseCode": "",
"status": "Completed"
},
"dataSettled": "2023-04-26",
"settled": {
"id": "RPPS12345678927",
"networkFee": -0.06,
"settledAmount": -421.78,
"status": "Complete",
"settlementDate": "2023-04-26"
}
},
//... rest of the transactions for the specified date
],
"exceptions": [
{
"reference": "exteralTrnId3", //external reference from your system
"cFiTransactionId": "pgclient_7prQNYkMO5MfVdWJz11234", //transaction ID in connectFi
"merchantId": "12345678",
"cFiTraceNumber": "000000000001236",
"status": "Declined",
"amount": 127.74,
"currency": "USD",
"dtsCreated": "2023-04-18T19:41:02.368Z",
"dtsSent": "2023-04-18T21:30:07.317Z",
"processing": {
"dateProcessed": "2023-04-18",
"isReversal": false,
"remarks": "",
"responseCode": "",
"status": "Completed"
},
"dataSettled": "2023-04-19",
"settled": {
"id": "RPPS12345678169",
"networkFee": -0.06,
"settledAmount": -127.74,
"status": "Complete",
"settlementDate": "2023-04-19"
},
"dataException": "2023-04-26",
"exception": {
"id": "RPPS12345678169",
"exceptionAmount": 127.74,
"networkFee": 0,
"exceptionCode": "R02",
"exceptionDescription": "Customer account closed-Merchant paid",
"exceptionDate": "2023-04-26"
}
},
{
"reference": "exteralTrnId4", //external reference from your system
"cFiTransactionId": "pgclient_6ht4w9wrQnE7eWlWsA1234", //transaction ID in connectFi
"merchantId": "12345678",
"cFiTraceNumber": "000000000001237",
"status": "Declined",
"amount": 478.64,
"currency": "USD",
"dtsCreated": "2023-04-20T18:26:02.866Z",
"dtsSent": "2023-04-20T21:30:07.525Z",
"processing": {
"dateProcessed": "2023-04-20",
"isReversal": false,
"remarks": "",
"responseCode": "",
"status": "Completed"
},
"dataSettled": "2023-04-21",
"settled": {
"id": "RPPS12345678224",
"networkFee": -0.06,
"settledAmount": -478.64,
"status": "Complete",
"settlementDate": "2023-04-21"
},
"dataException": "2023-04-26",
"exception": {
"id": "RPPS12345678224",
"exceptionAmount": 478.64,
"networkFee": 0,
"exceptionCode": "R02",
"exceptionDescription": "Customer account closed-Merchant paid",
"exceptionDate": "2023-04-26"
}
}
],
"extraExceptions": [
{
"id": "A23042612345678",
"merchantId": "12345678",
"cFiAggregatorId": "pgclient",
"merchantReferenceId": "TP12345678",
"exceptionAmount": -12.04,
"networkFee": 0,
"exceptionCode": "0",
"exceptionDescription": "Miss debited - RPPS-",
"exceptionDate": "2023-04-26",
"fileName": "3113_0024_20230426_exceptions_v2-5.csv",
"dtsCreatedAt": "2023-05-13T10:52:21.328Z",
"updatedAt": "2023-05-13T10:52:21.328Z"
}
],
"notes": [] //an array of warning/error messages obtained while generating the summary
},
"requestId": "18790320f3fe11eda56f1008c9ab6112"
}
400 (HTTP response status code) -- Must have required property 'date'
In this example, the required date property was not included in the request.
{
"requestId": "d1327a70f40a11eda56f1008c9ab6112",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": {
"missingProperty": "date"
},
"message": "must have required property 'date'"
}
]
}
400 (HTTP response status code) -- Must match pattern \"^\d{4}-\d{2}-\d{2}$\"
In this example, the requested date was not in the correct YYYY-MM-DD format.
{
"requestId": "06b4c040f40b11eda56f1008c9ab6112",
"code": "requestValidateError",
"context": [
{
"instancePath": "/date",
"schemaPath": "common#/definitions/dateOnly/pattern",
"keyword": "pattern",
"params": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"message": "must match pattern \"^\\d{4}-\\d{2}-\\d{2}$\""
}
]
}
Webhooks
Description:
If you specify a webhook URL in the /transfer-to/bills/initiate endpoint, every time a transaction status changes due to a response Paygears 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.
{
"code": "0",
"data":
{
"reference": "extTrnBill218", //external transaction ID in your system
"cFiTransactionId": "evolve_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
"merchantId": "10000001",
"cFiTraceNumber": "000000000000008",
"status": "Sent", //current status
"amount": 10.93,
"currency": "USD", //currency code
"dtsCreated": "2023-05-12T14:27:33.684Z" //date created
}
}
Possible Status Values
| Value of status property | Description |
|---|---|
| Initiated | A /transfer-to/bills/initiate request has successfully created the bill transaction entity and returned the cFiTransactionId that was created. |
| Processing | A /transfer-to/bills/execute request has successfully updated the bill transaction entity and registered it to be executed. |
| Sent | Multiple times a day, connectFi will validate, package, and send files containing all of the unsent bill transactions that have been registered for execution. A bill transaction with a "Sent" status has successfully been sent for payment. |
| Complete | A "Complete" status indicates that PayGears has received a response that the payment request was received successfully. |
| Settled | A "Settled" status indicates that PayGears has received a response that the amount has been deducted from the settlement account. |
| Declined | A "Declined" status indicates that PayGears has received a response that the payment failed or was returned. |
| DecryptError | A "DecryptError" status indicates that there was an error with the encryption interface (for PAN transactions only). Contact support for next steps. |
| Unknown | An "Unknown" status indicates that PayGears has received an unexpected response and a manual review will need to take place. Please contact support. |