The SMS OTP API allows businesses to verify a mobile phone number of their users by sending a One-Time Password (OTP).

API flow

A user wants to access the merchant's website, which requires identification or authentication.
The user enters the mobile phone number in the web application and receives a validation code (OTP) through SMS.
The user enters in the validation code (OTP) in the web application.
The merchant receives the verified mobile phone number in the response from Rabobank.

📘
The SMS OTP API can be consumed as a standalone service. However, it is generally applied as an additional layer on top of another method, such as MFA.

Using the API

After your account set up is complete, subscribe the SMS OTP API to your application.

With SMS OTP, merchants can verify mobile phone numbers of users by sending a One-Time Password (OTP). The SMS OTP API will verify the phone number based on this OTP.

Create a session

Start a session to receive an authentication URL to redirect the user with a POST sessions request.

POST https://api.rabobank.nl/openapi/ris/auth/smsotp/sessions

To view full list of POST parameters, go to:

POST/ris/auth/smsotp/sessions

POST SMS OTP session

You can start an SMS OTP session by using the POST /sessions request.

Use the following example request body to start an SMS OTP flow:

{
    "callbackUrls": {
        "success": "https://api.rabobank.nl/success",
        "abort": "https://api.rabobank.nl/abort",
        "error": "https://api.rabobank.nl/error"
    },
    "language": "en",
    "requestedAttributes": [
        "idpId"
    ],
    "externalReference": "bfad9dfd-8691-443b-91c0-af16198e4d68"
}

This results in the following example response body with status Created:

{
    "id": "e94152f1-3f00-7040-9c1f-32e991f648dd",
    "authenticationUrl": "https://api.rabobank.nl/broker/sp/external-service/login?messageId=19de992b-5216-1c4f-b394-e45d62736493&transactionId=e94152f1-3f00-7040-9c1f-32e991f648dd",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://api.rabobank.nl/success&sessionId==e94152f1-3f00-7040-9c1f-32e991f648dd&",
        "abort": "https://api.rabobank.nl/abort&sessionId=e94152f1-3f00-7040-9c1f-32e991f648dd&",
        "error": "https://api.rabobank.nl/error&sessionId=e94152f1-3f00-7040-9c1f-32e991f648dd&",
    },
    "language": "en",
    "requestedAttributes": [
        "idpId"
    ],
    "externalReference": "bfad9dfd-8691-443b-91c0-af16198e4d68",
    "sessionLifetime": 1200
}

📘
For each session, a unique sessionId is generated to identify the session.

After the user has completed the authentication flow, the user is redirected to your own application (redirect URLs should be provided in HTTPS in the request body) and the status changes to a final state.

This should trigger your application to make a request to the GET endpoint and fetch the final result.

Retrieve a session

When the user is being redirected back to your own application, the session reaches a final state and the result can then be fetched using a GET /session/:sessionId request.

GET SMS OTP session result

GET https://api.rabobank.nl/openapi/ris/auth/smsotp/sessions/472b1cf0-2c2e-1647-9dcc-035f11643943

To view the GET parameters, read the endpoint description for GET /ris/auth/smsotp/sessions/:sessionId

{
    "id": "e94152f1-3f00-7040-9c1f-32e991f648dd",
    "authenticationUrl": "https://api.rabobank.nl/broker/sp/external-service/login?messageId=19de992b-5216-1c4f-b394-e45d62736493&transactionId=e94152f1-3f00-7040-9c1f-32e991f648dd",
    "status": "SUCCESS",
    "provider": "otp-sms",
    "subject": {
        "id": "uvWLXNUG9d3MyjO6arFT4u-xnO1WSw0JgbP3H-JY22M=",
        "idpId": "+31615600242"
    },
    "callbackUrls": {
        "success": "https://api.rabobank.nl/success&sessionId==e94152f1-3f00-7040-9c1f-32e991f648dd&",
        "abort": "https://api.rabobank.nl/abort&sessionId=e94152f1-3f00-7040-9c1f-32e991f648dd&",
        "error": "https://api.rabobank.nl/error&sessionId=e94152f1-3f00-7040-9c1f-32e991f648dd&",
    },
    "language": "en",
    "requestedAttributes": [
        "idpId"
    ],
    "externalReference": "bfad9dfd-8691-443b-91c0-af16198e4d68",
    "sessionLifetime": 1200
}

🚧

Each response contains a X-Trace-Id header which can be used for troubleshooting failed transactions

Certain fields may not be available in the response body, this depends on the availability in the source and the type of request. Read the response schema object to understand which fields can be part of the response body.

All responses are signed by Rabobank, to validate the response read Validate signed responses

Prefilling the mobile phone number

The SMS OTP API supports the functionality to prefill the mobile phone number in the request, which allows the service to be used as an MFA service. When the mobile phone number is prefilled, the number cannot be altered by the user in the UI and upon starting the flow in the browser, the OTP will be send out directly to the mobile phone number provided in the request.

In order to prefill the mobile phone number, the object below needs to be included when creating a session

    "prefilledInput": {
        "mobile": "+31612345678"
    },