Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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:

console enable transactional totp

Once this is enabled, end users will have the option to Scan a QR code from your application view in the Authy App.

Scan transactional TOTP QR code

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]=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.

Parameters

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.
        
        
        
        

        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:

        1. Sending the QR code as a base64 encoded image in your HTML
        2. 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.

        example transactional totp qr code
        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.

        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
        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.

        Parameters

        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.

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

        Every new Authy user must complete a verification before subsequent authentications can be done. Otherwise, see how to force verification of unregistered users here.

              
              
              
              
                    
                    
                    
                    
                    Rate this page:

                    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 browsing the Twilio tag on Stack Overflow.