Check Authentication

Implement the Check Authentication Method V2 API if you want your system to be consulted for every e-commerce transaction. Nium invokes this API during an e-commerce transaction to retrieve the authentication method supported by your system.

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

important

EComAuthCodeValidationBaseURL is the base URL you provide during integration setup. Nium uses this URL to invoke your API. Replace the placeholder with your configured host when testing the example.

Headers

Header	Description	Example
content-type	Request body content type.	application/json
x-request-id	Unique request identifier.	123e4567-e89b-12d3-a456-426655440000
x-client-name	Name of the calling application.	Cards-Card-Service

Request body

The request contains general identifiers and three nested objects: card, merchant, and transaction.

General information

Field	Description	Type	Required/Optional
customerHashId	Unique customer identifier generated when the customer is created.	UUID	Required

Card information (card)

Field	Description	Type	Required/Optional
maskedCardNumber	Masked card number, for example 4611-35xx-xxxx-1234.	String	Required
cardHashId	Unique card identifier generated during new or add-on card issuance.	UUID	Required
email	Customer's email address.	String	Required
phoneNumber	Customer's phone number.	String	Required
cardExpiry	Base64-encoded card expiry, encoded from the MM/YY format.	String	Required

Merchant information (merchant)

Field	Description	Type	Required/Optional
id	Identifier of the merchant performing the purchase request.	String	Optional
name	Merchant name.	String	Required
mcc	Merchant category code describing the merchant's business.	String	Optional
countryCode	Merchant country code in three-digit numeric format, for example 840.	String	Optional
url	Merchant URL or application name.	String	Optional

Transaction information (transaction)

Field	Description	Type	Required/Optional
amount	Transaction amount with up to two decimal places.	Number	Required
currency	Three-letter ISO 4217 transaction currency code.	String	Required
timestamp	Transaction timestamp, for example 2026-09-29T11:59:00.000Z.	String	Optional

Request example

cURL

curl -X POST \
  'https://<EComAuthCodeValidationBaseURL>/v2/preference' \
  -H 'content-type: application/json' \
  -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
  -H 'x-client-name: Cards-Card-Service' \
  -d '{
    "customerHashId": "df3dfdf0-d75a-4d7e-b575-f8ed34e0fa94",
    "card": {
      "maskedCardNumber": "4611-35xx-xxxx-1234",
      "cardHashId": "5fa34f1a-8e7a-4bb5-a010-3a07cf714534",
      "email": "melissa@xyz.com",
      "phoneNumber": "9834201949",
      "cardExpiry": "<base64-encoded-expiry>"
    },
    "merchant": {
      "id": "MERCHANT12345",
      "name": "Test Merchant",
      "mcc": "5411",
      "countryCode": "840",
      "url": "https://www.testmerchant.com/"
    },
    "transaction": {
      "amount": 1.10,
      "currency": "EUR",
      "timestamp": "2026-09-29T11:59:00.000Z"
    }
  }'

note

The request example follows the nested card, merchant, and transaction structure indicated in the original guide. Confirm the exact V2 schema and the expected cardExpiry encoding with the API team. The cardExpiry value above is a placeholder, not a valid encoded expiry.

Response body

Field	Description	Type
respCode	Code indicating the selected authentication preference. See the authentication preference table below.	String
message	Description of the selected authentication preference. See the authentication preference table below.	String

Authentication preferences

respCode	message	Description
00	OOB Only	Only out-of-band (OOB) authentication is supported.
01	OOB with fallback to OTP+Passcode	OOB authentication is supported, with OTP plus passcode as a fallback.
02	OTP+Passcode Only	Only OTP plus passcode authentication is supported.
03	OTP Only	Only OTP authentication is supported.
04	OOB with fallback to OTP	OOB authentication is supported, with OTP as a fallback.

Response examples

Success response — OOB only

{
  "respCode": "00",
  "message": "OOB Only"
}

Success response — OOB with fallback to OTP plus passcode

{
  "respCode": "01",
  "message": "OOB with fallback to OTP+Passcode"
}

Success response — OTP plus passcode only

{
  "respCode": "02",
  "message": "OTP+Passcode Only"
}

Success response — OTP only

{
  "respCode": "03",
  "message": "OTP Only"
}

Success response — OOB with fallback to OTP

{
  "respCode": "04",
  "message": "OOB with fallback to OTP"
}

Error responses

The source guide does not specify HTTP error status codes, error response payloads, or timeout and retry behavior for this API. Confirm these details with the API team before documenting or implementing error-specific handling.

The respCode values 00–04 above describe authentication preferences; they are not HTTP error codes.