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 along with the cardholder’s identification information and challengeable identities. The API supports enrollment using either of the following enrollment options:

using the 15/16-digit card PAN
using the SHA256 of the card

Endpoint URI

POST	/tenants/{tenantId}/cards

Request details

Request parameters

Request sample

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 card PAN. This field is mandatory when cardInfo.scheme is DEFAULT.

cardInfo/cardNumberSha

String, Required

The base64 encoded SHA256 of the card PAN.

cardInfo/maskedcardNumber

String, Required

The masked card PAN in the 6x4 masked format with unmasked first 6 digits and last 4 digits.
This is needed for the following reasons:

Product identification
Bin mapping
Display purposes

identities/type

String, Required

Type of identity challenged to authenticate the cardholder. Supported types are phone number, email and tenantUniqueVector:

phone number: Used to enroll the card with the phone number of the cardholder for authentication.
email: Used to enroll the card with the email id of the cardholder for authentication.
tenantUniqueVector: An unique identifier of the cardholder generated by the tenant. This is used to map the card to a cardholder and to authenticate the usage of SDK by this cardholder.

tenantUniqueVector is mandatory. Choose other identity types (phoneNumber and/or email) based on the authPlans you configure for your cardholders.
The tenantUniqueVectorID is verified by the Cipher system (using the authentication token given by the host app) while authenticating the SDK during registration.

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.

{
	"name" : "Amit",
	"cardInfo" : {
		"scheme" : "DEFAULT",
		"cardNumber" : "1112228948763895"
	},
	"identities" : [
		{
			"type" : "phoneNumber",
			"value" : "+918948763892"
		},
		{
			"type" : "tenantUniqueVector",
			"value" : "D7480"
		},
		{
			"type" : "email",
			"value" : "amit@zeta.tech"
		}
	],
	"state" : "ENABLED"
}

Response details

Response parameters

Response sample

Parameter Description

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.

name

String

Name of the cardholder.

tenantId

Integer

ID of the tenant generated on the Cipher system.

productId

String

ID of the product generated on the Cipher system.

productName

String

Name of the product generated on the Cipher system.

cardHolderId

String

ID of the cardholder generated in the Cipher system.

If more than one card is enrolled with the same value for tenantUniqueVector, the values for other identity types should match exactly. The enrollment call fails if more than one card is enrolled with the same value for tenantUniqueVector but the values for other identities differ.

authProfileId

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

String

A 15/16-digit card PAN. This field is mandatory when cardInfo.scheme is DEFAULT.

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 are phone number, email and tenantUniqueVector:

phone number: Used to enroll the card with the phone number of the cardholder for authentication.
email: Used to enroll the card with the email id of the cardholder for authentication.
tenantUniqueVector: An unique identifier of the cardholder generated by the tenant. This is used to map the card to a cardholder and to authenticate the usage of SDK by this cardholder.

tenantUniqueVector is mandatory. Choose other identity types (phoneNumber and/or email) based on the authPlans you configure for your cardholders.
The tenantUniqueVectorID is verified by the Cipher system (using the authentication token given by the host app) while authenticating the SDK during registration.

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.

{
    "cardId": "CRN0000059516",
    "cardGuid": "9425de25-d15c-49e8-a707-ad618df72e96",
    "name": "Name",
    "tenantId": "296793",
    "productId": "PRO00001",
    "productName": "First Product Updated",
    "cardHolderId": "fiWjynqJVV3pKDDCHV5HLQ==",
    "authProfileId": "fiWjynqJVV3pKDDCHV5HLQ==",
    "cardNumber": "123456xxxxxx8848",
    "cardNetwork": "rupay",
    "state": "ENABLED",
    "identities": [
        {
            "type": "phoneNumber",
            "value": "+919876548765",
            "state": "ENABLED"
        },
        {
            "type": "tenantUniqueVector",
            "value": "Drio",
            "state": "ENABLED"
        },
        {
            "type": "email",
            "value": "test@zeta.tech",
            "state": "ENABLED",
            "createdAt": "2020-07-21T11:53:02.652+0000"
        },
        {
            "type": "cardGuid",
            "value": "9425de25-d15c-49e8-a707-ad618df72e96",
            "state": "ENABLED"
        }
    ],
    "createdBy": {
        "actorJid": "yAUnv4Zwxtiyq-KMl4ZTOQ==@authProfile.296793.admin/29",
        "mode": "API"
    }
}

