Card Holder API Tokens

Performing sensitive card actions like showing card details or managing pin requires two-factor authentication. For individual customers, the cardholder is the customer themselves, so using the customer token is sufficient. For business customers, where the cardholder may not necessarily be the business contact, you should use cardholder token. This token will allow you to provide access to one specific card for the person owning it.

Create Cardholder Token

Create a bearer token for a particular card.

A Cardholder Token can only interact with one card.

note

When using a Cardholder Bearer Token, API calls should be made directly from your front-end (browser or app).

Verb	POST
Url	https://api.s.unit.sh/cards/:cardId/card-holder/token
Required Scope	cards-write
Data Type	cardHolderToken
Timeout (Seconds)	5

Example Request (two-factor authentication not required):

curl -X POST 'https://api.s.unit.sh/cards/123/card-holder/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "cardHolderToken",
    "attributes": {
      "scope": "cards"
    }
  }
}'

Attributes

Name	Type	Description
scope	string	list of Scopes separated by spaces. Only cards (cards cards-sensitive cards-write cards-sensitive-write) scopes are allowed.
verificationToken	string	Required if scope includes a scope which require two-factor authentication. Received as a response from Create Cardholder Token Verification.
verificationCode	string	Required if the scope attribute includes a scope which requires two-factor authentication. 6 digits code sent to the card holder through the desired channel.
expiresIn	integer	Optional. The lifetime of the token (in seconds). Maximum value is 86400 (24 hours). Default value is also 24 hours.
upgradableScope	string	Optional. list of Scopes separated by spaces. The card holder will be able to upgrade the token to the scopes you provide here.

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data.attributes.token	string	The token issued for the card.
data.attributes.expiresIn	integer	The lifetime of the token (in seconds).

Example Response:

{
  "data": {
    "type": "cardHolderBearerToken",
    "attributes": {
      "token": "v2.public.eyJyb2xlIjoiY3VzdG9tZX...",
      "expiresIn": 86400
    }
  }
}

Create Cardholder Token Verification

When creating a cardholder token that contains a scope which requires two-factor authentication (see Scopes), it is required to first create a verification challenge that will be sent to the customer.

The challenge is a six digits code and is valid for 10 minutes after its creation.

note

The phone number that is used for the verification process is the one defined for the cards whose identifier is provided as part of the request params. An alternative phone number (authorized user / business contact) can be provided for Business Customers via the phone attribute (see below).

note

In Sandbox, Unit will not send a text message, in order to avoid breaching the electronic communications consent requirements. In order to create a card holder token that has access to scopes that require two factor authentication, please use the passcode 000001

info

The rate limit for verifying a customer is 5 attempts per 10 minutes.

Verb	POST
Url	https://api.s.unit.sh/cards/:cardId/card-holder/token/verification
Data Type	cardHolderTokenVerification
Timeout (Seconds)	5

Attributes

Name	Type	Description
channel	string	Send a verification code to the card holder through one of the following channels - sms or call.
phone	Phone	Optional. This allows providing the phone number of one of the customer's

authorized users. The provided phone must match an authorized user phone and will be used in the One Time Password (OTP) authentication process instead of the business customer contact's phone. appHash | string | Optional. For sms verifications only, 11-character hash string that identifies your app. Appended at the end of your verification SMS body the way that client-side SMS Retriever API expects. language | string | Optional. Select the verification language using a 2-letters code.
Default is English.
See Localization Options bellow for the support languages and their 2-letters code.

Create a cardholder verification:

curl -X POST 'https://api.s.unit.sh/cards/123/card-holder/token/verification'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "cardHolderTokenVerification",
    "attributes": {
      "channel": "sms"
    }
  }
}'

201 Created

Field	Type	Description
verificationToken	string	The generated verification token. It should be passed back to Create Cardholder Bearer Token along with the verification code the customer received on the specified channel

Localization Options

English-en, Afrikaans-af, Arabic-ar, Catalan-ca, Chinese-zh, Chinese (Mandarin)-zh-CN, Chinese (Cantonese)-zh-HK, Croatian-hr, Czech-cs, Danish-da, Dutch-nl, English (British)-en-GB, Estonian-et, Finnish-fi, French-fr, German-de, Greek-el, Hebrew-he, Hindi-hi, Hungarian-hu, Indonesian-id, Italian-it, Japanese-ja, Kannada-kn, Korean-ko, Malay-ms, Marathi-mr, Norwegian-nb, Polish-pl, Portuguese - Brazil-pt-BR, Portuguese-pt, Romanian-ro, Russian-ru, Slovak-sk, Spanish-es, Swedish-sv, Tagalog-tl, Telegu-te, Thai-th, Turkish-tr, Vietnamese-vi

Example Response:

{
  "data": {
    "type": "cardHolderTokenVerification",
    "attributes": {
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm...."
    }
  }
}