Skip to content

Push To/Pull From Cards

The endpoints in this section may be used to pull money from or push money to an external card (a card that was not issued through the connectFi API).

Before transactions with external cards can occur, the card must be registered.

  • Register the external card through a /transfer-to/card/register request.
  • Push money from your settlement account to a registered external card through a /transfer-to/card/push request.
  • Pull money from a registered external card to your settlement account through a /transfer-to/card/pull request.

Debits and credits to/from cards issued through connectFi, including peer-to-peer (p2p) transactions, will be completed through separate transaction endpoints. The /transfer-to/card/register, /transfer-to/card/push, and /transfer-to/card/pull endpoints are specific to transactions involving cards that were not issued through connectFi.

The settlement account refers to the main account in Evolve bank in which you (the connectFi client) maintain a minimum deposit as collateral for future transactions.

Endpoint or Section Action
Encrypting Card Data Instructions for encrypting sensitive card data before registering an external card
/transfer-to/card/register Register card to enable push/pull transactions for the card
/transfer-to/card/get/:cardId Get the details of a registered card
/transfer-to/card/push Push money to a registered card
/transfer-to/card/pull Pull money from a registered card
Possible Transaction Status Values List and descriptions of possible transaction status values
/transfer-to/card/transactions-query Query details of one or more push/pull transactions
/transfer-to/card/list/transactions List transactions by search criteria
/transfer-to/card/reversal Reverse a specified pull transaction
Possible Transaction Reversal Status Values List and descriptions of possible transaction reversal status values

Encrypting Card Data

To pull money from an external card or to push to an external card, you need to register the card with connectFi first. The /transfer-to/card/register endpoint requires that the card data be encrypted. You will need to concatenate and encrypt the card PAN (full 16-digit card number), expiration date and CVV.

Here is a code snippet that performs the encryption using the standard node.js crypto module. This example uses the public key method sha256. There are many other implementations for other languages and platforms.

The input arguments required by crypto are the user's public key and the concatenated card data. The result is an encrypted string with a length of 256 bits.

Make sure to npm install --save base64url crypto fs if you do not have these dependencies already in your project.

const pan = '1234567890123456' // the 16 digit Primary Account Number for the card
const expiryYYYYMM = '202211' // the date of expiration for the card
const cvv = '123' // the cvv code on the back of the card
const base64url = require("base64url").default;
const fs = require("fs");
const crypto = require("crypto"); //node standard crypto
const myKey = fs.readFileSync("./public.key");
const rawData = `${pan}|${expiryYYYYMM}|${cvv}`; //1234567890123456|202211|123

const encryptedData = crypto.publicEncrypt({
    key: myKey,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "sha256",
  },
    Buffer.from(rawData)
  );
return base64url(encryptedData);

Back to Top

Register an External Card

Request method and URL:

POST /transfer-to/card/register

Description:

Once the external card data is encrypted, this endpoint will register it in the connectFi database.

The /transfer-to/card/register 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 registrations. It is important to note that card registrations submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following requests are not considered duplicates even though they refer to the same card data. If both of these requests are processed, there will be two separate registrations with two separate reference IDs for the same external card.

{
  "reference": "EXT_REFERENCE_ID1", //Different reference IDS
  "card": {
    "encryptedData": "u5zl2moWuA...gFNLRg", //exact same encryption data
    "keyId": "h123...abcw" //exact same key ID
  },
  "owner": { //same owner details
    "name": {
      "first": "John",
      "middle": "M",
      "last": "Doe",
      "suffix": "III"
    },
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    }
  }
}

{
  "reference": "EXT_REFERENCE_ID2", //Different reference IDS
  "card": {
    "encryptedData": "u5zl21234...gFNLRg", //exact same encryption data
    "keyId": "h123...abcw" //exact same key ID
  },
  "owner": { //same owner details
    "name": {
      "first": "John",
      "middle": "M",
      "last": "Doe",
      "suffix": "III"
    },
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    }
  }
}

The request body properties for this endpoint are:

