Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

Overview of the Card APIs

These six Card APIs handle credit/debit card interaction in the Juspay system.

Tokenize:   
This API generates a token representing the given details of a card. Once a card is tokenized, you can initiate a payment or add the card to any customer’s account using the Add Card API.   Should be called from a browser or from Android/iOS app.
Required:  Card (request) Parameters object,  merchant_id
Returns:  token   (expires after 15 min.)
  POST     https://api.juspay.in/card/tokenize
Add Card:   
Adds a credit card or debit card of a customer to JusPay Locker. Token from the Tokenize API may be used to represent the card. customer_id identifies the customer.
Required:  token or  Card (request) Parameter object,
merchant_id, customer_id
Returns:  card_token, card_reference, card_fingerprint
  POST     https://api.juspay.in/card/add
List stored cards:   
List all the cards stored for a customer. Returns an array of  Card (list) Parameter objects with tokens and other card data. Optionally checks if cards are eligible for ATM PIN payments, OTP payments, and/or mandates.
Required:  customer_id     Optional:  options.direct_otp_support,
options.atm_pin_auth_support, options.mandate_support
Returns:  customer_id, merchant_id, cards: [{...},{...}...]
  GET     https://api.juspay.in/cards
Delete Card:   
Deletes card and associated info identified by  card_token
Required:  card_token
Returns:  card_token, card_reference, deleted (true/false)
  POST     https://api.juspay.in/card/delete
Card Info:   
Get Card details using card bin (cardbin). Can also check if a card is eligible for ATM PIN payments, OTP payments, and/or mandates.
Optional:  merchant_id, options.check_direct_otp_support,
options.check_atm_pin_auth_support, options.check_mandate_support
Returns:  Card (info) Parameters.
  GET     https://api.juspay.in/cardbins/cardbins
Bin List:   
Get the list of bins based on the supported authentication type.
Required:  auth_type (Set to either "OTP" or "VIES")
Returns:  bins:[...]  (List of cardbin parameters - one for each card)
  GET     https://api.juspay.in/v2/bins/eligibility
URL Embedded (Query) Parameter:
Field * Type Description
token String Token to identify card. Used only for the for the Add Card API, and if used, do not include  Card (request) Parameters. Must be used before it expires.
NOTE: This parameter can easily be confused with card_token, which basically does the same thing. The parameter token should be changed to card_token, or vice-versa.
Additonal Request (Form) Parameters:
Field * Type Description
merchant_id String Merchant ID which represents the merchant storing the card
(Required only for the Tokenize API and Add Card API)
customer_id String Customer ID which represents the user uniquely
(Required only for the Add Card API and List stored cards API)

Card Parameter Objects

  Card (Request) Parameters:   Card parameters sent with the Tokenize API.
Also sent with the Add Card API only if token isn't used.     (click to open table)
FieldTypeDescription
card_number*StringA valid card number (Required for the Tokenize API, and also for the Add Card API if token is not used. )
card_exp_year*StringExpiry year of the card (Format: yyyy) Example: "2020" (Required for the Tokenize API, and also for the Add Card API if token is not used. )
card_exp_month*StringExpiry month of the card (Format: mm) Example: "06" (Required for the Tokenize API, and also for the Add Card API if token is not used. )
card_security_code*StringCVV of the card. Usually three digits.
(Required only for the Tokenize API. Not used for the Add Card API)
name_on_cardStringCard holder name. Should contain alphabetical characters only.
customer_emailStringEmail address of the customer.
(Optional only for the Add Card API)
nicknameStringA tag or a label for the card so that the user can easily identify the card.
(Optional only for the Add Card API)
  * = Conditionally required
  Card (List) Parameters:   Used in the array returned with the List Stored
Cards API for listing card details.       (click to open table)
FieldTypeDescription
card_tokenStringToken representing the card. Payment must be initiated using this token. Tokens are by definition short lived, so please do not cache them in your system. Expired tokens will lead to transactions being declined.
card_referenceStringA reference identifier that doesn’t change for the stored card. Can be used to store any card metadata; for example: card type, card bin, or even transaction data.
card_fingerprintStringA string that uniquely identifies the card across the board. When the same card is stored across multiple accounts, same fingerprint will be returned. This can be used to identify duplicates.
card_numberStringMasked card number that can be displayed to the customer.
card_isinStringFirst 6 digits of the card
(International Securities Identification Number)
card_exp_yearStringExpiry year of the card (Format: yyyy) Example: "2020"
card_exp_monthStringExpiry month of the card (Format: mm) Example: "06"
card_typeStringIndicates if the card is either CREDIT or DEBIT. Please note that this information is inferred. Not all cards will have this information.
card_issuerStringIndicates the bank which issued the card. This again is not available all the time. We make our best effort to get this information for all cards.
card_brandStringIndicates the name of the card switch provider (MASTERCARD, VISA, etc.). Please note that this information is inferred
name_on_cardStringCardholder name given while storing the card. Should contain alphabetical characters only.
nicknameStringOptional nickname for card
expiredBooleanIndicates whether the stored card is expired or not
direct_otp_supportBooleanIndicates if the card is eligible for OTP payments.
atm_pin_auth_supportBooleanIndicates if the card is eligible for ATM PIN payments.
mandate_supportBooleanIndicates if the card is eligible for mandates.
  Card (Info) Parameters:   Response for the Card Info API
(click to open table)
FieldTypeDescription
idStringID code for the card (depends on object selection).
objectStringObject is usually set to cardbin (first 6 digits of the card number). Could also be card_isin, card_reference, etc.
card_brandStringBrand of card (MASTERCARD, VISA, etc.) This can be inferred from card.
card_issuerStringCode for bank that issued the card (not always available)
countryStringCountry where card originated (not always available)
card_typeStringIndicates if the card is either CREDIT or DEBIT. This can be inferred from card (but not for all cards).
expiredBooleanIndicates whether the stored card is expired or not
(not in main document, but should be included).
direct_otp_supportBooleanIndicates if the card is eligible for OTP payments.
atm_pin_auth_supportBooleanIndicates if the card is eligible for ATM PIN payments.
mandate_supportBooleanIndicates if the card is eligible for mandates.

📘

NOTE:

There are three different types of Card Parameter objects, depending on which API they are used for and how they are used.   There should be a way to combine parameters so that only one or two Card Parameter objects are needed.