Tim Engineering

Tim does not authorize us to authenticate and charge the user directly. In this case, the user must go through a Engineering's WebView in order to be authenticated. After the authentication, Engineering will make a callback to Kiwi, informing some authentication parameters that Kiwi will send to SBS. With theses parameters, SBS is able to make a create subscription call to Tim. Asynchronously, Tim will inform SBS that the subscription was created, and SBS will inform kiwi the same thing. When this callback arrives, Kiwi will register and link the subscription.

Headers

All the calls to Kiwi's APIs must inform the following header:

x-kiwi-application-key: YOUR_APP_APPLICATION_KEY

Starting authentication

On this step, the client will ask Kiwi to build a URL to be used on a WebView. The request is the following:

POST to https://api.kwsdk.io/api/1.0/carrier/tim/start_oauth

Request Body:

{
"app_install_id" : "CAE62616-F025-47D8-874B-859E8FA93034",
"user_id" : "612F5369-314E-45A1-BEC9-49C635534687",
"msisdn" : "5519981234567",
"sku" : "com.movile.your.sku"
}

Response Body:

{
 "status": 1,
 "status_message": "Success!",
 "auth_url": "https://timUrl?redirectUri=https://tools.kwsdk.io/timRedirect"
}

Possible Status are:

• 1 - Success

• 100 - Invalid Parameters

• 101 - Missing Configuration

• -1 Unknown Error

Parsing Authentication Result

After the user authenticates on the WebView, Engineering will redirect the user to a Kiwi's URL. This URL should not be loaded on the WebView, instead, the client should intercept it, close the webView and extract the result from the parsed URL.

The URL will be on the following format:

kwauth://timcarrier?status=1&status_message=success

Possible Status are:

• 1 - Success

• 100 - Invalid Parameters

• 101 - Missing Configuration

• 500 - Error performing auth

• -1 Unknown Error

If the status is success, asynchronous callbacks will happen between Tim, SBS and Kiwi, and the new subscription will be linked to the current kiwi's userId. So, the client must perform a profile call in order to check the new subscription. Since the flow is asynchronous, a good practice would be to enable the premium access to the user for the rest of the session, while the profile doesn't return a subscription.