Authentication
Try the API Explorer
APIs
SMS API
SMS Verify API
Bulk SMS API
Anonymous SMS API
Voice API
Voice Verify API
Phone Numbers API
PhoneID API
Score API
App Verify API
Get Status API
Completion API

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 in order for transaction callbacks to work properly. For HTTP, the default standard port would be 80, and for HTTPS (transport layer security (TLS)), the default standard port would be 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 Timeline
  • Additional Info: MNC (see NOTE 2)
  • Additional Info: MCC (see NOTE 2)
  • Additional Info: Price
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 Technical Account 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
{    
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",    
  "sub_resource": "call",    
  "errors": [],    
  "status": {       
    "updated_on": "Wed, 03 Oct 2012 14:51:28 +0000",       
    "code": 100,       
    "description": "Call answered"
   },
"additional_info": {
  "mnc": 03,
  "mcc": 220,
  "price": 0.0001 USD
   },
"verify": {       
  "code_state": "VALID",       
  "code_entered": "12345",       
  "code_submitted": "12345"    
   },    
"submit_timestamp": "Wed, 03 Oct 2012 14:50:43 +0000" 
} 

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" 
}