Passcode Validation

You need to implement the Passcode Validation V2 API as part of the knowledge-based authentication (KBA) and the Strong Customer Authentication (SCA) requirement for e-commerce transactions. Nium invokes the operation to validate the customer's passcode during the authentication step of an e-commerce transaction.

POST https://<EComAuthCodeValidationBaseURL>/v2/passcode

📌 IMPORTANT

EComAuthCodeValidationBaseURL is the URL that you provide during the setup and which Nium uses as a base URL.

Headers

Header	Parameters
Content-Type	application/JSON
x-request-id	UUID
x-client-name	String

Request body

The API's request body is divided into these four areas:

Field	Description	Required/Optional	Type
passcode	This field contains the base64 encoded value.	Required	Number

Card information

Field	Description	Required/Optional	Type
maskedCardNumber	The 16-digit masked card number in the 1234-56xx-xxxx-3456 format.	Required	UUID
clientHashId	The unique client identifier that's generated and shared before the API handshake.	Required	UUID
cardHashId	The unique card identifier that's generated while new or add-on card issuance.	Required	UUID
cardExpiry	The card's expiration year. This field contains the base64 encoded expiration date of the card in the YYMM format.	Required	String

Merchant information

Field	Description	Required/Optional	Type
id	The identifier for the merchant performing the purchase request.	Optional	String
name	This field accepts the merchant's name.	Required	String
mcc	The code that's used to describe the merchant business type.	Optional	String
countryCode	The country code of the merchant, for example, 840 numeric -3 format.	Optional	String
url	The URL or app name for the merchant performing the purchase request.	Optional	String

Transaction information

Field	Description	Required/Optional	Type
amount	This field accepts the transaction amount up to two decimals. The formatted transaction amount.	Required	Number
currency	This field accepts the three-letter ISO-4217 transaction currency code.	Required	String
timestamp	The transaction time stamp, for example, \n2020-03-21T20:55:49.0000Z.	Optional	String

Request example

curl -X POST \ 'https://<EComAuthCodeValidationBaseURL>/v2/passcode' \
 -H 'content-type: application/json' \ 
 -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
  -H 'x-client-name: Cards-Card-Service' \ 
  -d '{ 
  "clientHashId":"",
 "passcode":"<base64 encoded passcode>", 
      "card",
      {
      "maskedCardNumber" : "4611-35xx-xxxx-1234",
      "cardHashId":"",
      "cardExpiry":"",
       },    
      "merchant",
      {
      "id":"",
      "name" : "Test Merchant",
      "mcc":"",
      "countryCode":"",
      "url":""
      }
      "transaction",
      {
      "amount": "1.10",
      "currency": "EUR",
      "timestamp":""
      }
    }
  }'

Response example

A successful verification is returned if the given passcode matches the one found in the customer's profile.

{
    "message": "Request processed successfully",
    "referenceNumber": "481b18ad-1146-439b-a227-f42fda6ae306",
    "responseCode": "00"
}

A failed verification is returned if the given passcode does not match the one found in the customer's profile.

{
    "message": "Passcode Mismatch",
    "referenceNumber": "9cac7923-42bf-4c9e-97d3-23ef41ba86b1",
    "responseCode": "01"
}

A failed verification is returned if the customer does not have a passcode or has not set up the passcode.

{
    "message": "Passcode not setup by user",
    "referenceNumber": "5faee1b2-97b0-4355-b2ad-774f1bfcb6c5",
    "responseCode": "02"
}