Div

class	developer-cookbook-inner-page-title

HTML Table

class	tagline-page-title

Table Row (tr)

Table Cell (td)

class	title-text

Learn how you can use the Cipher APIs and then build your own Two Factor Authentication (2FA).

Find out how Cipher REST APIs can be integrated into the Card Management System (CMS) or other such systems to trigger updates on Cipher System. Find out Cipher Offering here.

In this article, you will learn how to use the Cipher APIs and then build your own Two Factor Authentication (2FA).

Create Card

This endpoint allows you to enroll cards for authentication using the cardholder’s challengeable identities. The API supports enrollment using the following card schemes:

15/16-digit card PAN
SHA256 of the card

Endpoint URI

Status

colour	Green
title	Post

/tenants/{tenantId}/cards

Request details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Request parameters

Div

class	tabsmenu_2

Request sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter	Description
Body parameters
`name` String, Required	Name of the cardholder.
`cardInfo/scheme` String, Required	Type of schemes to enroll cards in Cipher: DEFAULT: Enroll cards using the 15/16-digit card PAN. SHA256: Enroll cards using the SHA256 (hashing function) of the card and a masked card PAN. The masked card PAN in the 6x4 masked format (with unmasked first 6 digits and last 4 digits). This is needed for product identification, BIN mapping and display purposes.
`cardInfo/cardNumber` Integer, Required	A 15/16-digit number on the payment card.
`identities/type` String,

Optional

Required

Type of identity challenged to authenticate the cardholder. Supported types:

phone number: Enroll the card with the phone number of the

card holder

cardholder for authentication.
email: Enroll the card with the email id of the cardholder for authentication.
tenantUniqueVector:

Map the

An unique identity generated by the tenant. This used to map the card to an authProfile and to authenticate the SDK usage.
Note
tenantUniqueVector is mandatory. Choose other identity types based on the authPlans you configure for your cardholders.

identities/value

String, Optional

Value of the specified identity type.

state

String, Optional

Desired state of a card.

ENABLED: card can be used for authentications.
DISABLED: card remains enrolled but gets disabled for authentication. The authentication requests arriving for this card will fail with CARD_NOT_FOUND reason code.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
	"name" : "Foo BarAmit",
    	"cardInfo" : {
		"scheme" : "DEFAULT",
		"cardNumber" : "1111118447391721112228948763895"
	},
    	"identities" : [
		{
			"type" : "tenantUniqueVectorphoneNumber",
			"value" : "990011223+918948763892"
		},
		{
			"type" : "phoneNumbertenantUniqueVector",
			"value" : "+919999999999D7480"
		},
		{
			"type" :  ]"email",
			"value" : "amit@zeta.tech"
		}
	],
	"state" : "ENABLED"
}

Response details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Response parameters

Div

class	tabsmenu_2

Response sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter	Description
`cardId`

Integer

String	The card reference ID generated on the Cipher system.
`cardGuid` String	Card Globally Unique Identifier. In Cipher, whenever a card is enrolled , at Zeta an alias is created for it called `cardGuid`.
`name` String	Name of the cardholder.
`tenantId` Integer	ID of the tenant generated on the Cipher system.
`productId`

Integer

String

ID of the product generated on the Cipher system.

productName

String

Name of the product generated on the Cipher system.

authProfileId

Integer

String

The authProfileId generated on the Cipher system for the card holder.

If you enroll multiple cards with the same tenantUniqueVector value, ensure that the values for other identity types should match exactly for authentication.
The enrollment call will fail if you pass same tenantUniqueVector value (already used for other card) and different value for other identities.

cardNumber

Integer

String	A 15/16-digit number on the payment card.
`cardNetwork` String	Type of network used to manage payments. Examples: Visa and Mastercard.
`state` String	Desired state of a card. ENABLED: card can be used for authentications. DISABLED: card remains enrolled but gets disabled for authentication. The authentication requests arriving for this card will fail with `CARD_NOT_FOUND` reason code.
`identities/type` String	Type of identity challenged to authenticate the cardholder. Supported types: cardGuid: Map the card to `cardGuid`.

tenantUniqueVector: Map the card to an authProfile and to authenticate the SDK usage.

phone number: Enroll the card with the phone number of the

card holder

cardholder for authentication.
tenantUniqueVector: An unique identity generated by the tenant. This used to map the card to an authProfile and to authenticate the SDK usage.

Note
`tenantUniqueVector` is mandatory. Choose other identity types based on the `authPlans` you configure for your cardholders.