Update Card

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

Endpoint URI

PATCH

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

Request details

Request parameters

Request sample

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.

{
	"state":"DISABLED"
}

Response details

Response parameters

Response sample

Parameter	Description
`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`.
`name` String	Name of the cardholder.
`tenantId` Integer	ID of the tenant generated on the Cipher system.
`productId` String	ID of the product generated on the Cipher system.
`productName` String	Name of the product generated on the Cipher system
`authProfileId` 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` String	A 15/16-digit card PAN. This field is mandatory when `cardInfo.scheme` is DEFAULT.
`cardNetwork` 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 are phone number, email and tenantUniqueVector: phone number: Used to enroll the card with the phone number of the cardholder for authentication. email: Used to enroll the card with the email id of the cardholder for authentication. tenantUniqueVector: An unique identifier of the cardholder generated by the tenant. This is used to map the card to a cardholder and to authenticate the usage of SDK by this cardholder. `tenantUniqueVector` is mandatory. Choose other identity types (phoneNumber and/or email) based on the `authPlans` you configure for your cardholders. The tenantUniqueVectorID is verified by the Cipher system (using the authentication token given by the host app) while authenticating the SDK during registration.
`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.

{
    "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

GET	/tenants/{tenantId}

Request details

Request parameters

Parameter Description

Query parameters

tenantId

Integer, Required

ID of the tenant generated on the Cipher system.

Response details

Response parameters

Response sample

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, the Cipher system supports single factor authentication plans like SMS_OTP, email_OTP, and Super PIN.

{
    "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

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

Request details

Request parameters

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.

If more than one card is enrolled with the same value for tenantUniqueVector, the values for other identity types should match exactly. The enrollment call fails if more than one card is enrolled with the same value for tenantUniqueVector but the values for other identities differ.

Response details

Response parameters

Response sample

Parameter Description

cardHolderId

String

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

If more than one card is enrolled with the same value for tenantUniqueVector, the values for other identity types should match exactly. The enrollment call fails if more than one card is enrolled with the same value for tenantUniqueVector but the values for other identities differ.

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 are phone number, email and tenantUniqueVector:

phone number: Used to enroll the card with the phone number of the cardholder for authentication.
email: Used to enroll the card with the email id of the cardholder for authentication.
tenantUniqueVector: An unique identifier of the cardholder generated by the tenant. This is used to map the card to a cardholder and to authenticate the usage of SDK by this cardholder.

tenantUniqueVector is mandatory. Choose other identity types (phoneNumber and/or email) based on the authPlans you configure for your cardholders.
The tenantUniqueVectorID is verified by the Cipher system (using the authentication token given by the host app) while authenticating the SDK during registration.

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 card PAN in the 6x4 masked format with unmasked first 6 digits and last 4 digits.
This is needed for the following reasons:

Product identification
Bin mapping
Display purposes

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.

{
  "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 Identities

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

PATCH

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

Request details

Request parameters

Request sample

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. If more than one card is enrolled with the same value for tenantUniqueVector, the values for other identity types should match exactly. The enrollment call fails if more than one card is enrolled with the same value for tenantUniqueVector but the values for other identities differ.
Body Parameters
`identitiesInfo/type` String, Required	Type of identity to be updated. Currently, the Cipher system supports phone number and email. 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.

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

Response details

Response parameters

Response sample

Parameter Description

cardHolderId

String

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

If more than one card is enrolled with the same value for tenantUniqueVector, the values for other identity types should match exactly. The enrollment call fails if more than one card is enrolled with the same value for tenantUniqueVector but the values for other identities differ.

identities

String

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

{
  "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": "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

On this page:

Need Help?

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

Page tree

API Reference

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 Identities

Endpoint URI

Request details

Response details

Error codes