Okay LogoOkay Logo

All the one's and zeros

Integrate Okay app with your service

All the one's and zeros
Download Server SDKExample: Android appExample: iOS app
1. Server Response Status Codes

Every response and callback from the Okay service contains status:

"status": { "code": <status code>, "message": "status message" }

Here is the list of all possible codes:

  • Code: -1 - INCOMPLETE
  • Code: 0 - SUCCESS
  • Code: 101 - ERROR

When status code is ERROR the message field has one of the following messages:

  • TenantInactive - Tenant is not active

  • TenantExpired - Trial period has expired

  • BadApplication - Cannot find App with the parameters within the request

  • BadLinkingCode - There are no linking records or more than one linking records with the linking code within the request

  • TenantLimitsNotDefined - There are no limits for the Tenant

  • TenantReachedLimits - Tenant exceeded limits for requested type of operation

  • BadTenantSession - There is an active Session for requested user already

  • TenantSessionNotFound - User Session is not found

  • UserNotLinked - Requested user is not linked

  • ProtocolError - Cannot decrypt the incoming request

  • NoUniqueLinkingCode - Cannot generate unique linking code in the specified time

  • NoPendingLinking - Multiple users are completing linking simultaneously on the same device

  • UnknownError - Unknown error

    2. Add Link User Workflow to Your Server

    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.
    2.1 Provide a Unique Value Generator

    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.

    2.2 Create Link User Trigger

    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.

    2.3 Example of Signature Generation

    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.

    3. Change Your Settings

    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.
    3.1 Know Your Tenant ID

    To make requests, you will need to provide your Tenant ID. You can obtain it from the Okay Admin Panel:

    1. Login to the Okay Admin Panel.
    2. Go to the Tenants page.
    3. 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>.

    3.2 Know Your Secret

    The Token you entered in your settings is also known as a Secret. A secret is used to generate signatures for every request.

    4. Add Link User Callback to Your Server

    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.

    5. Add Authorize User Callback to Your Server

    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.

    5.1 Handling the 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.

    Available values for the dataType :

    The following types of user answers that may come from the mobile application:

    Code - Value
    101 - CANCEL
    102 - PIN
    103 - OK

    At this point the transaction is finished and your server has the information that an end-user has sent.

    6. Add Authorize User Action Workflow to the Mobile Application

    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.

    7. Server Integration

    7.1 Starting

    To start using the Okay Application, your server should be integrated with the Okay Server using a REST interface.

    Your server needs to support three types of requests and three types of callbacks. A request to link a new user, authenticate them, or check authentication status. Your server must listen to three types of callbacks to receive notifications when user has finished linking, responding to authentication request, or removed your service from the list of supported services.

    Before You Start

    If you use Java to implement you server, there is the maven repository with all required artifacts. Please follow the Maven Artifacts Repository page to get them.

    7.2 Callbacks

    Some actions might take the user awhile to accomplish. To prevent long lasting requests and overloading the Okay server with an enormous amount of Check Requests, the Okay server sends callbacks when a long lasting action is completed. The target URI should be configured with the Okay website on the Tenant Settings page.

    Note: Every callback has a signature value. Check it to make sure the request has been received by the Okay service.

    Link User Callback

    When an end user completes linking, the Okay server will send ServerLinkUserCallback:

    { "status": { "code": <status code>, "message": "status message" }, "type": 101, "userExternalId": "unique user identifier", "signature": "callback signature" }

    Check the Callback Types page for all available values of type.

    Unlink User Callback

    When an end user removes your service from the list of connected services on the Okay application, the ServerUnlinkUserCallback will be sent:

    { "status": { "code": <status code>, "message": "status message" }, "type": 103, "userExternalId": "unique user identifier", "signature": "callback signature" }

    7.3 Link User

    When a user wants to add your service to the Okay Application, you need to send the ServerLinkUserRequest:

    POST /gateway/link Content-Type: application/json { "tenantId": <your tenant id>, "userExternalId": "user unique identifier", "signature": "request signature" }

    You can see a detailed explanation of the signature generation algorithm at the Signature Generation page.

    The Okay server responds with the ServerLinkUserResponse:

    { "status": { "code": <status code>, "message": "status message" }, "linkingCode": "unique short-living code", "linkingQrImg": "base64-encoded image of QR code" }

    An end user needs the linkingCode to accomplish linking.

    When you receive a response from the Okay service, check if it was successful by examining the status object. All possible codes are listed on the Server Response Status Codes page.

    The purpose of the linking is explained here.

    7.4 Check Authentication (Authorization) Status

    Once the ServerAuthUserResponse is received, send ServerAuthCheckUserRequest to check the end user's answer:

    POST /gateway/check Content-Type: application/json { "tenantId": <your tenant id>, "sessionExternalId": "user unique identifier", "type": "authorization type", "authParams": { "guiText": "message that is shown in the Okay application", "guiHeader": "header of the message that is shown in the Okay application" }, "signature": "request signature" }

    Note: Check statuses in periodically increasing intervals to avoid DoS of the Okay service.

    The Okay server will respond with ServerAuthCheckUserResponse:

    { "status": { "code": <status code>, "message": "status message" }, "authResult": { "dataType": <result data type code>, "data": "user response" } }

    Check out the AuthData Types page to see all available values for the dataType.

    A detailed explanation can be found here.

    7.5 Authenticate User (Authorize User Action)

    To authenticate a user or authorize a user action send ServerAuthUserRequest:

    POST /gateway/auth Content-Type: application/json { "tenantId": <your tenant id>, "userExternalId": "user unique identifier", "type": <authorization type>, "authParams": { "guiText": "message that is shown in the Okay application", "guiHeader": "header of the message that is shown in the Okay application" }, "signature": "request signature" }

    All possible codes of type are listed on the Session Types page. The Okay server will respond with ServerAuthUserResponse:

    { "status": { "code": <status code>, "message": "status message" }, "sessionExternalId": "unique session identifier" }

    sessionExternalId can be used to check status of this request.

    Detailed explanation is here.

    8. Add Link User Workflow to Your Mobile Application

    Install Okay Application

    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.

    8.1 Call Okay Application

    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.

    9. Additional Information

    There are additional request types that allows your server to check transaction status at the time of execution. Check here 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.

    10. Add Authorize User Action Workflow to Your Server
    10.1 Authenticate a user

    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.

    11. Create an Account

    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.

    11.1 Completing the registration

    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

    12. Signature Generation

    Every request and callback contains the signature field. Its value is based on the secret token that is set on the Okay website on the Tenant Settings page, and the data within the transferring object. As this token is known by you and Okay server only both servers can be sure that the request is received from trusted sender.

    Java Developers Notice

    You can use com.protectoria.gateway.tenant.signature.SignatureService that is shipped with multi-tenant-gateway-client artifact to generate signatures. Use an example from OkayRestClient.

    Structure

    To create a signature, concatenate all the fields from the request, response, or callback, and secret token. Then get its binary hash using the SHA-256 algorithm. After that, encode the binary data with Base64 encoding.

    Link User Request

    BASE64[SHA256(tenantId | userExternalId | secret)]

    For example, if your tenantId is 10000, userExternalId is U12, and secret is hollywood, you will need to calculate the value of BASE64[SHA256('10000U12hollywood')]. This would be 2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks=

    Authenticate User (Authorize User Action) Request

    BASE64[SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret)]

    For example, if tenantId is 12000, userExternalId is AATFR7851, type is 101, guiText is Have you requested authorization request?, guiHeader is Secure Service Request, and secret is password, you need to calculate the value of BASE64[SHA256('12000AATFR7851Secure Service RequestHave you requested authorization request?101password')]. This would be BBtE0ixMwgVZ2U0XZCBGpGffwfQgu4S0ler0Ia2kwHQ=.

    Check Authentication (Authorization) Status Request

    BASE64[SHA256(tenantId | sessionExternalId | secret)]


    Link User Callback

    BASE64[SHA256(userExternalId | status | type | secret)]

    For example, if userExternalId is 169U, status is ERROR, type is always 101, and secret is madonna, you need to calculate the value of BASE64[SHA256('169UERROR101madonna')]. This would be 7KqaxVN8vdS3VcJ4q83kQVP2wnzqoN+peI4ORXj7QP8=

    Authentication (Authorization) Callback

    BASE64[SHA256(userExternalId | sessionExternalId | status | type | data | dataType | secret)]

    Unlink User Callback

    BASE64[SHA256(userExternalId | status | type | secret)]