identities/value

String

A value for a given type of identity used to authenticate the cardholder.

identities/state

String

Desired state of the identity for authentication.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
    "cardId": "CRN0000000050",
    "cardGuid": "5f90a3d8-8b59-441f-95cd-2e1b3fb680ee",
    "name": "Foo Bar",
    "tenantId": "900912",
    "productId": "PRO00103",
    "productName": "My Amex Product",
    "authProfileId": "_aP56QPq1U03wFTq_lNBqg==",
    "cardNumber": "111111xxxxxx172",
    "cardNetwork": "amex",
    "state": "ENABLED",
    "identities": [
        {
            "type": "cardGuid",
            "value": "5f90a3d8-8b59-441f-95cd-2e1b3fb680ef",
            "state": "ENABLED"
        },
        {
            "type": "tenantUniqueVector",
            "value": "990011223",
            "state": "ENABLED"
        },
        {
            "type": "phoneNumber",
            "value": "+919999999999",
            "state": "ENABLED"
        }
    ]
}

Update Card

This endpoint allows you to enable or disable a card using its cardId.

Endpoint URI

Status

title	Patch

/tenants/{tenantId}/cards/{cardId}

Request details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Request parameters

Div

class	tabsmenu_2

Request sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

Body parameters

state

String, Required

Desired state of a card.

ENABLED: card can be used for authentications.
DISABLED: card remains enrolled but gets disabled for authentication. The authentication requests arriving for this card will fail with CARD_NOT_FOUND reason code.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
	"state":"DISABLED"
}

Response details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Response parameters

Div

class	tabsmenu_2

Response sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter	Description
`cardId`

Integer

String	The card reference ID generated on the Cipher system.
`cardGuid` String	Card Globally Unique Identifier. In Cipher, whenever a card is enrolled , at Zeta an alias is created for it called `cardGuid`.
`name` String	Name of the cardholder.
`tenantId` Integer	ID of the tenant generated on the Cipher system.
`productId`

Integer

String	ID of the product generated on the Cipher system.
`productName`

Integer

String	Name of the product generated on the Cipher system
`authProfileId`

Integer

String

The authProfileId generated on the Cipher system for the card holder.

If you enroll multiple cards with the same tenantUniqueVector value, ensure that the values for other identity types should match exactly for authentication.
The enrollment call will fail if you pass same tenantUniqueVector value (already used for other card) and different value for other identities.

cardNumber

Integer

String	A 15/16-digit number on the payment card.
`cardNetwork`

Integer

String

Type of network used to manage payments between card issuing banks and merchant banks. Examples: Visa and Mastercard.

identities/type

String

Type of identity challenged to authenticate the cardholder. Supported types:

cardGuid: Map the card tocardGuid.

tenantUniqueVector: Map the card to an authProfile and to authenticate the SDK usage.

phone number: Enroll the card with the phone number of the

card holder

cardholder for authentication.
tenantUniqueVector: An unique identity generated by the tenant. This used to map the card to an authProfile and to authenticate the SDK usage.

Note
`tenantUniqueVector` is mandatory. Choose other identity types based on the `authPlans` you configure for your cardholders.

identities/value

String

A value for a given type of identity used to authenticate the cardholder.

state

String

Desired state of the identity for authentication.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
    "cardId": "CRN0000000050",
    "cardGuid": "5f90a3d8-8b59-441f-95cd-2e1b3fb680ee",
    "name": "Foo Bar",
    "tenantId": "900912",
    "productId": "PRO00103",
    "productName": "My Amex Product",
    "authProfileId": "_aP56QPq1U03wFTq_lNBqg==",
    "cardNumber": "111111xxxxxx172",
    "cardNetwork": "amex",
    "state": "DISABLED",
    "identities": [
        {
            "type": "cardGuid",
            "value": "5f90a3d8-8b59-441f-95cd-2e1b3fb680ef",
            "state": "ENABLED"
        },
        {
            "type": "tenantUniqueVector",
            "value": "990011223",
            "state": "ENABLED"
        },
        {
            "type": "phoneNumber",
            "value": "+919999999999",
            "state": "ENABLED"
        }
    ]
}

Get Tenant

This endpoint allows you to retrieve details of a tenant. A tenant is an organization or financial institute on-boarded with Zeta.

Endpoint URI

Status

colour	Blue
title	GET

/tenants/{tenantId}

Request details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Request parameters

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

Query parameters

tenantId

Integer, Required

