Want to provide feedback?

Write to docs@telesign.com.

Transaction Callback Service

The TeleSign Transaction Callback web service sends the transaction status of a Verify service request (Voice Verify, SMS Verify, Smart Verify). As opposed to the Get Status API, where you send one or more GET requests to the /v1/verify/ resource to learn about the status of individual transactions, the Transaction Callback web service makes more efficient use of network system resources (for example, bandwidth or server load), and is best suited to TeleSign customers that have a high volume of SMS or voice transactions they want to retrieve status information for.

NOTE:

You must use standard ports for transaction callbacks to work properly. For HTTPS (transport layer security (TLS)), the default standard port is 443.

NOTE 2:

This API is only for use with SMS Verify, Voice Verify, and Smart Verify.

Service Setup

To use the Transaction Callback service:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign. Fields that will be sent back with the JSON formatted response include:
  • Custom Authorization header (refer to section Authenticate Callbacks from TeleSign below).
  • Reference ID
  • Sub-Resource
  • Errors
  • Status: Updated On
  • Status: Code
  • Status: Description
  • Verify: Code State
  • Verify: Code Entered
  • Verify: Code Submitted
  • Submit Timestamp
  • Additional Info: MNC (see NOTE 2)
  • Additional Info: MCC (see NOTE 2)
  • Additional Info: Price
  • Additional Info: Currency
NOTE:

For mission critical applications, TeleSign recommends that you provide redundancy by implementing two URIs instead of one.

NOTE 2:

Additional Info is an optional parameter that returns Mobile Network Code (MNC) and Mobile Country Code (MCC). You must request that your Customer Success Manager enable the Additional Info parameter if you want it returned.

  1. Provide TeleSign with your private URI.
  2. Allow 1 business day for setup to be completed.
  3. You will receive callback notifications after both of the following occur:
    • A verification transaction completes
    • TeleSign determines the final status of the transaction (refer to the section Transaction Status Codes on the Codes, Languages, and Timezones page for a list of status codes that may be returned).
  4. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt. After that, to obtain verification information, your application should resort to using the Get Status (pull) mechanism, described above.
Contents of a Successful Callback Notification
{
  "status": {
    "updated_on": "2019-09-20T12:43:46.710291Z",
    "code": 200,
    "description": "Delivered to handset"
  },
  "submit_timestamp": "2019-09-20T12:43:45.339000Z",
  "errors": [],
  "verify": {
    "code_state": "VALID",
    "code_entered": "12345"
  },
  "sub_resource": "sms",
  "reference_id": "C5B53ACC84EC01048994FE7AADF900CD",
  "additional_info": {
    "message_parts_count": 1,
    "price": "0.5112",
    "mnc": "05;09",
    "mcc": "220",
    "currency": "USD"
  }
}

Here is a diagram of what the flow would look like, using SMS Verify for the example. The flow is the same for Voice Verify.

Authenticate Callbacks from TeleSign

You can authenticate callbacks for added security. You can learn more about these things here:

Transaction Callback Examples

Here is an example of a Verify Transaction Callback service post to your provided URL:

Example Verify Transaction Callback POST Body
Accept-Encoding: gzip, deflate
Authorization: Basic 78E5ACC9-83C1-4E25-BE21-44A0CA1D57B4:KdpP11dPeAUW/6IVRx30JA3FG1eCOFVoE8ojI8NqnTA=
Content-Length: 308
Content-Type: application/json
User-Agent: python-requests/2.9.1

{ 
  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200, "description": "Delivered to handset" 
   }, 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "verify": { 
     "code_state": "UNKNOWN", 
     "code_entered": null 
   }, 
   "sub_resource": "sms", 
   "reference_id": "2557312299CC1304904080F4BE17BFB4" 
}