Required Properties Description Schema Example Values
card The external card being registered, consisting of the encrypted data and a keyId object see Card Object below
owner The card holder details object see Owner Object below
reference An external alphanumeric reference ID (1-32 characters) for the card in your system string, regex pattern: ^[0-9a-zA-Z]+$ "externalCardId02"

Card Object

Required Properties Description Schema Example Values
encryptedData A long string containing the encrypted card data string, regex pattern: ^.{1,500}$ see Encrypting Card Data
keyId The ID of your public key string, regex pattern: ^.{1,50}$ "123"

Owner Object

Required Properties Description Schema Example Values
address The card holder's address object see Address Object below
name The card holder's name object see Name Object below
phone The card hold's phone number object see Phone Object below

Address Object

Properties Description Schema Example Values
addressLine1 Cardholder address line 1 (required) string, regex pattern: ^.{1,50}$ "1346 Some Ave"
addressLine2 Cardholder address line 2 (optional) string, regex pattern: ^.{0,50}$ "Apt A123"
city Cardholder city (required) string, regex pattern: ^.{1,50}$ "Salt Lake City"
state Cardholder state (required) string, regex pattern: ^.{1,50}$ "UT"
postalCode Cardholder postal code (required), each # represents a digit 0-9 string, regex pattern: "^[0-9a-zA-Z-]{5,10}$" "#####"
country Cardholder country (required) string, regex pattern: ^[A-Z]{2}$ "US"

Name Object

Properties Description Schema Example Values
first Cardholder first name (required) string, regex pattern: ^.{1,50}$ "John"
last Cardholder last name (required) string, regex pattern: ^.{1,50}$ "Doe"
middle Cardholder middle name (optional, nullable) string, regex pattern: ^.{0,50}$ "M"
suffix Cardholder suffix (optional, nullable) string, regex pattern: ^.{0,50}$ "III"

Phone Object

Required Properties Description Schema Example Values
countryCode Cardholder phone country code string, regex pattern: ^.{1,4}$ "1"
number Cardholder 10 digit phone number, each # represents a digit 0-9 string, regex pattern: ^[0-9]{10}$ "##########"

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
  "reference": "externalCardId01", //unique ID of the card in the client system 
  "card": {
    "encryptedData": "<encryptedData", //PAN, expiry, CVV as a long encryption string
    "keyId": "123" //ID of your public key
  },
  "owner": { //cardholder
    "name": {
      "first": "John",
      "middle": "M", //optional
      "last": "Doe",
      "suffix": "III" //optional
    },
    "address": {
      "addressLine1": "1346 Some Ave",
      "addressLine2": "Apt A123", //optional
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "#####", //a postal code (5-9 digits is typical for the US), ##### is used as a placeholder here for documentation purposes
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "##########" //a phone number (10 digits for the US), ########## is used as a placeholder here for documentation purposes
    }
  }
}

The same card can be registered multiple times.

Possible responses:

200 (HTTP response status code) -- Success, request for registering a card was accepted and will be processed:

{
    "code": "0", //Success
    "data": {
        "cFiCardId": "tcrd_5F6cM6PnllBKutxDb10gqY", //card ID in connectFi
        "dtsRegistered": "2023-05-15T14:56:52.407Z", //date registered
        "reference": "externalCardId50", //give external reference
        "isPullEnabled": true, //True if pull transactions are enabled for the card
        "isPushEnabled": true, //True if push transactions are enabled for the card
        "cardExpirationDate": "202512", //Card expiration date
        "cardLast4": "1234" //Last 4 digits of the card number
    },
    "requestId": "b8f66a50f33011eda84f56da8a8643b8"
}

400 (HTTP response status code) -- Duplicate cardReference:

{
    "requestId": "0493e350684f11ee8df9d847b134c812",
    "code": "referenceExists",
    "context": {
        "reference": "externalCardId60"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Incorrect input data:

{
    "requestId": "8b376090f33211eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "card"
            },
            "message": "must have required property 'card'"
        }
    ]
}

400 (HTTP response status code) -- Invalid keyId value

