Step by Step Guide
Before you can start, you will need to create a new Tenant. This Tenant will be the account for your service. You can create your Tenant at the Okay website.
The email address used in your Tenant creation will receive instructions for completing the registration process. This will include setting a password to the account.
It is advised that you first try to integrate your device to the Okay Service back-end. You can do this using the Okay app on your device. If you can see that the Okay app works for authentications and transaction verification, then the back-end is working correctly and you may switch to the SDK.
Next there are some mandatory fields we will need you to fill out in your account settings. Navigate to Tenants page and click on 
button to alter your account settings. The fill in the following fields:
- Name - While mandatory, this setting will have no impact on functionality.
- Callback - This must be filled with the URL that you will be using to handle callbacks from the Okay Service.
- Token - An alphanumeric sequence that is used to create signatures and validate requests. This should be kept a secret or you will compromise security.
To make requests, you will need to provide your Tenant ID. You can obtain it from the Okay Admin Panel:
- Login to the Okay Admin Panel.
- Go to the Tenants page.
- Your Tenant ID will be the number in the first column in the row with your service name.
In all examples below use your actual Tenant ID Number instead of <your tenant id>.
The Token you entered in your settings is also known as a Secret. A secret is used to generate signatures for every request.
To integrate Okay to your server, the server must be able to make requests and handle callbacks.
Your back-end will need to be able to send requests of the following types:
- ServerLinkUserRequest - Requests to link the end-user.
- ServerAuthUserRequest - Requests to authorize end-user actions.
- ServerAuthCheckUserRequest - Requests to check an authorization status.
Your server needs to generate and store a unique identifier for every end-user in order to differentiate between them. You can use any ASCII symbols to compose this value. A UUID or a primary key from your database can be used for example. Use this value in all requests instead of "user unique identifier" in the examples below.
User Linking is required to allow your server to send requests to users using the Okay service.
When a user wants to add your service to the Okay Application you will need to send the ServerLinkUserRequest.
It uses the following JSON structure:
{
"tenantId": <your tenant id>,
"userExternalId": "user unique identifier",
"signature": BASE64[SHA256(tenantId | userExternalId | secret)]
}
To use our demostand you need to send this JSON to https://demostand.okaythis.com/gateway/link using POST.
Here is an example of how to generate a signature for this JSON. For this example your tenantId is 10000, userExternalId is U12, and secret is hollywood.
You need to calculate the value of BASE64[SHA256('10000U12hollywood')]. This would be 2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks=.
If you have any questions take a look at a detailed explanation.
After that create a JSON with your data. In our example the result is:
{
"tenantId": 10000,
"userExternalId": "U12",
"signature": "2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks="
}
Send the JSON to the Okay service using the POST method and the Content-Type header:
POST https://demostand.okaythis.com/gateway/link
Content-Type: application/json
{
"tenantId": 10000,
"userExternalId": "U12",
"signature": "2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks="
}
If your request is correct, you'll get a response with the following body:
{
"status": {
"code": 0,
"message": "OK"
},
"linkingCode": "unique short-living code",
"linkingQrImg": "base64-encoded image of QR code"
}
This linkingCode need to be delivered to the end-user in order to accomplish linking workflow.
To proceed with linking workflow switch to mobile application development.
First install the Okay Application on your device:
Start it and wait until application is initialised. At start-up, the application will be registered on the Okay service. No other actions with this application is needed.
In your application call the Okay Application and pass the linkingCode, your service display, and your tenantId.
That will show the Okay Application to the end-user. After they finish the flow, the application will return the result back to your application.
Note that this result just informs you whether an end-user clicked Ok or Cancel, this is not the Okay service result.
When an end-user clicks Ok or Cancel in the Okay Application, the result is sent to the Okay service that links the user device with your identifier for the user. So in order to understand if the Okay service accomplished linking your server, you need to wait for the Link User Callback.
The Okay service sends all callbacks to the URL that you set in the Callback field on the second step.
The data is sent in this JSON format using HTTP POST method:
{
"status": {
"code": <status code>,
"message": "status message"
},
"type": 101,
"userExternalId": "unique user identifier",
"signature": BASE64[SHA256(userExternalId | status | type | secret)]
}
To avoid attacks, make sure you check the received signature.
Example: If userExternalId is 169U, status is ERROR, type is always 101, and secret is madonna, you will need to calculate the value of BASE64[SHA256('169UERROR101madonna')]. This would be 7KqaxVN8vdS3VcJ4q83kQVP2wnzqoN+peI4ORXj7QP8=.
At this point the user linking scenario is finished.
To authenticate a user or authorize a user action, your server will need to send ServerAuthUserRequest with the following structure:
{
"tenantId": <your tenant id>,
"userExternalId": "user unique identifier",
"type": <authorization type code>,
"authParams": {
"guiText": "message that is shown in the Okay application",
"guiHeader": "header of the message that is shown in the Okay application"
},
"signature": BASE64[SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret)]
}
All options of type are listed on the Session Types page.
The authParams contains text which an end-user see when request is received.
Next generate a signature.
Example: If tenantId is 12000, userExternalId is AATFR7851, type is 101 (simple scenario with OK/Cancel buttons), guiText is Have you requested authorization request?, guiHeader is Secure Service Request, and secret is password, you will need to calculate the value of BASE64[SHA256('12000AATFR7851Secure Service RequestHave you requested authorization request?101password')]. This would be BBtE0ixMwgVZ2U0XZCBGpGffwfQgu4S0ler0Ia2kwHQ=.
Now create a JSON with your data. In our example the result is:
{
"tenantId": 12000,
"userExternalId": "AATFR7851",
"type": 101,
"authParams": {
"guiText": "Have you requested authorization request?",
"guiHeader": "Secure Service Request"
},
"signature": "BBtE0ixMwgVZ2U0XZCBGpGffwfQgu4S0ler0Ia2kwHQ="
}
To use our demostand, you need to send that JSON to https://demostand.okaythis.com/gateway/auth using HTTP POST method and the Content-Type header.
If your request is correct, you'll get a response with the following body:
{
"status": {
"code": 0,
"message": "Ok"
},
"sessionExternalId": "unique session identifier"
}
sessionExternalId can be used later to check status of this request.
In this scenario the Okay Application handles requests form the Okay service. No implementation is required.
The end-user just follows instructions on their mobile phone.
When an end-user accomplishes flow in the Okay Application, the result is sent to the Okay service, in-which transforms the data and sends to your server. In order to receive the end-user's answer, your server must wait for the Authorization Callback.
The Okay service sends all callbacks to the URL that you set in Callback field on the second step. The data is sent in JSON format using HTTP POST method. The structure of the callback is the following:
{
"status": {
"code": <status code>,
"message": "status message"
},
"type": 102,
"userExternalId": "unique user identifier",
"sessionExternalId": "unique session identifier",
"authResult": {
"dataType": <result data type code>,
"data": "user response"
},
"signature": BASE64[SHA256(userExternalId | sessionExternalId | status | type | data | dataType | secret)]
}
To avoid attacks make sure you check received signature.
Callbacks of this type contains an end-user answer in the authResult field. dataType describes the type of data encrypted in the data field. Navigate to AuthData Types page to see all available values for the dataType.
At this point the transaction is finished and your server has the information that an end-user has sent.
There are additional request types that allows your server to check transaction status at the time of execution. See this page for more details.
To support cases when an end-user removes your service from their list, add Unlink User Callback support.
If you want to use the SDK instead of the Okay app, you can look at our guide.
