Transactional Time-based One Time Passwords
Use this feature if you need to tie a one-time password with transaction data. It's specifically useful to comply with PSD2 Dynamic Linking to fulfill Strong Customer Authentication Requirement.
To enable this feature you need to enable it in your Application's settings in the Twilio Console:
Once this is enabled, end users will have the option to Scan a QR code from your application view in the Authy App.
This feature is only supported in the following versions of the Authy App. End users will have to update their mobile applications to the following versions:
- iOS 22.3+
- Android 23.7+
Create a Transactional QR code
First, create a transaction string with the following format. This will be encoded in the QR code.
txotp://totp?message=msg&details[key1]=value1&hidden_details[key1]=value1message, details, and hidden_details are mixed with a seed to generate a unique TOTP. The same exact parameters are required to successfully verify the token. Order of parameters is not important but details will be displayed in the same order they are sent.
Parameters should be URL encoded.
Parameters
| Name | Description |
|---|---|
messageString |
Short description about the transaction |
detailsHash |
Dictionary containing any details related to the transaction you want the end user to see. |
hidden_detailsHash (optional) |
Dictionary containing any details related to the transaction you don't necessary want the end user to see. |
The recommended length for a transaction string is under 300 characters. It is not recommended to exceed 600 characters. Longer transaction strings create more complicated QR codes and cause slower scanning, especially in older smartphones. This example's length is 228 characters.
Generate the QR Code from the transaction string
Note: we do not recommend storing the QR code since it can potentially leak sensitive data. Instead, we recommend:
- Sending the QR code as a base64 encoded image in your HTML
- Generating the QR code from your application with a library like github.com/skip2/go-qrcode
After the QR code is generated display it so your user can scan it with the Authy App. Here is a sample QR code generated from the example transaction string.
Verify a Transactional One-Time Password
To verify a transactional one-time password, pass in the user provided token, the user authy_id and the transaction message, details and hidden_details. Twilio will use HTTP status codes for the response.
GET https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}URL
| Name | Description |
|---|---|
FORMATString |
The format to expect back from the REST API call. json or xml. |
TOKENInteger |
The 6-8 digit transactional TOTP you are verifying. |
AUTHY_IDString |
The Authy ID for the user validating the token. |
Parameters
| Name | Description |
|---|---|
messageString |
Short description about the transaction |
detailsHash |
Dictionary containing any details related to the transaction you want the end user to see. |
hidden_detailsHash (optional) |
Dictionary containing any details related to the transaction you don't necessary want the end user to see. |
HTTP Status Codes
| Code | Message |
|---|---|
| 200 | "Token is valid." Until you successfully verify a token for a new user, this will return 200 (see Note)*. |
| 401 | "Token is invalid." Invalid token. If you wish to verify the token anyway, pass force=true (see Note)*. |
| 401 | "The param details can not have empty values." For example a request with ?details[Name]=&details[Surname]=Doe will fail. |
| 401 | "The param hidden details can not have empty values." For example a request with ?hidden_details[ID]=&hidden_details[Account]=690239 will fail. |
Response
| Name | Description |
|---|---|
tokenString |
Either "is valid" or "is invalid" (🏢 not PII) |
successString |
"true" if the code was valid. Please note this field is a String and not a Boolean. (🏢 not PII) |
deviceObject |
An object including some details about the device used to get or generate the token. The fields included in the device object are: city, region, country, ip, registration_city, registration_region, registration_country, registration_ip, registration_date, os_type, last_account_recovery_at and id. (📇 PII) |
Every new Authy user must complete a verification before subsequent authentications can be done. Otherwise, see how to force verification of unregistered users here.
An invalid token will return the following error message:
{
"message":"Token is invalid",
"token":"is invalid",
"success":false,
"errors":{
"message":"Token is invalid"
},
"error_code":"60020"
}Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