This example shows the response when the request body contains an invalid keyId value.

{
    "requestId": "95a953d0f33211eda84f56da8a8643b8",
    "code": "extToucan",
    "subCode": 400,
    "context": {
        "errorCode": "3C3E1402"
    },
    "message": "card.keyID"
}

400 (HTTP response status code) -- Other errors:

{
    "requestId": "unique0Random1Request2Identifier",
    "code": "<not zero code>",
    "context": {
        "key": "value"
    },
    "message": "Some error",
}

Back to Top

Get Registered Card

Request method and URL:

GET /transfer-to/card/get/:cardId

Description:

This endpoint will return the details of the registered card specified. The cFiCardId for the requested card should be included as a path parameter, ":cardId".

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 retrieving details of registered card requested

{
    "code": "0", //Success
    "data": {
        "cFiCardId": "tcrd_508IaE0NgrygZ2SSTJmYcw", //card ID in connectFi
        "dtsRegistered": "2023-01-30T19:26:59.383Z", //date registered
        "reference": "externalCardId257", //give external reference
        "isPullEnabled": true, //True if pull transactions are enabled for the card
        "isPushEnabled": true, //True if push transactions are enabled for the card
        "cardExpirationDate": "202512", //Card expiration date
        "cardLast4": "1234" //Last 4 digits of the card number
    },
    "requestId": "b374bd00f33211eda84f56da8a8643b8"
}

400 (HTTP response statue code) -- Requested card was not found

{
    "requestId": "cc896a9083ae11ee9b7427220cc6c212",
    "code": "cardNotFound",
    "context": {
        "cFiCardId": "tcrd_4AKwFsr3faDq5PAbGKoDMS"
    },
    "message": "Card not found"
}

Back to Top

Push To Card

Request method and URL:

POST /transfer-to/card/push

Description:

This endpoint sends money from your settlement account to a registered external card. Such transfers typically happen within seconds. The required request body properties are "reference", "cFiCardId", "amount", "currency", and "narrative". A "softDescriptor" object property is optional.

The /transfer-to/card/push 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. For example, the following requests are not considered duplicates even though they are almost identical.

{
  "reference": "EXT_REFERENCE_ID1", //different reference IDS
  "cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
  "amount": 1.01, //same amount
  "currency": "USD",
  "narrative": "Both of these transactions will be posted.",
  "softDescriptor": {
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "PA",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    },
    "email": "merchant@sample.com"
  } 
}

{
  "reference": "EXT_REFERENCE_ID2", //different reference IDS
  "cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
  "amount": 1.01, //same amount
  "currency": "USD",
  "narrative": "Both of these transactions will be posted.",
  "softDescriptor": {
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "PA",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    },
    "email": "merchant@sample.com"
  } 
}
Properties Description Schema Example Values
reference An external alphanumeric reference ID (1-32 characters) for the transaction in your system (required) string, regex pattern: ^[0-9a-zA-Z]+$ "externalTrnId03"
cFiCardId The card ID (1-32 characters) in connectFi associated with the registered external card (required) string, regex pattern: ^[0-9a-zA-Z_]+$ "tcrd_5m41U6ycdgJ5CNyGDObY8Q"
amount The amount of the transaction (required) number > 0 1.01
currency A three character ISO alphabetic code to identify the type of currency (required) string, regex pattern: "^[A-Z]{3}$" "USD"
narrative Short description of transaction (required, max length: 22 characters) string, regex pattern: ^.{1,22}$ "For invoice #123"
softDescriptor Details of transaction recipient, (optional) object see softDescriptor Object

softDescriptor Object

