Rabo Identity Services - SMS OTP v1.32.0
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"
},
ClientId as provided by the Rabobank developer portal.