Redirecting the User to Authenticate
As covered under Token.io Basics, the requirement introduces the challenge of multi-factor authentication, efficiently accommodated using one of three models: (1) redirect, (2) decouple, or (3) embed. See Authentication for details on each of these models.
Otherwise, upon creating and storing the transfer token request, you're ready to redirect the customer to the user-selected bank via Token.io to authenticate and obtain consent.
Generate the Token Request URL
This can be a redirect from your browser page to the Token.io web app or, for mobile, you can use Token.io's App-to-App Redirect method. In both bases, you'll need to construct a URL or a mobile universal link that redirects the user from your web page or mobile app to the Token.io web app. This is done by appending the requestId of the stored request to Token.io's web app URL, which is as easy as:
// generate token request URL
return tokenClient.generateTokenRequestUrlBlocking(request-id);
The resulting token request redirect URL will look something like this:
https://web-app.token.io/request-token/rq:42w7yzgwJtN9fQVx78McJzEKiyU9:5zKtXEAq?
The request-id is shown in yellow.
You can specify a particular language by passing its language code (lang=country-code) as a query parameter, appended to the URL above, which the user can override in the Web App according to personal preference. Here's an example for passing the desired ISO 639-1 language code for German (de):
https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?
After generating the URL, you'll want to direct your front-end to visit it. There are a couple of ways to do this: (a) you can initiate a server-side or (b) bind the URL to a button in your UI that either redirects the customer to the Token.io web app in the current browser tab or launches a pop-up window. The request-id portion of the generated redirect URL associates your stored request with the result of the redirect.
Bind the Request Redirect to a Button
You can bind redirect URL generation to a button in your UI by taking these steps:
- Create the button.
- Create a TokenController to handle messages (onSuccess, onError).
- Bind the button to the controller with options for desktop: 'POPUP' (default = same browser window).
- Enable the button upon generating the redirect URL.
- onClick() redirect the user to the generated URL.
The following example offers merely one suggestion in Java on how to structure your pop-up/redirect functions and bind them to a "Token.io" button. You should implement a construct consistent with your user experience design practices.
// general construct in Java for the pop-up/redirect function
token.createRequest(
function(redirect) { // non-async function for redirect
// do some non-async actions here and execute
// redirect callback with url immediately after
redirect(url);
},
function(done, errorCallback) { // async function for popup
// do any async actions here and
// execute callback with url when done
done(url);
},
);
// create a redirect-only button
function createRedirectButton() {
var token = new window.Token({
env: 'sandbox',
});
// get button placeholder element
var element = document.getElementById(elementId);
// create the button
var button = token.createTokenButton(element, {
label: "Redirect Token Quick Checkout",
});
// create TokenController to handle messages
var tokenController = token.createController();
// bind the Token.io Button to the Token.io Controller when ready
tokenController.bindButtonClick(
button, // Token.io Button
token.createRequest(
function(redirect) {
redirect("/transfer", {
amount: 4.99,
currency: "EUR",
description: "Book",
});
}
),
function(done) { // redirect token request function
// go to transfer
done("/transfer"
+ "?amount=4.99¤cy=EUR"
+ "&description=Book");
},
function(error) { // bindComplete callback
if (error) throw error;
// enable button after binding
button.enable();
},
);
}
// create a button for both pop-up and redirect
function createRedirectButton() {
var token = new window.Token({
env: 'sandbox',
});
// get button placeholder element
var element = document.getElementById(elementId);
// create the button
var button = token.createTokenButton(element, {
label: "Redirect Token Quick Checkout",
});
// create TokenController to handle messages
var tokenController = token.createController();
// bind the Token.io Button to the Token.io Controller when ready
tokenController.bindButtonClick(
button, // Token.io Button
token.createRequest(
function(redirect) {
redirect("/transfer", {
amount: 4.99,
currency: "EUR",
description: "Book",
});
}
),
function(done) { // redirect token request function
// go to transfer
done("/transfer"
+ "?amount=4.99¤cy=EUR"
+ "&description=Book");
},
function(error) { // bindComplete callback
if (error) throw error;
// enable button after binding
button.enable();
},
);
}
Redirect to the TPP's Callback URL
Upon transfer to the Token.io web app, the customer is prompted to agree to Token.io's terms and conditions. If the customer accepts the , control is transferred to the customer-selected bank's login page or mobile app login screen to authenticate and authorize payment, whereupon a corresponding token is created and the user is returned to the TPP's callback URL specified in setRedirectUrl for the original request.
Covered in the next topic, callback handling depends on the bank-supported payment flow — Auth PLUS Transfer or Auth AND Transfer (see Payment Flows). If the bank supports the former, the callback URL will contain a tokenId, which you will have to redeem to receive payment. If the bank supports the latter, the bank automatically redeems the token and sends a transferId and transfer status in the callback.