Initiate OOB

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 setup and that Nium uses as a base URL.

Asynchronous authentication flow

1. Nium sends an OOB initiation request to your configured backend endpoint as part of its 3DS initiation flow.
2. Your system receives the request and starts the cardholder's OOB authentication experience.
3. The cardholder approves or declines the authentication through your supported OOB channel.
4. Your system sends the authentication outcome to Nium using the OOB Authentication Callback.
5. Nium processes the callback outcome as part of the 3DS authentication flow.

Headers

Header	Parameter
content-type	application/json
x-request-id	UUID
x-client-name	String

Request body

The API's request body is divided into four areas: the transaction identifier, payment information, merchant information, and transaction information.

Field	Description	Required/Optional	Type
authTransactionId	The unique identifier generated for a transaction.	Required	UUID

Payment information

Field	Description	Required/Optional	Type
maskedCardNumber	The 16-digit masked card number in the 1234-56xx-xxxx-3456 format.	Required	String
clientHashId	The unique client identifier generated and shared before the API handshake.	Required	UUID
cardHashId	The unique card identifier generated during new or add-on card issuance.	Required	UUID
cardExpiry	The Base64-encoded expiration date of the card, documented as being in MM/YY format before encoding.	Required	String

Merchant information

Field	Description	Required/Optional	Type
id	The identifier for the merchant performing the purchase request.	Optional	String
name	The merchant's name.	Required	String
mcc	The code describing the merchant's business type.	Optional	String
countryCode	The merchant's numeric three-digit country code, for example 840.	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	The transaction amount, with up to two decimal places.	Required	Number
currency	The three-letter ISO 4217 transaction currency code.	Required	String
timestamp	The transaction timestamp, for example 2020-03-21T20:55:49.0000Z.	Optional	String

Request examples

The following examples use the same nested request structure and the /v2/oob endpoint. Replace the base URL and placeholder card expiry value with your integration-specific values.

Integration validation

The nested card, merchant, and transaction structure follows the original cURL example. The original Java, JavaScript, and Python examples instead used flattened fields. Confirm the expected V2 payload schema with the API engineering team before using these examples in production. Also confirm whether clientHashId belongs at the top level and the required Base64 encoding format for cardExpiry.

cURL

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-Customer-Service' \
  -d '{
    "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776",
    "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684",
    "card": {
      "maskedCardNumber": "4611-35xx-xxxx-1234",
      "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684",
      "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"
    }
  }'

Java (OkHttp)

import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import org.json.JSONObject;

OkHttpClient client = new OkHttpClient();

JSONObject payload = new JSONObject();
payload.put("authTransactionId", "e5610bdf-12b1-9807-4ccf-09b70bcff776");
payload.put("clientHashId", "e2710bdf-25b1-4535-9ccf-09b70bcff684");

JSONObject card = new JSONObject();
card.put("maskedCardNumber", "4611-35xx-xxxx-1234");
card.put("cardHashId", "e3008bdf-25b1-4535-9ccf-09b70bcff684");
card.put("cardExpiry", "<base64-encoded-expiry>");
payload.put("card", card);

JSONObject merchant = new JSONObject();
merchant.put("id", "MERCHANT12345");
merchant.put("name", "Test Merchant");
merchant.put("mcc", "5411");
merchant.put("countryCode", "840");
merchant.put("url", "https://www.testmerchant.com");
payload.put("merchant", merchant);

JSONObject transaction = new JSONObject();
transaction.put("amount", 1.10);
transaction.put("currency", "EUR");
transaction.put("timestamp", "2026-09-29T11:59:00.000Z");
payload.put("transaction", transaction);

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, payload.toString());

Request request = new Request.Builder()
    .url("https://<EComAuthCodeValidationBaseURL>/v2/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();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.code());
}

The Java example requires OkHttp and org.json. The RequestBody.create method signature may differ depending on the OkHttp version.

JavaScript (jQuery)

var settings = {
  "url": "https://<EComAuthCodeValidationBaseURL>/v2/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",
    "card": {
      "maskedCardNumber": "4611-35xx-xxxx-1234",
      "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684",
      "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"
    }
  })
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (xhr) {
  console.error(xhr.status, xhr.responseText);
});

Python (requests)

import requests

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

payload = {
    "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776",
    "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684",
    "card": {
        "maskedCardNumber": "4611-35xx-xxxx-1234",
        "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684",
        "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"
    }
}

headers = {
    "content-type": "application/json",
    "x-request-id": "123e4567-e89b-12d3-a456-426655440000",
    "x-client-name": "Cards-Customer-Service"
}

response = requests.post(url, json=payload, headers=headers, timeout=10)
print(response.status_code)
print(response.text)