Register Card
Request 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 same card can be registered multiple times.
Schema
Property table for schema 1 for transfer-to/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, "description": "common-reference" } |
Property table for schema 2 for transfer-to/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, "description": "common-reference" } |
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, "description": "common-commonStr500Req" } |
| keyId | The keyId matching the public key used during encryption | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
Property table for toucan address object
| Property | Description | Required | Schema |
|---|---|---|---|
| addressLine1 | addressLine1 | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| addressLine2 | addressLine2 | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "description": "common-commonStr50" } |
| city | city | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| state | state | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| postalCode | postalCode | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z-]+$", "minLength": 5, "maxLength": 10, "description": "customer-postalCode" } |
| country | country | Yes | { "type": "string", "pattern": "^[A-Z]{2}$", "description": "customer-countryCodeA2" } |
Property table for toucan cardHolderName object
| Property | Description | Required | Schema |
|---|---|---|---|
| first | first | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| last | last | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| middle | middle | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "description": "common-commonStr50" } |
| suffix | suffix | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "description": "common-commonStr50" } |
Property table for toucan clearCard object
| Property | Description | Required | Schema |
|---|---|---|---|
| accountNumber | The account number | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| expirationDate | expirationDate | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
Property table for toucan owner object
| Property | Description | Required | Schema |
|---|---|---|---|
| address | An object containing 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, "description": "common-commonStr50Req" } |
| number | number | Yes | { "type": "string", "pattern": "^[0-9]+$", "minLength": 10, "maxLength": 10 } |
Request Body
{
"reference": "externalCardId520",
"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": "4345156001"
}
}
}
Snippet Examples
javascript
const axios = require('axios');
const data = {
"reference": "externalCardId520",
"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": "4345156001"
}
}
};
const config = {
method: 'POST',
url: '${CONNECTFI_BASE_URL}/transfer-to/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/card/register" --data "{ \"reference\":\"externalCardId520\", \"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\":\"4345156001\" } }}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"
Successful Response Examples
200 TRANSFER-TO/CARD/REGISTER 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": "externalCardId09",
"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": "4345156001"
}
}
}
RESPONSE BODY