Register Card
Request URL
POST /transfer-to/combo/card/register
Description
To pull money from or push money to an external card, you need to register the card with connectFi first. The /transfer-to/combo/card/register endpoint requires that the card data be either encrypted or tokenized. For more information on tokenization, view the Getting Started > Tokenization section of the connectFi documentation.
One of either the "card" object or the "clearCard" object is required for the /transfer-to/combo/card/register endpoint. When the "card" object is utilized, encryption is required. You will need to concatenate and encrypt the card PAN (full 16-digit card number), expiration date and CVV. When the alternative "clearCard" object is included, then tokenization of sensitive card data is required.
Once the external card data is encrypted or tokenized, this endpoint will register it in the connectFi database.
The /transfer-to/combo/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": "5556667777"
}
}
}
{
"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": "5556667777"
}
}
}
The same card can be registered multiple times.
Schema
Property table for schema 1 for transfer-to/combo/card/register
| Property | Description | Required | Schema |
|---|---|---|---|
| card | An object containing card details | Yes | common card object |
| owner | An object containing owner details | Yes | toucan owner object |
| reference | An external alphanumeric reference ID for the entity in your system | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z]+$", "minLength": 1, "maxLength": 32, "$id": "common-reference" } |
Property table for schema 2 for transfer-to/combo/card/register
| Property | Description | Required | Schema |
|---|---|---|---|
| clearCard | An object containing unencrypted card details | Yes | toucan clearCard object |
| owner | An object containing owner details | Yes | toucan owner object |
| reference | An external alphanumeric reference ID for the entity in your system | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z]+$", "minLength": 1, "maxLength": 32, "$id": "common-reference" } |
Property table for toucan clearCard object
| Property | Description | Required | Schema |
|---|---|---|---|
| accountNumber | The account number | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| expirationDate | The expiration date | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| securityCode | The CVV security code | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
Property table for toucan owner object
| Property | Description | Required | Schema |
|---|---|---|---|
| address | Address details | Yes | toucan address object |
| name | Name | Yes | toucan cardHolderName object |
| phone | Phone | Yes | toucan phone object |
Property table for toucan phone object
| Property | Description | Required | Schema |
|---|---|---|---|
| countryCode | countryCode | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| number | Number | Yes | { "type": "string", "pattern": "^[0-9]+$", "minLength": 10, "maxLength": 10 } |
Property table for toucan cardHolderName object
| Property | Description | Required | Schema |
|---|---|---|---|
| first | First name | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| last | Last name | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| middle | Middle name | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "$id": "common-commonStr50" } |
| suffix | Suffix | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "$id": "common-commonStr50" } |
Property table for toucan address object
| Property | Description | Required | Schema |
|---|---|---|---|
| addressLine1 | Line 1 of the address | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| addressLine2 | Line 2 of the address | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "$id": "common-commonStr50" } |
| city | City | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| state | State | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
| postalCode | Postal code | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z-]+$", "minLength": 5, "maxLength": 10, "$id": "customer-postalCode" } |
| country | Country | Yes | { "type": "string", "pattern": "^[A-Z]{2}$", "$id": "customer-countryCodeA2" } |
Property table for common card object
| Property | Description | Required | Schema |
|---|---|---|---|
| encryptedData | A long encryption string | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 500, "isNotOnlyWhitespace": true, "$id": "common-commonStr500Req" } |
| keyId | The keyId matching the public key used during encryption | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
Request Body
{
"reference": "externalCardId101",
"card": {
"encryptedData": "Snbx7y1UUwOjJ44jUA0OjHWz184mpK5dqaHGGHzQML7_d6FolgQ25VEq4UusvmSSMCziNF8h7wq2GjzJXMO3YghuuYqIw_2VvObd0TevFnjfFGL30qMM8GY2Q6BzRuXRdHMuy6qT4SPypJnDXbleHeEvjtzGSZ5zLlYp9BboyKU0oFGmT0P-_j4TQ2AHSnOF17bM5AZGkdKBzNBTLREKbMKev5ZF6ot1oAoeau9EldgOs74vBiKhGoUKSIbJl5E9cOXUmWCrUriblStRQkA-JSUEhkuZnReOEM83VEeVvaHYVtcxXydpIo55ecPg6EOTMlO41UDu3dExos0ssOVSUg",
"keyId": "je87i6-C2QJS7PHUAbJPqw"
},
"owner": {
"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": "5556667777"
}
}
}
Snippet Examples
javascript
const axios = require('axios');
const data = {
"reference": "externalCardId101",
"card": {
"encryptedData": "Snbx7y1UUwOjJ44jUA0OjHWz184mpK5dqaHGGHzQML7_d6FolgQ25VEq4UusvmSSMCziNF8h7wq2GjzJXMO3YghuuYqIw_2VvObd0TevFnjfFGL30qMM8GY2Q6BzRuXRdHMuy6qT4SPypJnDXbleHeEvjtzGSZ5zLlYp9BboyKU0oFGmT0P-_j4TQ2AHSnOF17bM5AZGkdKBzNBTLREKbMKev5ZF6ot1oAoeau9EldgOs74vBiKhGoUKSIbJl5E9cOXUmWCrUriblStRQkA-JSUEhkuZnReOEM83VEeVvaHYVtcxXydpIo55ecPg6EOTMlO41UDu3dExos0ssOVSUg",
"keyId": "je87i6-C2QJS7PHUAbJPqw"
},
"owner": {
"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": "5556667777"
}
}
};
const config = {
method: 'POST',
url: '${CONNECTFI_BASE_URL}/transfer-to/combo/card/register',
headers: {
'Content-Type': "application/json",
'x-connectfi-token': "A long random string token received from /auth/get-token request"
},
data
};
let result;
try {
result = await axios.request(config);
if (result.status === 200) {
console.log(JSON.stringify(result.data));
}
} catch (err) {
console.log({
errCode: err.code,
responseStatus: err.response && err.response.status,
data: err.response && JSON.stringify(err.response.data)
});
}
cURL
curl --location "CONNECTFI_BASE_URL/transfer-to/combo/card/register" --data "{ \"reference\":\"externalCardId101\", \"card\":{ \"encryptedData\":\"Snbx7y1UUwOjJ44jUA0OjHWz184mpK5dqaHGGHzQML7_d6FolgQ25VEq4UusvmSSMCziNF8h7wq2GjzJXMO3YghuuYqIw_2VvObd0TevFnjfFGL30qMM8GY2Q6BzRuXRdHMuy6qT4SPypJnDXbleHeEvjtzGSZ5zLlYp9BboyKU0oFGmT0P-_j4TQ2AHSnOF17bM5AZGkdKBzNBTLREKbMKev5ZF6ot1oAoeau9EldgOs74vBiKhGoUKSIbJl5E9cOXUmWCrUriblStRQkA-JSUEhkuZnReOEM83VEeVvaHYVtcxXydpIo55ecPg6EOTMlO41UDu3dExos0ssOVSUg\", \"keyId\":\"je87i6-C2QJS7PHUAbJPqw\" }, \"owner\":{ \"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\":\"5556667777\" } }}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"
Successful Response Examples
200 SUCCESSFUL RESPONSE
HEADERS
| Header | Value |
|---|---|
| Content-Type | application/json |
| x-connectfi-token | A long random string token received from /auth/get-token request |
REQUEST BODY
{
"reference": "externalCardId55",
"card": {
"encryptedData": "Snbx7y1UUwOjJ44jUA0OjHWz184mpK5dqaHGGHzQML7_d6FolgQ25VEq4UusvmSSMCziNF8h7wq2GjzJXMO3YghuuYqIw_2VvObd0TevFnjfFGL30qMM8GY2Q6BzRuXRdHMuy6qT4SPypJnDXbleHeEvjtzGSZ5zLlYp9BboyKU0oFGmT0P-_j4TQ2AHSnOF17bM5AZGkdKBzNBTLREKbMKev5ZF6ot1oAoeau9EldgOs74vBiKhGoUKSIbJl5E9cOXUmWCrUriblStRQkA-JSUEhkuZnReOEM83VEeVvaHYVtcxXydpIo55ecPg6EOTMlO41UDu3dExos0ssOVSUg",
"keyId": "je87i6-C2QJS7PHUAbJPqw"
},
"owner": {
"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": "5556667777"
}
}
}
RESPONSE BODY