Required Properties Description Schema Example Values
address Address of recipient object see Address Object in the Register an External Card section above
email Email of recipient string, regex pattern: "^(.+)@(.+)$" "merchant@sample.com"
name Name of recipient string, regex pattern: ^.{1,22}$ "Sample Merchant"
phone Phone number of recipient object see Phone Object in the Register an External Card section above

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
  "reference": "exrnl2TnId2562", //unique ID of the transaction in the client system 
  "cFiCardId": "tcrd_508IaE0NgrygZ2SSTJmYcw", //connectFi ID of the card
  "amount": 1.01,
  "currency": "USD",
  "narrative": "For invoice #123",
  "softDescriptor": { //optional
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Some Ave",
      "addressLine2": "Apt A123", //optional
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "#####", //a postal code (5-9 digits is typical for the US), ##### is used as a placeholder here for documentation purposes
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "##########" //a phone number (10 digits for the US), ########## is used as a placeholder here for documentation purposes
    },
    "email": "merchant@sample.com"
  }
}

Possible responses:

200 (HTTP response status code) -- Success pushing funds to an external card

{
    "code": "0", //Success
    "data": {
        "reference": "exrnl2TnId2562", //unique ID of the transaction in the client system
        "cFiTransactionId": "evolve_P09TgjZaadgTXH3DVQtcc", //transaction ID in the connectFi system
        "dtsCreatedAt": "2022-11-29T15:52:39.342Z", //date/time stamp when the transaction occurred
        "status": "Complete",  //status of the transaction ("Complete", "Declined", "Initiated", "Unknown", or "Manual")
        "network": "Visa", //network of the external card that was used for the transaction ("Visa", "Mastercard", "Amex", etc.)
        "networkRC": "00"
    },
    "requestId": "1b067390f33411eda84f56da8a8643b8"
}

400 (HTTP response status code) -- Incorrect input data:

{
    "requestId": "91209000f33511eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiCardId"
            },
            "message": "must have required property 'cFiCardId'"
        }
    ]
}

400 (HTTP response status code) -- Settlement account not found

{
    "requestId": "9794d220684c11ee8df9d847b134c812",
    "code": "toucanSettlementAccountNotFound",
    "context": {
        "cFiAggregatorId": "amplifi"
    },
    "message": "Aggregator doesn't have toucanSettlementAccount attribute."
}

400 (HTTP response status code) -- Transaction declined:

{
    "requestId": "a511e44083b011ee9b7427220cc6c212",
    "code": "extToucan",
    "context": {
        "status": "Declined",
        "cFiTransactionId": "evolve_51v5WDBwifZVf4rcai6DGq",
        "cFiAggregatorId": "evolve",
        "reference": "externalTrnId0369"
    },
    "message": "amount"
}

400 (HTTP response status code) -- The external reference ID used already exists

{
    "requestId": "4b044d8083b011ee9b7427220cc6c212",
    "code": "referenceExists",
    "context": {
        "reference": "exrnl2TnId25875",
        "entityId": "evolve_592DqjacOAhX41ssgrgTVU"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Card not found for pushing transaction

In this example, an incorrect cFiCardId was included in the request body.

{
    "requestId": "5b9b167083af11ee9b7427220cc6c212",
    "code": "cardNotFound",
    "context": {
        "cFiCardId": "tcrd_4AKwFsr3faDq5PAbGKoDMS"
    },
    "message": "Card not found"
}

Back to Top

Pull From Card

Request method and URL:

POST /transfer-to/card/pull

Description:

This endpoint transfers money from a registered external card to your settlement account. Such transfers typically happen within seconds. Similar to a push request, the required request body properties are "reference", "cFiCardId", "amount", "currency", and "narrative". A "softDescriptor" object property is optional. See the Push To Card description for a detailed look at these properties

The /transfer-to/card/pull 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. For example, the following requests are not considered duplicates even though they are almost identical.

{
  "reference": "EXT_REFERENCE_ID1", //different reference IDS
  "cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
  "amount": 1.01, //same amount
  "currency": "USD",
  "narrative": "Both of these transactions will be posted.",
  "softDescriptor": {
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "PA",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    },
    "email": "merchant@sample.com"
  } 
}

{
  "reference": "EXT_REFERENCE_ID2", //different reference IDS
  "cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
  "amount": 1.01, //same amount
  "currency": "USD",
  "narrative": "Both of these transactions will be posted.",
  "softDescriptor": {
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "PA",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    },
    "email": "merchant@sample.com"
  } 
}

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
  "reference": "externalTrnId31", //unique ID of the transaction in the client system 
  "cFiCardId": "1pO1AoWoSAyCdu21Xro8Ac", //connectFi ID of the card
  "amount": 1.01,
  "currency": "USD",
  "narrative": "For invoice #123",
  "softDescriptor": { //optional
    "name": "Sample Merchant",
    "address": {
      "addressLine1": "1346 Some Ave",
      "addressLine2": "Apt A123", //optional
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "#####", //a postal code (5-9 digits is typical for the US), ##### is used as a placeholder here for documentation purposes
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "##########" //a phone number (10 digits for the US), ########## is used as a placeholder here for documentation purposes
    },
    "email": "merchant@sample.com"
  } 
}

