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.
Info
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+
First, create a transaction string with the following format. This will be encoded in the QR code.
_10txotp://totp?message=msg&details[key1]=value1&hidden_details[key1]=value1
message, 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.
| Name | Description |
|---|---|
message String | Short description about the transaction |
details Hash | Dictionary containing any details related to the transaction you want the end user to see. |
hidden_details Hash (optional) | Dictionary containing any details related to the transaction you don't necessary want the end user to see. |
_10txotp://totp?message=Approve+money+transaction&details[Amount]=1000+Euros&details[To]=John+Doe&details[Destination+Account]=29385&details[Source+Account]=98381&details[Reason]=transfer+money&hidden_details[Transaction+ID]=T2293
Info
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.
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.
Your QR code may not look exactly like the example above when you recreate it. Test if the example works by scanning your QR code with the Authy app on your smartphone.
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.
_10GET https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}
| Name | Description |
|---|---|
FORMAT String | The format to expect back from the REST API call. json or xml. |
TOKEN Integer | The 6-8 digit transactional TOTP you are verifying. |
AUTHY_ID String | The Authy ID for the user validating the token. |
| Name | Description |
|---|---|
message String | Short description about the transaction |
details Hash | Dictionary containing any details related to the transaction you want the end user to see. |
hidden_details Hash (optional) | Dictionary containing any details related to the transaction you don't necessary want the end user to see. |
| 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. |
| Name | Description |
|---|---|
token String | Either "is valid" or "is invalid" (🏢 not PII) |
success String | "true" if the code was valid. Please note this field is a String and not a Boolean. (🏢 not PII) |
device Object | 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) |
Warning
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:
_10{_10 "message":"Token is invalid",_10 "token":"is invalid",_10 "success":false,_10 "errors":{_10 "message":"Token is invalid"_10 },_10 "error_code":"60020"_10}