Passcode Validation V2

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, 2020-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"
}

📌IMPORTANT

Headers

Request body

Card information

Merchant information

Transaction information

Request example

Response example

📌
IMPORTANT