ID of the tenant generated on the Cipher system.

Response details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Response parameters

Div

class	tabsmenu_2

Response sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

tenantId

Integer

ID of the tenant generated on the Cipher system.

name

String

Name of the tenant. A tenant is an organization or financial institute on-boarded with Zeta.

config

String

Configurations for look and feel of the authentication page.

gaID: ID of google analytics. It allows us to use Google analytics to measure various things.
logoURL: An URL path to the desired logo on the authentication page.
templateConfig: It is a JSON object which contains default config for how the authentication page should look like for a cardholder.
challengeConfig: It is a JSON object which contains default config for challenges. Examples: resend challenge limit and retrial challenge limit.
authExpiryInSeconds: Time after which an authentication session expires.

state

String

Desired state of a card.

ENABLED: card can be used for authentications.
DISABLED: card remains enrolled but gets disabled for authentication. The authentication requests arriving for this card will fail with CARD_NOT_FOUND reason code.

authPlans

String

A collection of authentication plans that are available to choose from for configuring the authentication experience of the cardholder . Currently,

we support

the Cipher system supports single factor authentication plans like SMS_OTP, email_OTP, and Super PIN.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
    "tenantId": "900912",
    "name": "HDFC",
    "config": {
        "gaID": "ga_id_amzn_fstv",
        "logoURL": "https://sample.svg",
        "templateConfig": {
            "bannerBgColor": "#ebebeb",
            "linkTextColor": "#7d52cd",
            "activeBtnColor": "#7d52cd",
            "bannerTextColor": "#222",
            "disabledBtnColor": "#cfcfcf",
            "primaryTextColor": "#222",
            "secondaryTextColor": "#030303"
        },
        "challengeConfig": {
            "resendOTPLimit": 3,
            "incorrectChallengeAttemptLimit": 2
        },
        "authExpiryInSeconds": 300
    },
    "state": "ENABLED",
    "authPlans": [
        {
            "authPlanId": 1,
            "factors": [
                {
                    "factorNumber": 1,
                    "identities": [
                        {
                            "identityType": "phoneNumber"
                        }
                    ]
                }
            ]
        }
    ]
}

Get CardHolder

This endpoint allows you to fetch the enrollment details of a cardholder, including the identity types.

Endpoint URI

Status

colour	Blue
title	GET

/tenants/{tenantId}/cardHolders/{cardHolderId}

Request details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Request parameters

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

Query parameters

tenantId

Integer, Required

ID of the tenant generated on the Cipher system.

cardHolderId

String, Required

ID of the cardholder generated in the Cipher system. The cardHolderID is received in response of the Create Card API.

Response details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Response parameters

Div

class	tabsmenu_2

Response sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

cardHolderId

String

ID of the cardholder for whom the enrollment details are being fetched.

name

String

Name of the tenant. A tenant is an organization or financial institute on-boarded with Zeta.

tenantId

Integer

ID of the tenant generated on the Cipher system.

identities/type

String

Type of identity challenged to authenticate the cardholder. Supported types:

cardGuid: Map the card to cardGuid.
phone number: Enroll the card with the phone number of the cardholder for authentication.
tenantUniqueVector: An unique identity generated by the tenant. This used to map the card to an authProfile and to authenticate the SDK usage.

Note
`tenantUniqueVector` is mandatory. Choose other identity types based on the `authPlans` you configure for your cardholders.

identities/value

String

A value for a given type of identity used to authenticate the cardholder.

cardId

String

The card reference ID generated on the Cipher system.

cardGuid

String

Card Globally Unique Identifier. In Cipher, whenever a card is enrolled, at Zeta an alias is created for it called cardGuid.

productId

String

ID of the product generated on the Cipher system.

productName

String

Name of the product generated on the Cipher system

maskedcardNumber

String

The masked 15/16-digit number on the payment card.

cardNetwork

String

Type of network used to manage payments. Examples: Visa and Mastercard.

state

String

Desired state of a card.

ENABLED: card can be used for authentications.
DISABLED: card remains enrolled but gets disabled for authentication. The authentication requests arriving for this card will fail with CARD_NOT_FOUND reason code.

disabledReason

String

A reason provided when the card of the cardholder is blocked.

config

String

Attributes (in key, value pair) attached to the card.

createdBy

String

This is required for auditing purposes. It consists of following two fields:

