Initiate OOB Authentication V2

You need to implement the Initiate OOB Authentication V2 API as part of the out-of-band (OOB) authentication process. Nium invokes the endpoint to perform the operation and start the OOB authentication step of an e-commerce transaction.

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

πŸ“Œ

IMPORTANT

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

Headers

HeaderParameter
content-typeapplication/JSON
x-request-idUUID
x-client-nameString

Request body

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

FieldDescriptionRequired/OptionalType
authTransactionIdThis field accepts the unique identifier generated for a transaction.RequiredUUID

Payment 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/oob> \
  -H 'content-type: application/json' \
  -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
  -H 'x-client-name: Cards-Card-Service' \
  -d '{
      "authTransactionId" : "e5610bdf-12b1-9807-4ccf-09b70bcff776",
      "clientHashId":"",
      "card",
      {
      "maskedCardNumber" : "4611-35xx-xxxx-1234",
      "cardHashId":"",
       "cardExpiry":""
      },    
      "merchant",
      {
      "id":"",
      "name" : "Test Merchant",
      "mcc":"",
      "countryCode":"",
      "url":""
      }
      "transaction",
      {
      "amount": "1.10",
      "currency": "EUR",
      "timestamp":""
      }
    }
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"authTransactionId\" : \"e5610bdf-12b1-9807-4ccf-09b70bcff776\",\r\n    \"clientHashId\" : \"e2710bdf-25b1-4535-9ccf-09b70bcff684\",\r\n    \"cardHashId\" : \"e3008bdf-25b1-4535-9ccf-09b70bcff684\",\r\n    \"customerHashId\" : \"e2708eef-25b1-4535-9ccf-09b70bcff684\",\r\n    \"walletHashId\" : \"e2708bdf-25b1-4535-9ccf-09b70bcdd684\",\r\n    \"merchantName\" : \"Test Merchant\",\r\n    \"maskedCardNumber\" : \"4611-35xx-xxxx-1234\",\r\n    \"transactionAmount\" : \"1.10\",\r\n    \"transactionCurrency\" : \"EUR\"\r\n}");
Request request = new Request.Builder()
  .url("https://<EComAuthCodeValidationBaseURL>/oob")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("x-request-id", "123e4567-e89b-12d3-a456-426655440000")
  .addHeader("x-client-name", "Cards-Customer-Service")
  .build();

Response response = client.newCall(request).execute();
var settings = {
  "https://<EComAuthCodeValidationBaseURL>/oob",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "x-request-id": "123e4567-e89b-12d3-a456-426655440000",
    "x-client-name": "Cards-Customer-Service"
  },
  "data": JSON.stringify({
    "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776",
    "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684",
    "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684",
    "customerHashId": "e2708eef-25b1-4535-9ccf-09b70bcff684",
    "walletHashId": "e2708bdf-25b1-4535-9ccf-09b70bcdd684",
    "merchantName": "Test Merchant",
    "maskedCardNumber": "4611-35xx-xxxx-1234",
    "transactionAmount": "1.10",
    "transactionCurrency": "EUR"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
import requests

url = "https://<EComAuthCodeValidationBaseURL>/oob"

payload = json.dumps({
  "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776",
  "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684",
  "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684",
  "customerHashId": "e2708eef-25b1-4535-9ccf-09b70bcff684",
  "walletHashId": "e2708bdf-25b1-4535-9ccf-09b70bcdd684",
  "merchantName": "Test Merchant",
  "maskedCardNumber": "4611-35xx-xxxx-1234",
  "transactionAmount": "1.10",
  "transactionCurrency": "EUR"
})
headers = {
    'content-type': "application/json",
    'x-request-id': "123e4567-e89b-12d3-a456-426655440000",
    'x-client-name': "Cards-Customer-Service"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)