Transactional Time-based One Time Passwords

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.

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.

Expand image

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.

GET https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
options = {
9
    "message": "Approve money transaction",
10
    "details[Amount]": "1000 Euros",
11
    "details[To]": "John Doe",
12
    "details[Destination Account]": 29385,
13
    "details[Source Account]": 98381,
14
    "details[Reason]": "transfer money",
15
    "hidden_details[Transaction ID]": "T2293"
16
}
17

18
verification = authy_api.tokens.verify(
19
    authy_id,
20
    token=1685105,
21
    options=options)
22

23
print(verification.ok())

1
{
2
  "message":"Token is valid.",
3
  "token":"is valid",
4
  "success":"true",
5
  "device":{
6
    "city":"Brooklyn",
7
    "country":"United States",
8
    "ip":"192.168.0.1",
9
    "region":"New York",
10
    "registration_city":"Medellín",
11
    "registration_country":"Colombia",
12
    "registration_ip":"192.168.0.3",
13
    "registration_method":"sms",
14
    "registration_region":"Antioquia",
15
    "os_type":"ios",
16
    "last_account_recovery_at":1498837117,
17
    "id":4854321,
18
    "registration_date":1551300946,
19
    "last_sync_date":1551301762
20
  }
21
}

An invalid token will return the following error message:

1
{
2
  "message":"Token is invalid",
3
  "token":"is invalid",
4
  "success":false,
5
  "errors":{
6
    "message":"Token is invalid"
7
  },
8
  "error_code":"60020"
9
}