Register Card
Request URL
POST /acquiring/register
Description
The card data must be encrypted or tokenized before being registered. For more information on encrypting card data see Encrypting Card Data. For more information on tokenization of card data see Getting Started > Tokenization.
Once the external card data is encrypted or tokenized, this endpoint will register it in the connectFi database. If using encryption, then the "card" object will be included in the request. If using tokenization, then the alternative "clearCard" object will be included in the request.
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, "$id": "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, "$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": "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 SUCCESSFUL RESPONSE - ENCRYPTION
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
{
"code": "0",
"data": {
"cFiCardId": "1BpOVitG1ADj5bYwJijI00",
"dtsRegistered": "2023-03-31T20:11:22.103Z",
"reference": "externalCardId09",
"isPullEnabled": true,
"isPushEnabled": true,
"cardExpirationDate": "202512",
"cardLast4": "9990"
},
"requestId": "338ed710d00011ed855ac5641e003b98"
}
200 SUCCESSFUL RESPONSE - TOKENIZATION
HEADERS
| Header | Value |
|---|---|
| Content-Type | application/json |
| x-connectfi-token | A long random string token received from /auth/get-token request |
REQUEST BODY
{
"reference": "externalCardId521",
"clearCard": {
"accountNumber": "1234567890123456", //must be tokenized
"expirationDate": "202610", //must be tokenized
"securityCode": "123" //must be tokenized
},
"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