Register Card
Request URL
POST /acquiring/register
Description
The card data must be encrypted before being registered. For more information on encrypting card data see Encrypting Card Data.
Once the external card data is encrypted, this endpoint will register it in the connectFi database.
The /acquiring/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. The same card can be registered multiple times.
{
"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"
}
}
}
Schema
Property table for schema 1 for acquiring/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 acquiring/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": "extRefTCardId103",
"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": "extRefTCardId103",
"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}/acquiring/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/acquiring/register" --data "{ \"reference\":\"extRefTCardId103\", \"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 ACQUIRING/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": "5556667777"
}
}
}
RESPONSE BODY