Possible responses:

200 (HTTP response status code) -- Success pulling funds from an external card

{
    "code": "0", //Success
    "data": {
        "reference": "externalTrnId31", //unique ID of the transaction in the client system
        "cFiTransactionId": "evolve_mOiVSm6blEl2LZ7EOaNok", //transaction ID in connectFi
        "dtsCreated": "2022-11-30T17:01:26.823Z",  //date/time stamp when the transaction was created
        "status": "Complete",  //status of the transaction ("Complete", "Declined", "Initiated", "Unknown", or "Manual")
        "network": "VISA", //network of the external card that was used for the transaction ("Visa", "Mastercard", "Amex", etc.)
        "networkRC": "00"
    },
    "requestId": "0c0fe290f33411eda84f56da8a8643b8"
}

400 (HTTP response status code) -- Incorrect input data:

{
    "requestId": "5adf7190f33611eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiCardId"
            },
            "message": "must have required property 'cFiCardId'"
        }
    ]
}

400 (HTTP response status code) -- Transaction declined:

{
    "requestId": "a511e44083b011ee9b7427220cc6c212",
    "code": "extToucan",
    "context": {
        "status": "Declined",
        "cFiTransactionId": "evolve_51v5WDBwifZVf4rcai6DGq",
        "cFiAggregatorId": "evolve",
        "reference": "externalTrnId0369"
    },
    "message": "amount"
}

400 (HTTP response status code) -- The external reference ID used already exists

