OOB Authentication Callback

Use this callback to notify Nium after processing an out-of-band (OOB) authentication as part of the strong customer authentication (SCA) flow.

API version: The endpoint below is retained from the existing guide (V1). The API Reference also lists a V2 callback endpoint at /api/v2/client/{clientHashId}/3ds/oob/callback. Confirm the supported version and its request/response contract with the API team before changing the endpoint.

POST https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback

Path parameters

Parameter	Description	Type	Required
clientHashId	Unique identifier of the client.	UUID	Required

Headers

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

Request body

Field	Description	Type	Required
authTransactionId	Unique identifier of the transaction received during OOB authentication.	UUID	Required
referenceNumber	Unique reference associated with the OOB request in your system.	UUID	Required
status	ndicates the processing status of the OOB authentication. The expected value when submitting the callback is Success.	String	Optional
statusCode	OOB authentication outcome: • SSS000 — Authentication approved. • VCU701 — Authentication declined.	String	Required

The statusCode indicates the authentication outcome. It is distinct from the response status, which indicates whether Nium processed the callback request successfully. For example, VCU701 can indicate a declined authentication even if the callback request itself is processed successfully.

Request examples

cURL

curl -X POST \
  'https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback' \
  -H 'content-type: application/json' \
  -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
  -H 'x-client-name: Cards-Customer-Service' \
  -d '{
    "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06",
    "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89",
    "status": "Success",
    "statusCode": "SSS000"
  }'

Java (OkHttp)

import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String json = "{"
    + "\"authTransactionId\":\"2096355c-57c3-43c6-9c4a-fb155a026e06\","
    + "\"referenceNumber\":\"1b6865e4-5839-424a-8e73-965ef15c5d89\","
    + "\"status\":\"Success\","
    + "\"statusCode\":\"SSS000\""
    + "}";

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

Request request = new Request.Builder()
    .url("https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback")
    .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());
    System.out.println(response.body() != null ? response.body().string() : "");
}

Replace {clientHashId} with the actual client identifier. The RequestBody.create argument order may differ depending on the OkHttp version.

JavaScript (jQuery)

var settings = {
  "url": "https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "x-request-id": "123e4567-e89b-12d3-a456-426655440000",
    "x-client-name": "Cards-Customer-Service"
  },
  "data": JSON.stringify({
    "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06",
    "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89",
    "status": "Success",
    "statusCode": "SSS000"
  })
};

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

Replace {clientHashId} with the actual client identifier.

Python

import requests

url = "https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback"

payload = {
    "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06",
    "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89",
    "status": "Success",
    "statusCode": "SSS000"
}

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)

Replace {clientHashId} with the actual client identifier.

Response example

{
  "status": "Success"
}

Response body

Field	Description	Type
status	Indicates whether Nium processed the callback request. Documented values: • Success — The callback request was processed successfully. • Failed — The callback request was not processed successfully.	String

Error responses

The existing guide does not specify HTTP error status codes, error codes, or error response payloads for this callback. Consult the applicable API Reference or confirm these details with the API team before implementing error-specific handling.

Do not treat an authentication decline (statusCode: VCU701) as equivalent to a failed HTTP callback request. Check the HTTP response and response status separately from the authentication outcome.