Skip to content

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

{
    "code": "0",
    "data": {
        "cFiCardId": "tcrd_16w5vwEiPBDBXRHb7fF0Bk",
        "dtsRegistered": "2024-07-16T11:11:25.677Z",
        "reference": "externalCardId521",
        "isPullEnabled": true,
        "isPushEnabled": true,
        "cardExpirationDate": "202610",
        "cardLast4": "3456"
    },
    "requestId": "237a1a50436411efa55c1a4fb7d8f612"
}