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 Integration

1.1 Getting Started

To proceed with Okay integration, you are required to create an account using this link. Once you are successfully signed up, login in with the credentials that you used to create the account here.Once you are logged in to your dashboard click on Tenants in the top toolbar, then select tenants from the drop down menu.

The Tenants web page is where you will register your server that will communicate with Okay servers in order to verify/initiate secure transactions/authentications. Your tenant page should present a table that looks like the table below.

Overview of the Tenant table

If you check the tenants page, you will see that you already have an entry in the Tenants table. The contents of that row are essential in understanding how to integrate Okay into your server.

The first column under the table is what we refer to as your Tenant ID. In the image above my Tenant Id is 

40007

It is very important that you take note of this value as we will be using this value for our transactions/authentication.

The text under the Name column in the Tenants table is the name of the company you provided at the time of your sign up.

Specifies the status of your tenant.

Shows your tenant trial expiration date, if you are still on trial mode.Actions

The Action column has three buttons that allows us to manage our tenant credentials.

Adding Credentials to your Tenant

To make our tenant useful, we will be adding more information to the tenant to connect properly/securely to Okay servers. Click on the pencil icon under Actions to complete the tenant registration.

To be able to recieve feedbacks from Okay servers you will need to add a valid callback url (A callback url is an endpoint on your server that will be used as a point of communication by Okay to notify your server about the status of transactions/authentication) to the Callback input field. We will also need to generate a secret secure token(or secret) that will be used to verify all transactions by Okay secure servers. The token could be any alphanumeric secure string that contains about 30 characters (or more) and must always be kept secret.

Note: we will be referring to our Token as secret in further illustrations.

1.2 Linking Guide

Provide a Unique Value Generator

Before we can authorize transactions using Okay on our server, we need to link our users to Okay so that we can identify all transactions coming from different users.

Before we proceed to linking your users to Okay. We need to generate and store a Unique Identifier for every end-user in order to differentiate all your users. You can use any alpha-numeric character to compose this value, for example a UUID. We will be using this value in all our requests as User Unique Identifier. This normally serves as value to the "userExternalId" key in our payload.

Click here for server sample demo

This is a typical structure of our JSON payload for linking users

{ "tenantId": "<your tenant id>", "userExternalId": "User Unique Identifier", "signature": "BASE64[SHA256(tenantId | userExternalId | secret)]" }

The tenantId key in our payload above, is the ID we got from our  table. Please refer to Integrating Okay to your Server section of this document if you don't already have your tenant id.

The userExternalId key in our payload above is the User Unique Identifier you created for your users in order to differentiate them as described in the Provide a Unique Value Generator section of this documentation above.

The signature key in our payload above is a hash that is generated from concatenating your tenantId + userExternalId + secret (also know as the Token you added to your tenant) then passing the concatenated string as value to SHA256() algorithm. Then we encode whatever value or string we get from the SHA256() algorithm in BASE64.

const crypto = require('crypto') const axios = require('axios') const PSS_BASE_URL = 'https://demostand.okaythis.com'; const tenantId = 40007; // replace with your tenantId const userExternalId = 'uid406jkt'; // replace with your unique user id const secret = 'securetoken'; // replace with your secret const hashStr = `${tenantId}${userExternalId}${secret}`; const signature = createHashSignature(hashStr); console.log(signature) // returns zqVmg24iAeAqhKdyFOClJdmaB1NBE4lm4K/xnZUwg7M= function createHashSignature(hashStr) { return crypto .createHash('sha256') .update(hashStr) .digest('base64') } ...

If all is set, we proceed to linking our user. To link a user we need to send our JSON payload as a POST request to this endpoint below:

https://demostand.okaythis.com/gateway/link

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

User Linking Sample Code

