Rabo Identity Services - SMS OTP v1.32.0

Skip to main content

Overview

The SMS OTP API is an offering of Rabo Identity Services for businesses that want to verify a mobile phone number, through sending a One-Time Password.

Before you begin

Make sure you have a working sandbox account in the Rabobank developer portal. Read Get Started to set up an account and register an Application.

NOTE: To use these API(s), a valid TLS certificate is required.

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.

You should create separate applications for the pre-production and production environments to efficiently differentiate the API traffic.

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"
    },
Type
REST
OAS2
Protocol
HTTPS
Endpoint
Production, Development:
https://api.rabobank.nl/openapi/
Security
Mutual TLS
Enabled
clientId
X-IBM-Client-Id
apiKey located in header

ClientId as provided by the Rabobank developer portal.