About
Introduction
The connectFi API is designed to support Banking-as-a-Service (BaaS) by providing a clear and consistent interface to back end banking services simply and quickly. The connectFi API provides a low level of abstraction to complement your existing front-end and middle-ware components when adding or extending existing functionality from a single, stand-alone API. The connectFi API allows a single user to get products from multiple individual back-end systems and can orchestrate transactions in different back-offices into a single transaction in the front-end.
API Concepts
The API provides REST endpoints that can be accessed directly from your program code. All requests are made using the http verbs GET, PUT, POST, and DELETE. The endpoints available through the connectFi API are:
| Endpoint | Usage |
|---|---|
| /auth/get-token | Getting and using authorization access token |
| /user/change-password | Change the password of the currently logged in user (client/FinTech/aggregator) |
| Endpoint | Usage |
|---|---|
| /health | Check the health of the application |
| Endpoint | Usage |
|---|---|
| /customer/init | Create a customer |
| /customer/update | Update a customer's details |
| /customer/status/:customerId | Get customer information |
| /customer/add-employee | Add an employee to a business customer |
| /customer/disable-employee | Disable an employee associated with a business customer |
| Endpoint | Usage |
|---|---|
| /akepa/identification | KYC (Know Your Customer)/KYB (Know Your Business) process initialization through akepa |
| /akepa/status/:customerId | Get the current KYC/KYB approval status |
| /akepa/document/generate | Generate a document ID before uploading the document |
| /akepa/document/upload/:documentId | Upload a document and attach the upload to a pregenerated document ID |
| /akepa/update | Update KYC/KYB application by linking additional required documents |
| Endpoint | Usage |
|---|---|
| /transfer-to/ach/create | Send an ACH funds transfer |
| Standard Entry Class Codes | SEC table containing descriptions of Standard Entry Class Codes and conditions for each |
| /transfer-to/ach/query | Query details of one or more ACH transfers |
| /transfer-to/ach/list | List ACH transfers by search criteria |
| /transfer-to/ach/return-rates | Retrieve return rate data, including number of days out of compliance with NACHA thresholds for administrative return rates, unauthorized return rates, or overall return rates |
| Webhooks | Information about optional webhookUrls |
| Possible Status Values | List and descriptions of possible ACH transfer status values |
| ACH Transfers Using SFTP File Transfer | Send batch ACH transfer requests through SFTP File Transfer (an alternate to sending ACH funds transfer requests through the /transfer-to/ach/create endpoint) |
Money Transfer: RPPS Bill Payment
| Endpoint | Usage |
|---|---|
| /transfer-to/bills/billers/download | Download 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 for processing |
| /transfer-to/bills/query | Get the status of up to 20 bill payment transactions |
| /transfer-to/bills/list | List existing bill payment transactions by specified search criteria |
| /transfer-to/bills/summary | Summarize RPPS activity for a specified date |
| Possible Status Values | Description of possible RPPS transaction status values |
| RPPS Webhooks | Description of RPPS transaction webhooks |
Money Transfer: Push/Pull to Card
| Endpoint | Usage |
|---|---|
| /transfer-to/card/register | Register an external card |
| /transfer-to/card/get/:cardId | Get card details for a previously registered external card |
| /transfer-to/card/pull | Pull money from an external card |
| /transfer-to/card/push | Push money to an external card |
| /transfer-to/card/transaction-query | Query details of one or more push/pull transactions |
| /transfer-to/card/list/transactions | List existing push/pull transactions by specified search criteria |
| /transfer-to/card/reversal | Reverse a specified pull transaction |
| Possible Status Values | Description of possible push/pull transaction status values |
| Possible Reversal Status Values | Description of possible transaction reversal status values |
| Encrypting Sensitive Card Data | Description of how to encrypt sensitive card data before registering an external card |
| Endpoint | Usage |
|---|---|
| /transfer-to/wire | Send US-domestic wires |
| /transfer-to/wire/query | Query status of wires |
| /transfer-to/wire/list | List existing wire transfer transactions by specified search criteria |
| Possible Status Values | Description of possible wire transfer status values |
| Testing Wires in the Sandbox | How to trigger desired error messages in the sandbox |
| Wires Webhooks | Description of wires webhooks |
Money Transfer: Unified Payments
| Endpoint | Usage |
|---|---|
| Encrypting Card Data | Instructions for encrypting sensitive card data before registering an external card |
| /transfer-to/combo/card/register | Register card to enable push/pull transactions for the card |
| /transfer-to/combo/create | Create a transaction (either ACH, wire, pull from card, or push to card) |
| Additional Actions Available to Unified Card Payments Transactions | List and descriptions of actions available for transactions created using the unified card payments endpoint |
| Possible Status Values | List and descriptions of possible transfer status values |
| Webhooks | Information about optional webhookURLs |
| Endpoint | Usage |
|---|---|
| /acquiring/register | Register a new card (acquiring) |
| /acquiring/pull | Pull funds from a registered card (acquiring) |
| /acquiring/transactions-query | Query card transactions (acquiring) |
| /acquiring/list | List existing acquiring pull transactions by specified search criteria |
| /acquiring/reversal | Reverse a card transaction (acquiring) |
| Possible Status Values | Description of possible acquiring pull transaction status values |
| Possible Reversal Status Values | Description of possible transaction reversal status values |
| Encrypting Sensitive Card Data | Description of how to encrypt sensitive card data before registering an external card |
Issuing: Debit Cards/Credit Cards
| Endpoint | Usage |
|---|---|
| /check/print | Create a check to be printed |
| /check/get/:checkId | Get the details of a specified check |
| /check/query | Query details of up to 20 checks |
| /check/void | Request to void an existing check |
| /check/list | List checks by search criteria |
| Possible Status Values | Description of possible cFiCheckStatus status values |
| Check Printing Webhooks | Description of check printing webhooks |
More endpoints coming soon
Common Elements
This section describes some elements that are common to most, if not all, of the connectFi API calls. These elements are not discussed in the individual descriptions unless necessary.
Each method is invoked by an http request to an API endpoint using one of the verbs GET, PUT, POST or DELETE. Path parameters may be encoded in the URL.
All requests except login require the authorization token that is returned by a login call. This token must be copied to a header parameter named "x-connectfi-token".
Most POST and PUT requests provide a request body in JSON format. However, some POST and PUT requests require form-data instead. The specific documentation for each section will indicate which format is required for each request. When a JSON format request body is required, the Content-Type header should be application/json. When form data is required, the Content-Type header should be multipart/form-data. For GET requests the request body is empty, but path parameters encoded in the URL may be necessary.
Each request returns a status code, along with a set of standard http headers which may be ignored.
In some cases a response body is also returned in JSON format.
If the call succeeds, the response body includes the element
"code": "0"
and the status code is 200 or 201. If the call fails, the status code is 300 or greater, and the response body gives an appropriate message.
Pre-requisite Requests
Some requests will fail if pre-requisite requests have not been completed prior to the current request. In the same way that all requests (except logging in) will fail without a token, many requests require a reference to prior responses received from these pre-requisite requests before they will succeed.
For example, a debit card cannot be activated unless the debit card is first added to a customer. Likewise, a debit card cannot be added to a customer unless the customer has been initialized, all necessary documents have been uploaded, and the kycStatus is "APPROVED".
Deprecated Endpoints
The following endpoints are deprecated and will no longer receive additional features or support. Instead of using /condor endpoints, it is recommended to use /ibis endpoints. Ibis endpoints support both credit-card issuing and debit-card issuing. Instead of using /customer/kyc and /document endpoints, we recommend the use of the /akepa endpoints for KYC/KYB verification and document upload.