{
    "requestId": "4b044d8083b011ee9b7427220cc6c212",
    "code": "referenceExists",
    "context": {
        "reference": "exrnl2TnId25875",
        "entityId": "evolve_592DqjacOAhX41ssgrgTVU"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Card not found for pulling transaction

In this example of a Bad Request, an incorrect cFiCardId was included in the request body.

{
    "requestId": "5b9b167083af11ee9b7427220cc6c212",
    "code": "cardNotFound",
    "context": {
        "cFiCardId": "tcrd_4AKwFsr3faDq5PAbGKoDMS"
    },
    "message": "Card not found"
}

Back to Top

Possible Transaction Status Values:

A transaction can have the following status values:

  • Complete - The transaction has been completed.
  • Declined - The transaction was declined.
  • Initiated - The transaction was initiated. Status updates to "Complete" or "Declined" within seconds.
  • Unknown or Manual - An unforeseen situation occurred. Contact support.

Back to Top

Query Card Transactions

Request method and URL:

POST /transfer-to/card/transactions-query

Description:

The status of up to 20 push/pull transactions may be requested at a time. The requested transactions are identified either by an array of connectFi transaction IDs ("cFiTransactionIds") or by an array of external system "references". The array that you include may not be an empty array.

The system will return only the push/pull 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 "amplifi-6UkLq66HEN6IMj4fNl6hgM" 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_2ocR89OfxphmuiKRO7EwrK", "evolve_6kWrOhwi3aAIxkvIAeklfO", "evolve_6zDmS9AnwgNIkkZj4v4d6M"]

OR

Required Properties Description Schema Example Values
references Array of external IDs from your system that you entered when initializing the push/pull transactions array ["externalTrnId31", "externalTrnId30"]

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example (using connectFi transaction IDs):

{
  "сFiTransactionIds": ["evolve_2ocR89OfxphmuiKRO7EwrK", "evolve_6kWrOhwi3aAIxkvIAeklfO", "evolve_6zDmS9AnwgNIkkZj4v4d6M"] //array of transaction IDs
}

Request body example (using external system references):

{
  "references": ["externalTrnId31", "externalTrnId30"] //array of external references
}

Possible responses:

200 (HTTP response status code) -- Success, requested transactions returned

{
    "code": "0", //Success
    "data": [
        {
            "reference": "externalTrnId31", //unique ID of the transaction in the client system
            "cFiTransactionId": "evolve_2ocR89OfxphmuiKRO7EwrK", //transaction ID in the connectFi system
            "dtsCreated": "2022-11-30T17:01:26.823Z", //date/time stamp when the transaction was created
            "status": "Complete", //status of the transaction ("Complete", "Declined", "Initiated", "Unknown", or "Manual")
            "network": "VISA", //network of the external card that was used for the transaction ("Visa", "Mastercard", "Amex", etc.),
            "networkRC": "00"
        },
        {
            "reference": "externalTrnId30", //unique ID of the transaction in the client system
            "cFiTransactionId": "evolve_6kWrOhwi3aAIxkvIAeklfO", //transaction ID in the connectFi system
            "dtsCreated": "2022-11-30T16:42:16.070Z", //date/time stamp when the transaction was created
            "status": "Complete", //status of the transaction ("Complete", "Declined", "Initiated", "Unknown", or "Manual")
            "network": "VISA", //network of the external card that was used for the transaction ("Visa", "Mastercard", "Amex", etc.)
            "networkRC": "00"
        }
    ],
    "requestId": "d02ae8d0f33611eda84f56da8a8643b8"
}

200 (HTTP response status code) -- Success, no transactions returned

In this example, no push/pull transactions were found that matched the requested cFiTransactionIds or references. This could result if the requested transaction IDs do not exist or if the requested transaction IDs are not push/pull transactions.

{
    "code": "0", //Success
    "data": [],
    "requestId": "07ee23508d1911ee876fa8dcb82ccc12"
}

400 (HTTP response status code) -- Must NOT have fewer than 1 items

In this example, the "cFiTransactionIds" array was empty. You must include between 1 and 20 cFiTransactionIds, inclusive (or external references). 

{
    "requestId": "f7323640f33611eda84f56da8a8643b8",
    "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 have required property '_____'

In this example, no cFiTransactionIds array or references array was present. You must include either the cFiTransactionIds array or the references array (but not both).

{
    "requestId": "04e87f10f33711eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiTransactionIds"
            },
            "message": "must have required property 'cFiTransactionIds'"
        },
        {
            "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"
        }
    ]
}

Back to Top

List Transactions

Request method and URL:

POST /transfer-to/card/list/transactions

Description:

This endpoint will list transactions that match the desired search criteria. Search criteria may be a date range, 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
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"
status The desired status for which to search, nullable string "Initiated", "Complete", "Declined", "Unknown", or "Manual"
reversalStatus The desired reversal status for which to search (only include if searching for reversal transactions), nullable string "Reversal", "Reversed" or "Unknown"
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 a date range)

{
    "dateCreateFrom": "2023-05-01T14:27:33.684Z",
    "dateCreateTo": "2023-05-12T14:27:33.684Z"
}

Request body (using reversalStatus)

