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.

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

/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 number on the payment card.

identities/type

String, Optional

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

phone number: Enroll the card with the phone number of the card holder for authentication.
email: Enroll the card with the email id of the cardholder for authentication.
tenantUniqueVector: Map the card to an authProfile and to authenticate the SDK usage.

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.

{
	"name": "Foo Bar",
    "cardInfo" : {
		"scheme" : "DEFAULT",
		"cardNumber" : "111111844739172"
	},
    "identities": [
		{
			"type" : "tenantUniqueVector",
			"value" : "990011223"
		},
		{
			"type": "phoneNumber",
			"value": "+919999999999"
		}
    ],
    "state": "ENABLED"
}

Response details

Response parameters

Response sample

Parameter Description

cardId

Integer

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

ID of the product generated on the Cipher system.

productName

String

Name of the product generated on the Cipher system.

authProfileId

Integer

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

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 for authentication.

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.

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

/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` Integer	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	ID of the product generated on the Cipher system.
`productName` Integer	Name of the product generated on the Cipher system
`authProfileId` Integer	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	A 15/16-digit number on the payment card.
`cardNetwork` Integer	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 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 for authentication. `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.

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

/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, we support 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"
                        }
                    ]
                }
            ]
        }
    ]
}

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