const crypto = require('crypto') const axios = require('axios') const PSS_BASE_URL = 'https://demostand.okaythis.com'; const tenantId = 40007; // replace with your tenantId const userExternalId = 'uid406jkt'; // replace with your unique user id const secret = 'securetoken'; // replace with your secret const hashStr = `${tenantId}${userExternalId}${secret}`; const signature = createHashSignature(hashStr); axios({ method: 'post', headers: { 'Content-Type': 'application/json' }, url: `${PSS_BASE_URL}/gateway/link`, data: { tenantId, userExternalId, signature } }) .then((response) => { console.log(response.data); }) .catch((error) => { console.log(error.response.data) }); function createHashSignature(hashStr) { return crypto .createHash('sha256') .update(hashStr) .digest('base64') }

When your request is correct you'll get a response with the following body

{ "linkingCode": "unique short-living code", "eg 416966" "linkingQrImg": "base64-encoded image of QR code", "status": { "code": 0, "message": "OK" }, }

Sample Response:

{ "linkingCode": "980565", "linkingQrImg": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABhUlEQVR42u3aQXKDMAwFUGVYsOQIHIWjhaPlKBwhSy8yqLIkm9CUNMae6XTme0XMW8WqLCkl/mTdCQwMDAzsb1ggW0PomIkm2e5W3+vAqpk+8zLwg+xYgjDeXoHVsfidT8JY3s5+Cjz7uYA1Y7KE2SmAtWaPC9OVFyKwlizlkF2QH6casCK23YDKliH8clGCFbC89O31Nt7t7VGZB1bEAl3YcwgpY4321yAHO8UsRcsn8ZKZRw37mKK/lcdgZ5itm+WQHORixh/+FsCKWYxtmnKuHjXs4524PwWwU0w35eKjPtZvwtIpEPUMVs/Iyrb+Odr9AayeWdOhzZ0FudVvqdIAq2J+A3r9Jtu9VxpgTVicSOROWY4j5+pdeQx2iu27j9zTzWkWBFbFcu8cmw4NcvIm+uUGBDvBtqm7VRoW7TYCAqtnPrdM02BfyYO1YpyajtXbELB2TH+Ss9SxHk4wwIrZU11hD7G5ixO2AFbPdlP32NOxNdHvhvNgnzL8Xw0YGBjYP2ZfZfRH9E/qf44AAAAASUVORK5CYII=", "status": { "code": 0, "message": "OK" } }

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.

1.3 Linking With Okay Mobile App

In order to test if your server is working properly, we strongly recommend you to download the Okay mobile app from Google Play Store for Android, or Apple App Store for iOS.

STEPS TO LINKING ON MOBILE APP

After installation proceed to granting these permissions

Click the check box on this screen to grant permission then press the back button twice to return the app.

Grant all permissions

To proceed with linking, click the white button on this screen below.

You will be redirected to a camera screen, click the button at the bottom of the camera screen labeled 

Type 'em instead

 to proceed to the linking screen shown below.

Enter the six digits linkingCode you received from your linking response into the mobile app's input field, then click Link me on the app. In our case the linkingCode was 980565.

If all goes smoothly, you will see a screen like the one below

1.4 Authenticate User (Authorize User Action)

After Linking a user, we can now authenticate that user or authorize the user's action.

Just like linking a user, we will be sending a JSON payload as a POST request to Okay using the link below

https://demostand.okaythis.com/gateway/auth

This is a typical structure of our JSON payload for authenticating users/authorizing user actions

{ "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": "BASE64[SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret)]" }

For this request, we will be adding two new fields, the type and authParams fields.

The type key in our JSON payload is a field that allows us to clearly specify the kind of authorization/authentication we choose to initiate. The type key can take as value any of these authentication types listed below.

AUTH TYPE | AUTH CODE -------------------------------- AUTH_OK | 101 AUTH_PIN | 102 AUTH_PIN_TAN | 103 BIOMETRIC_OK | 105 GET_PAYMENT_CARD | 111

All possible auth codes/types are listed on the Session Types page.

The authParams just contains a  (guiText) and the  (guiHeader) that will be displayed on the Okay App. The message is intended for the user to read, in order to grant Okay the required permission to complete a transaction/authentication.

We can now proceed to sending our request to Okaythis server like so.

const crypto = require('crypto') const axios = require('axios') const PSS_BASE_URL = 'https://demostand.okaythis.com'; const tenantId = 40007; // replace with your tenantId const userExternalId = 'uid406jkt'; // replace with your unique user id const secret = 'securetoken'; // replace with your secret const authParams = { guiText: 'Do you okay this transaction', guiHeader: 'Authorization requested' }; const AUTH_TYPES = { OK: 101, PIN: 102, PIN_TAN: 103, BIOMETRIC_OK: 105, GET_PAYMENT_CARD: 111, } const type = AUTH_TYPES.OK const hashStr = `${tenantId}${userExternalId}${authParams.guiHeader}${authParams.guiText}${type}${secret}`; const signature = createHashSignature(hashStr); axios({ method: 'post', headers: { 'Content-Type': 'application/json' }, url: `${PSS_BASE_URL}/gateway/auth`, data: { tenantId, userExternalId, type, authParams, signature } }) .then((response) => { console.log(response.data); }) .catch((error) => { console.log(error.response.data) }); function createHashSignature(hashStr) { return crypto .createHash('sha256') .update(hashStr) .digest('base64') }

If your request is correct you'll get a response with the following body structure:

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

Sample Response:

{ "status": { "code": 0, "message": "OK" }, "sessionExternalId": 100227 }

If a secure communication channel was succcessfully established, Okay presents the authorization screen.

Click the "OKAY" button to grant authorization.

Click "Start Now" on the modal popup shown below to proceed.

If all goes well, Okay will present a success screen like the one below, to notify you that the request was approved successfully.

For better reference to all possible status code and messages you can receive from Okay server please refer to this link.

The sessionExternalId can be used to check the status of this request. We will see shortly, in the Check Authentication/Authorization Status section, how we can use the sessionExternalId value retrieved from the response to check the status of our transaction.

1.5 Check Authentication (Authorization) Status

After Authorizing/Authenticating a user we can check the status of that request by sending a JSON payload as a POST request to this endpoint https://demostand.okaythis.com/gateway/check on Okay Server.

This is a typical structure of our JSON payload for checking authentication/authorization status

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

Send a request to check the status of your transaction (Sample Code).

const crypto = require('crypto') const axios = require('axios') const PSS_BASE_URL = 'https://demostand.okaythis.com'; const tenantId = 40007; // replace with your tenantId const sessionExternalId = 100227; // "replace with your 'sessionExternalId' from previous Auth request const secret = 'securetoken'; // //replace with your secret const hashStr = `${tenantId}${sessionExternalId}${secret}`; const signature = createHashSignature(hashStr); axios({ method: 'post', headers: { 'Content-Type': 'application/json' }, url: `${PSS_BASE_URL}/gateway/check`, data: { tenantId, sessionExternalId, signature } }) .then((response) => { console.log(response.data); }) .catch((error) => { console.log(error.response.data) }); function createHashSignature(hashStr) { return crypto .createHash('sha256') .update(hashStr) .digest('base64') }

If your request is correct you'll get a response with the following body structure:

{ "status": { "code": "<status code>", "message": "status message" }, "authResult": { "dataType": "<result data type code> eg. 101, 102, 103", "data": "user response eg. CANCEL, PIN, OK" } }

The authResult field may contain any of these values from the table below, as a user response from the mobile app

DATA | DATA TYPE -------------------------------- CANCEL | 101 PIN | 102 OK | 103

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

A detailed explanation can be found here.

1.6 Callbacks

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.

Some actions might take the user a while 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, Okay server sends the following JSON data to the callback url that was specified on the tenant settings page:

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

Authentication (Authorization) Callback

Okay sends this JSON body when a transaction response from Okay mobile application is received.

{ "type": 102, "userExternalId": "unique user identifier", "sessionExternalId": "unique session identifier", "authResult": { "dataType": "<result data type code>", "data": "user response" }, "signature": "callback signature" }

The authResult key in the response above, has the same structure as the authResult returned from Check Authentication/Authorization Status request.

Unlink User Callback

When an end user removes your service from the list of connected services from Okay, Okay sends to your server via the callback url a JSON response having the structure below:

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

2. Server Response Status Codes

Every response and callback from the Okay service contains a status field:

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

Here is the list of all possible codes:

Attribute | Type | Description -------------------------------------------------------------------- INCOMPLETE | Const (-1) | Response Status code SUCCESS | Const (0) | Successful result. ERROR | Const (101) | Error result

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

    3. Changing Your Tenant 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. Then 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.
    4. 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.

    How you should generate your signature hash for linking a user

    If your tenantId is 10000userExternalId is "U12," and secret is "hollywood", you will need to calculate the value of BASE64(SHA256("10000U12hollywood")). This result of the hash would be 2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks=

    How you should generate your signature hash for authorizing user request

    BASE64(SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret))If your tenantId is 12000, userExternalId is AATFR7851type 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 result of the hash will be BBtE0ixMwgVZ2U0XZCBGpGffwfQgu4S0ler0Ia2kwHQ=.

    Link User Callback

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

    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)]


    5. Additional Information

    There are additional request types that allows your server to check transaction status at the time of execution.

    5.1 Response Status

    Every response from Okay contains a status. The table below represents the fields/attributes that are returned from Okay response to your server.

    The structure of the status field in JSON format

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

    The structure of the status field in XSD format

    <xs:complexType name="ResponseStatus"> <xs:sequence> <!-- Response status code. --> <xs:element name="Code" type="tns:ResponseStatusCode"/> <!-- Response message. --> <xs:element name="Message" type="xs:string"/> </xs:sequence> </xs:complexType>

    Response Status

    Attribute | Type | Description -------------------------------------------------------------------- code | returns Response Status Code | Response Status code (see Response Status table below) message | String | Response Message

    Response Status in XSD

    <xs:complexType name="ResponseStatus"> <xs:sequence> <!-- Response status code. --> <xs:element name="Code" type="tns:ResponseStatusCode"/> <!-- Response message. --> <xs:element name="Message" type="xs:string"/> </xs:sequence> </xs:complexType>

    Response Status Codes

    Attribute | Type | Description -------------------------------------------------------------------- INCOMPLETE | Const (-1) | Response Status code SUCCESS | Const (0) | Successful result. ERROR | Const (101) | Error result

    Response Status Codes in XSD

    <xs:simpleType name="ResponseStatusCode"> <xs:restriction base="xs:int"> <!-- Incomplete result (for asynchronous requests). --> <xs:enumeration value="-1"/> <!-- Successful result. --> <xs:enumeration value="0"/> <!-- Error result. --> <xs:enumeration value="101"/> </xs:restriction> </xs:simpleType>

    Error messages associated with Response Status

    Message | Description -------------------------------------------------------------------- BadTenant | Requested Tenant does not exist UnsupportedInstallation | Installation not supported. Application should start force update scenario. BadApplication | App does not exist or must not exist on current step NoActiveSession | Active Session is not found BadSession | Session does not exist, There multiple suitable Sessions, Session must not exist on current step SessionIncomplete | Previous Session is incomplete SessionExpired | Timeout CodeBlockError | Facing problems with CodeBlock generation CodeBlockGenerationTimeout | Was not able to generate CodeBlock is specified time CryptographyError | Key generation error TextToSpeechError | TTS service is broken WatermarkError | Cannot decode watermark PushNotificationError | Problems with third-party push notification service VoipError | Problems with third-party VoIP service CallNoAnswer | The call was originated but no one answered IntegrityError | Critical error while processing integrity checks ProtocolError | Error while encoding/decoding client request/response LicenseError | Server license is not valid and any client action requests are rejected

    5.2 Session Type

    The Session Type table represents all authorization/transaction types that Okay currently support. You can review the getting started guide to see how Okay uses AUTH_OK in our demo for authorization.

    Types

    Attribute | Type | Description ------------------------------------------------------------- AUTH_OK | 101 | OK button authorization session AUTH_PIN | 102 | PIN authorization session AUTH_PIN_TAN | 103 | PIN/TAN authorization session AUTH_BIOMETRIC_OK | 104 | Bio-metric confirmation authorization session GET_PAYMENT_CARD | 111 | Get payment card session

    Session Type in XSD

    <xs:simpleType name="SessionType"> <xs:restriction base="xs:int"> <!-- OK button authorization session. --> <xs:enumeration value="101"/> <!-- PIN authorization session. --> <xs:enumeration value="102"/> <!-- PIN/TAN authorization session. --> <xs:enumeration value="103"/> <!-- Bio-metric confirmation authorization session. --> <xs:enumeration value="105"/> <!-- Get payment card session. --> <xs:enumeration value="111"/> </xs:restriction> </xs:simpleType>

    Info about Session Types

    AUTH_OK - An end-user is asked to accept or deny request by pressing OK or CANCEL button in a mobile application. Simple scenario with YES/NO possible answers.

    AUTH_PIN - An end-user is asked to enter PIN in a mobile application input field. Also an end-user can CANCEL the request.

    AUTH_PIN_TAN - An end-user is asked to enter PIN in a mobile application input field. Then the user need to wait for the call and enter the numbers that the voice is prompted. Answer CANCEL is possible at any step.

    AUTH_BIOMETRIC_OK - An end-user is asked to identify themselves using biometric solution of their smartphone. When the biometric identification is not supported or disabled the AUTH_PIN is executed instead.

    GET_PAYMENT_CARD - An end-user is asked to enter bank card data to process with transaction.

    5.3 Session Artifact

    SessionArtifactType

    Attribute | Type | Description ------------------------------------------------------------------------------------ ERROR_UNKNOWN | 101 | OK button authorization session ERROR_TIMEOUT | 102 | Timeout ERROR_CRYPTO | 103 | Cryptography error ERROR_CODE_BLOCK | 105 | Code block error ERROR_SESSION | 107 | Error caused by an incorrect session ERROR_TTS | 108 | TTS error ERROR_WATERMARK | 109 | Watermark processing error ERROR_PNS | 110 | PNS error ERROR_VOIP | 111 | VOIP error ERROR_CALL_NO_ANSWER | 112 | ERROR_CALL_NO_ANSWER ERROR_INTEGRITY | 113 | Mobile application fatal integrity error. ARG_GUI_HEADER | 201 | The transaction title. ARG_GUI_TEXT | 202 | The transaction details. ARG_VOICE_PROMPT | 203 | A voice prompt, used in a scenario with the highest risk level. ARG_VOICE_LANG | 204 | The language of the voice prompt. ARG_MSISDN | 205 | The phone number. ARG_AMOUNT | 206 | The amount of the transaction. ARG_AMOUNT_CURRENCY | 207 | The currency of the amount. ARG_CREDITOR_NAME | 208 | The creditor's name. ARG_CREDITOR_ACCOUNT | 209 | The creditor's account number. ARG_CREDITOR_BANK | 210 | The creditor's bank name. ARG_GUI_DATA | 211 | Any data for UI. For example in JSON format. INTEGRITY_HONEYPOT | 301 | Integrity check: Honeypot is triggered. INTEGRITY_OVERLAY | 302 | Integrity check: Overlay window present. INTEGRITY_ROOTED | 303 | Integrity check: Device is rooted. INTEGRITY_ACCELEROMETER | 304 | Integrity check: Unusual accelerometer pattern. INTEGRITY_CODE | 305 | Integrity check: Code block hash sum check failure. INTEGRITY_WATERMARK | 306 | Integrity check: Watermark integrity check. INTEGRITY_SCREENSHOT_CLIENT_DISABLED | 307 | Integrity check: Screenshot functionality is disabled by a client. INTEGRITY_SCREENSHOT_UNSUPPORTED | 308 | Integrity check: Screenshot functionality is not supported on this device. INTEGRITY_SCREENSHOT_DISABLED | 309 | Integrity check: Screenshot functionality is disabled on server. INTEGRITY_SYSTEM_ALERT_WINDOW | 310 | Integrity check: System alert window is detected, this code notifies if there is probability that a malware is installed. INTEGRITY_CLIENT_WATERMARK | 311 | Integrity check: Watermark integrity check. This artifact is generated by a mobile device in case the devise checks the watermark integrity (for example, in low-bandwidth case, when the screenshot is disabled). Probably this integrity should have less weight then INTEGRITY_WATERMARK which is generated by the PSS. INTEGRITY_STORAGE | 312 | Integrity check: Secure storage is in a inappropriate state (for example if the secure storage was copied to another device). RESULT_CANCEL | 401 | Auth result cancel. RESULT_PIN | 402 | Auth result PIN. RESULT_TAN | 403 | Auth result TAN. RESULT_OK | 404 | Auth result OK. RESULT_BIOMETRIC_OK | 405 | Auth result bio-metric OK. RESULT_PAYMENT_CARD | 411 | Auth result payment card information. DATA_SCREENSHOT | 1101 | Screenshot. DATA_CODE_BLOCK_HASH | 1102 | Hash of a code block. DATA_SYSTEM_INFO | 1103 | System information of a client device. DATA_CODE_BLOCK_CALL_STACK | 1104 | Call stack of code block calls.

    Session Artifact

    Attribute | Type | Description ------------------------------------------------------------------------------------ type | Session Artifact Type | Type of an artifact (see Session Artifact Type above) params | | Artifact optional params

    5.4 User Answer

    Every authorization request will require an answer from the user authorizing that request. The User Answer table below represents fields that contains details about an authorization request and response a user gives to that authorization request.

    Attribute | Type | Description ------------------------------------------------------------------------------------ type | Session Artifact Type | Type of an artifact (see Session Artifact Type above) value | Base64 | The value is a concatenation of the payload (for example, PIN) and a random nonce added for additional entropy. This value is encrypted on the pubSPS key.

    Note on "value" attribute

    The type of the payload depends on the type of the artifact. The following variants are available:

    • In case of type RESULT_OK the value field will contain the following data: EpubSPS[YES:nSPS], if the 'OK' button was pressed by the user.
    • In case of type RESULT_CANCEL the value field will contain the following data: EpubSPS[NO:nSPS], if the 'CANCEL' button was pressed by the user.
    • In case of type RESULT_PIN the value field will contain the following data: EpubSPS[PIN:nSPS], where the PIN is a number entered by the user.
    • In case of type RESULT_TAN the value will contain the following data: EpubSPS[TAN:nSPS], where the TAN is a number entered by the user.
    • In case of type RESULT_BIOMETRIC_OK the value field will contain the following data, EpubSPS[<BIOMETRIC TYPE>:nSPS].

    If the user verified with a biometric sensor. <BIOMETRIC TYPE> may be one of the following:

    • FINGERPRINT - if the user was verified by their fingerprint
    • FACE3DMAP - if the user was verified by their face
    • EYEPRINT - if the user was verified by their eye-print
    • PASSCODE - if the user was verified by a backup password instead of biometric sensor
    • UNKNOWN - if the mobile application could not determine the biometric type
    • <PIN> (a number entered by the user) - if the user's device does not support biometric functionality but the user accomplished a FALLBACK scenario - AUTH_PIN
    • In case of type RESULT_PAYMENT_CARD the value will contain the following data: EpubSPS[PAN:MM:YY:CVV:CARDHOLDER:nSPS].

    In case of type RESULT_PAYMENT_CARD the value will contain the following data: EpubSPS[PAN:MM:YY:CVV:CARDHOLDER:nSPS].

    *EpubSPS["x"] - This is an encrypted value based on the x, which includes the user's response.

    5.5 Server Prepare Client

    Server Prepare Client Request

    Wrapped | Attribute | Type | Description -------------------------------------------------------------------- SSL/TLS | version | Integer | Version of the PSA | requestId | String | Identifier of this request | pubSPS | Base64 | The public key that encrypts the communication between the PSA and the SPS

    Server Prepare Client Request in XSD

    <xs:element name="ServerPrepareClientRequest" type="tns:ServerPrepareClientRequest"/> <xs:complexType name="ServerPrepareClientRequest"> <xs:sequence> <!-- Version of the PSA. --> <xs:element name="Version" type="xs:string"/> <!-- Identifier of this request. --> <xs:element name="RequestId" type="xs:string"/> <!-- The public key that encrypts the communication between the PSA and the SPS. --> <xs:element name="PubSPS" type="xs:base64Binary"/> <!-- Application type. --> <xs:element name="AppType" type="tns:AppType"/> <!-- Identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> </xs:sequence> </xs:complexType>

    Server Prepare Client Response in XSD

    Wrapped | Attribute | Type | Description -------------------------------------------------------------------------------------- SSL/TLS | requestId | Integer | Identifier of the request that generated this response. SSL/TLS | installationID | String | The identifier for this installation. SSL/TLS | pubPSS | Base64 | The public key that encrypts the communication between the PSA and the SPS SSL/TLS | body | Base64 | The identifier for this installation. SSL/TLS | status | Response Status | Returns Response Status (check response status above)

    <xs:element name="ServerPrepareClientResponse" type="tns:ServerPrepareClientResponse"/> <xs:complexType name="ServerPrepareClientResponse"> <xs:sequence> <!-- Identifier of the request that generated this response. --> <xs:element name="RequestId" type="xs:string"/> <!-- The identifier for this installation. --> <xs:element name="InstallationId" type="xs:string"/> <!-- Response status. --> <xs:element name="Status" type="tns:ResponseStatus"/> <!-- The public key that encrypts the communication between the PSA and the PSS. --> <xs:element name="PubPSS" type="xs:base64Binary"/> <!-- Identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> </xs:sequence> </xs:complexType>

    Batch Server Prepare Client Request

    Wrapped | Attribute | Type | Description ------------------------------------------------------------------------------------- SSL/TLS | Requests | Server Prepare Client Request | List of requests. | NSPS | String | Random data to ensure entropy of this message.

    Batch Server Prepare Client Request in XSD

    <xs:element name="BatchServerPrepareClientRequest"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerPrepareClientRequest" type="tns:ServerPrepareClientRequest" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

    Batch Server Prepare Client Response

    Wrapped | Attribute | Type | Description ----------------------------------------------------------------------------------------- SSL/TLS | Responses | Server Prepare Client Response | List of responses. | NSPS | String | Random data to ensure entropy of this message.It should be same as the request value.

    Batch Server Prepare Client Response in XSD

    <xs:element name="BatchServerPrepareClientResponse"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerPrepareClientResponse" type="tns:ServerPrepareClientResponse" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

    5.6 Server Start Session

    Server Start Session Request

    Wrapped | Attribute | Type | Description --------------------------------------------------------------------------------------------------------- SSL/TLS | TenantId | String | Identifier of the request that generated this response. SSL/TLS | AppExteranlId | String | The identifier for this installation. SSL/TLS | SessionExteranlId | String | The public key that encrypts the communication between the PSA and the SPS SSL/TLS | SessionType | Session Type (see Session Type above) | Type of the session. SSL/TLS | SessionArguments | Session Artifact (see Session Artifact above)| Session arguments (artifacts with the ARG_... prefix).

    Server Start Session Request in XSD

    <xs:element name="ServerStartSessionRequest" type="tns:ServerStartSessionRequest"/> <xs:complexType name="ServerStartSessionRequest"> <xs:sequence> <!-- Identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> <!-- Application external identifier. --> <xs:element name="AppExternalId" type="xs:string"/> <!-- A unique session identifier. It identifies a session and ensures entropy of this message. --> <xs:element name="SessionExternalId" type="xs:string"/> <!-- Type of the session. --> <xs:element name="SessionType" type="tns:SessionType"/> <!-- Session arguments (artifacts with the ARG_... prefix). --> <xs:element name="SessionArguments" type="tns:SessionArguments"/> </xs:sequence> </xs:complexType>

    Server Start Session Response

    Wrapped | Attribute | Type | Description -------------------------------------------------------------------- SSL/TLS | TenantId | String | Identifier of a tenant. | SessionExteranlId | String | A unique session identifier. It identifies a session and ensures entropy of this message. | Status | Response Status | Response status (see Response Status session above).

    Server Start Session Response in XSD

    <xs:element name="ServerStartSessionResponse" type="tns:ServerStartSessionResponse"/> <xs:complexType name="ServerStartSessionResponse"> <xs:sequence> <!-- Identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> <!-- A unique session identifier. It identifies a session and ensures entropy of this message. --> <xs:element name="SessionExternalId" type="xs:string"/> <!-- Response status.--> <xs:element name="Status" type="tns:ResponseStatus"/> </xs:sequence> </xs:complexType>

    Batch Server Start Session Request

    Wrapped | Attribute | Type | Description ------------------------------------------------------------------------------------ SSL/TLS | Requests | Server Start Session Request | List of requests. | NSPS | String | Random data to ensure entropy of this message.

    Batch Server Start Session Request in XSD

    <xs:element name="BatchServerStartSessionRequest"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerStartSessionRequest" type="tns:ServerStartSessionRequest" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

    Batch Server Start Session Response

    Wrapped | Attribute | Type | Description ------------------------------------------------------------------------------------ SSL/TLS | Responses | Server Start Session Response | List of responses. | NSPS | String | Random data to ensure entropy of this message. It should be same as the request value.

    Batch Server Start Session Response in XSD

    <xs:element name="BatchServerStartSessionResponse"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerStartSessionResponse" type="tns:ServerStartSessionResponse" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

    5.7 Server Check Session Status

    A synchronous request between your server and Okaythis server that checks the authorization status of a session – Your server should perform this call to check session statuses.

    Server Check Session Status Request

    Wrapped | Attribute | Type | Description -------------------------------------------------------------------- SSL/TLS | TenantId | String | Identifier of a tenant. | SessionExteranlId | String | The identifier of a session.

    Server Check Session Status Request in XSD

    <xs:complexType name="ServerCheckSessionStatusRequest"> <xs:sequence> <!-- The identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> <!-- The identifier of a session. --> <xs:element name="SessionExternalId" type="xs:string"/> </xs:sequence> </xs:complexType>

    Server Check Session Status Response

    Wrapped | Attribute | Type | Description -------------------------------------------------------------------- SSL/TLS | TenantId | String | Identifier of a tenant. SSL/TLS | SessionExteranlId | String | The identifier of a session. SSL/TLS | Artifacts | Session Artifact | Artifacts of a session (See Session Artifact above). SSL/TLS | Status | Response Status | Response status (See Response Status above).

    Server Check Session Status Response in XSD

    <xs:complexType name="ServerCheckSessionStatusResponse"> <xs:sequence> <!-- The identifier of a tenant. --> <xs:element name="TenantId" type="xs:long"/> <!-- The identifier of a session. --> <xs:element name="SessionExternalId" type="xs:string"/> <!-- Artifacts of a session. --> <xs:element name="Artifacts" type="tns:SessionArguments"/> <!-- Response status. --> <xs:element name="Status" type="tns:ResponseStatus"/> </xs:sequence> </xs:complexType>

    Batch Server Check Session Status Request

    Wrapped | Attribute | Type | Description ----------------------------------------------------------------------------- SSL/TLS | Requests | Server Check Session Status Request | List of requests. | NSPS | String | Random data to ensure entropy of this message.

    Batch Server Check Session Status Request in XSD

    <xs:element name="BatchServerCheckSessionStatusRequest"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerCheckSessionStatusRequest" type="tns:ServerCheckSessionStatusRequest" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

    Batch Server Check Session Status Response

    Wrapped | Attribute | Type | Description ---------------------------------------------------------------------------------- SSL/TLS | Requests | Server Check Session Status Request | List of requests. | NSPS | String | Random data to ensure entropy of this message. It should be same as the request value.

    Batch Server Check Session Status Response in XSD

    <xs:element name="BatchServerCheckSessionStatusResponse"> <xs:complexType> <xs:sequence> <!-- Random data to ensure entropy of this message. --> <xs:element name="NSPS" type="xs:string"/> <!-- List of requests. --> <xs:element name="ServerCheckSessionStatusResponse" type="tns:ServerCheckSessionStatusResponse" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>