{
    "reversalStatus": "Reversed"
}

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": 37, //maximum number of records requested (or number of transactions found, if less than maximum requested)
            "more": false //true if the number of records found is greater than the "numberOfRecords" requested
        },
        "items": [
            {
            "reerence": "exrnl2TnId25852", //external reference from your system
            "cFiTransactionId": "evolve_2yA5kJvgPdC64CpEvCJ1jS",//transaction ID in connectFi
            "dtsCreated": "2023-05-05T19:37:53.679Z", //date created
            "status": "Complete", //current transaction status
            "amount": 1.01,
            "currency": "USD" //currency code
            },
            {
                "reference": "exrnl2TnId25851", //external reference from your system
                "cFiTransactionId": "evolve_2s9uz78yMWHMfyVXk6kRgU",//transaction ID in connectFi
                "dtsCreated": "2023-05-05T19:37:47.963Z", //date created
                "status": "Complete", //current transaction status
                "amount": 14.23,
                "currency": "USD" //currency code
            },  
            //... rest of the transactions that were returned
        ]
    },
    "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": "959df07083b111ee9b7427220cc6c212",
    "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": "6403a060f33c11eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/status",
            "schemaPath": "#/properties/status/enum",
            "keyword": "enum",
            "params": {
                "allowedValues": [
                    "Unknown",
                    "Manual",
                    "Initiated",
                    "Complete",
                    "Declined"
                ]
            },
            "message": "must be equal to one of the allowed values"
        }
    ]
}

Back to Top

Reverse a Card Transaction

Request method and URL:

POST /transfer-to/card/reversal

Description:

This endpoint can be used to reverse a specified pull transaction. Reversals are only supported for pull transactions at this time.

Required Properties Description Schema Example Values
cFiTransactionId The transaction ID in the connectFi system String "evolve_62bM8Uu65vtwDxwPIyJMBa"

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
    "cFiTransactionId": "evolve_62bM8Uu65vtwDxwPIyJMBa" //transaction ID in the connectFi system
}

Possible responses:

200 (HTTP response status code) -- Success, transaction was reversed

{
    "code": "0", //Success
    "data": {
        "reference": "externalTrnId33", //unique ID of the transaction in the client system
        "cFiTransactionId": "evolve_62bM8Uu65vtwDxwPIyJMBa", //transaction ID in the connectFi system
        "dtsCreated": "2022-11-30T17:41:44.406Z", //date/time stamp when the transaction was created
        "status": "Complete", //status of the transaction ("Complete", "Declined", "Initiated", "Unknown", or "Manual")
        "network": "VISA", //network of the external card that was used for the transaction ("Visa", "Mastercard", "Amex", etc.)
        "networkRC": "00",
        "reversalStatus": "Reversed",//status of the reversal ("Reversed", "Reversal", or "Unknown")
        "reversal": {
            "networkRC": "00"
        }
    },
    "requestId": "86e48ef0f33711eda84f56da8a8643b8"
}

400 (HTTP response status code) -- Must have required property '______'

In this example, a required property was missing in the request body.

{
    "requestId": "37048f70f33711eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiTransactionId"
            },
            "message": "must have required property 'cFiTransactionId'"
        }
    ]
}

400 (HTTP response status code) -- The requested transaction was already reversed

In this example, a duplicate request for the same transaction reversal was attempted.

{
    "requestId": "fb49022083b111ee9b7427220cc6c212",
    "code": "toucanCannotReverseError",
    "context": {
        "cFiTransactionId": "evolve_4rbhvn8ehUFqyGjzkaxmme"
    },
    "message": "This transaction is already reversed (reversal)"
}

400 (HTTP response status code) -- Requested transaction was not found

{
    "requestId": "09893b7083b211ee9b7427220cc6c212",
    "code": "transactionNotFound",
    "context": {
        "cFiTransactionId": "evolve_4rbhvn8ehUFqyGjzkaxmmee"
    },
    "message": "Transaction not found."
}

400 (HTTP response status code) -- Reversals are only available for pull transactions

{
    "requestId": "289c3fd083b211ee9b7427220cc6c212",
    "code": "toucanCannotReverseError",
    "context": {
        "cFiTransactionId": "evolve_12EAbIPQ9t24OxKIBog2no"
    },
    "message": "Reversals are only available for pull transactions"
}

Back to Top

Possible Transaction Reversal Status Values (reversalStatus):

A transaction reversal can have the following status values:

  • Reversed - Transaction was reversed.
  • Reversal - Transaction was tried, however the status is unknown.
  • Unknown - Need to re-query the transaction

More information about reversal:

https://developers.tabapay.com/reference/retrieve-transaction-additional-reference

Back to Top