actorJID belongs to the entity who performed this action.
Allowed format: <authProfileID>@authProfile.<domainID>/<resourceID>
Allowed mode: API/FILE/UI.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
  "cardHolderId": "kasdjnaskdjnalskn==",
   "name": "Foo Bar",
   "tenantId": "900912",
  "identities": [
     {
       "type": "phoneNumber",
       "value": "+918948763892"
     },
    {
       "type": "email",
       "value": "test@example.com"
     },
    {
       "type": "tenantUniqueVector",
       "value": "D740"
     }
               ],
               "cards": [
                  {
        "cardId": "CRN0000000050",
        "cardGuid": "5f90a3d8-8b59-441f-95cd-2e1b3fb680ee",
        "productId": "PRO00103",
        "productName": "My Amex Product",
        "maskedCardNumber": "111111xxxxxx172",
        "cardNetwork": "amex",
        "state": "ENABLED",
        "disabledReason": "",
        "config": {“key”: “value”, “key1”: “value1”},
        "createdBy": { 
"actorJid":"VcEupC_Vw0XUhTMPfvCi2A==@authProfile.160683.admin/2", 
"mode": "API" 
}
     }
               ]
}

Update CardHolder

This endpoint allows you to update the identities of a cardholder. Currently, the Cipher system supports identities such as phone numbers and email. You can update any one or both identities at a time. You can use the identity in a challenge verification only if it is enabled in your product.

Endpoint URI

Status

title	Patch

/tenants/{tenantId}/cardHolders/{cardHolderId}/identities

Request details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Request parameters

Div

class	tabsmenu_2

Request sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

Query parameters

tenantId

Integer, Required

ID of the tenant generated on the Cipher system.

cardHolderId

String, Required

ID of the cardholder generated in the Cipher system. The cardHolderID is received in response of the Create Card API.

Body Parameters

identitiesInfo/type

String, Required

Type of identity to be updated.
Currently, the Cipher system supports phone numbers and email.

Note
At least one type of identity should be specified. If both identity types are specified, this API updates both. If an identity type does not exist for this cardholder, this API will add the identity type.

identitiesInfo/value

String, Required

New value of the identity.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
    "identitiesInfo": [
      {
        "type": "phoneNumber",
        "value": "+918948763892"
      },
      {
        "type": "email",
        "value": "test@example.com"
      }
    ]
}

Response details

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Response parameters

Div

class	tabsmenu_2

Response sample

Div

class	tabscontent

Div

class	tabpage_1

Parameter Description

cardHolderId

String

ID of the cardholder for which the identities are being updated in the Cipher system.

identities

String

An updated list is received with all identities of the cardholder.

Div

class	tabpage_2

Code Block

language	js
theme	Midnight
linenumbers	true

{
  "cardHolderId": "kasdjnaskdjnalskn==",
  "identities": [
     {
       "type": "phoneNumber",
       "value": "+918948763892"
     },
    {
       "type": "email",
       "value": "test@example.com"
     }
               ]
}

Error codes

This section explains the various error codes thrown by Cipher APIs.

The sample error response below shows server-side error code and message returned in case of any error:

Code Block

language	js
theme	Midnight
linenumbers	true

{
    "code": "ER001",
    "message": "Bad request",
    "debugId": "9551a715-79d4-4b64-a3d8-11efe7610baf"
}

The following table lists the error codes, descriptions and possible solutions. If the issue persists, contact Zeta.

Error Code	Error Message	HTTP Status
`ER000`	Unexpected server error occurred	500
`ER001`	Bad request	400
`ER002`	Conflicting input	409
`ER003`	Resource not found	404
`ER004`	Unauthorized action	401

Panel

Div

class	alignLeftIcon

On this page:

Table of Contents

maxLevel	2

Div

class	help-box

Need Help?

Drop a mail at fusion-support@zeta.tech or call us on 080-6690 5995.

Page tree

Versions Compared

Old Version 8

New Version 9

Key

Create Card

Endpoint URI

Request details

Response details

Update Card

Endpoint URI

Request details

Response details

Get Tenant

Endpoint URI

Request details

Response details

Get CardHolder

Endpoint URI

Request details

Response details

Update CardHolder

Endpoint URI

Request details

Response details

Error codes

Page tree

Page History

Versions Compared

Old Version 8

New Version 9

Key

Create Card

Endpoint URI

Request details

Response details

Update Card

Endpoint URI

Request details

Response details

Get Tenant

Endpoint URI

Request details

Response details

Get CardHolder

Endpoint URI

Request details

Response details

Update CardHolder

Endpoint URI

Request details

Response details

Error codes