Guides

Passcode Validation V2

Suggest Edits

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

HeaderParameters
Content-Typeapplication/JSON
x-request-idUUID
x-client-nameString

Request body

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

FieldDescriptionRequired/OptionalType
passcodeThis field contains the base64 encoded value.RequiredNumber

Card information

FieldDescriptionRequired/OptionalType
maskedCardNumberThe 16-digit masked card number in the 1234-56xx-xxxx-3456 format.RequiredUUID
clientHashIdThe unique client identifier that's generated and shared before the API handshake.RequiredUUID
cardHashIdThe unique card identifier that's generated while new or add-on card issuance.RequiredUUID
cardExpiryThe card's expiration year. This field contains the base64 encoded expiration date of the card in the YYMM format.RequiredString

Merchant information

FieldDescriptionRequired/OptionalType
idThe identifier for the merchant performing the purchase request.OptionalString
nameThis field accepts the merchant's name.RequiredString
mccThe code that's used to describe the merchant business type.OptionalString
countryCodeThe country code of the merchant, for example, 840 numeric -3 format.OptionalString
urlThe URL or app name for the merchant performing the purchase request.OptionalString

Transaction information

FieldDescriptionRequired/OptionalType
amountThis field accepts the transaction amount up to two decimals. The formatted transaction amount.RequiredNumber
currencyThis field accepts the three-letter ISO-4217 transaction currency code.RequiredString
timestampThe transaction time stamp, for example,
2020-03-21T20:55:49.0000Z.		OptionalString

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

Updated 6 months ago