Confidential 1

GSMA OneAPI Gateway

It's a Cross Carrier play

Here's where APIs get really exciting!

Confidential 2

OneAPI — Registration

1. Register at:https://oneapi-gw.gsma.com

2. Confirm email3. Log in

Provides access to dashboard and developer documentation

Confidential 3

Creating an Application

Confidential 4

Manage Application

You can find this page from the Dashboard:

1. Go to Dashboard2. Click on the company

name link below Developer Profiles (bottom of page)

3. Click on the Manage Application button next to your application name.

Confidential 5

Application Specific Info

Note the two application profile buttons: “Endpoints” — Important application settings necessary

for using the APIs “Manage Whitelist” — Phone numbers for testing with

APIs

Confidential 6

Necessary Information

Application Profile — Endpoints– Application User Name & Application Password– The URI prefixes (excluding the “.*” suffix, shown, if

any) for each API-type PDF documents describing API sets’ usage

– “Common Information Guide” some error codes– “Sandbox Data service” prereq for Payments APIs

described in “Payment Developer Guide”– “Privacy Developer Guide” prereq for Location APIs

described in “Terminal Location Developer Guide”

Confidential 7

API Protocol

HTTP / REST (mostly) HTTP Basic Access Authentication Form-data or JSON Input XML or JSON output Some APIs Accept Callback URIs

Confidential 8

Tools

curl — Unix, Linux, OSX, cygwin/Win RESTClient — Firefox plug-in Chrome debug console — Chrome Browser (GET method testing) Coding

Confidential 9

RESTClient

Confidential 10

APIs Supported

Sending SMS from short code to phone Receiving SMS (to short code) Location (latitude/longitude) Payment — Charge to phone bill

Confidential 11

Send SMS to Phone

1. Add test phone number to Whitelist

2. Create request JSON in a file

3. Call HTTP

4. Receive Transaction ID

Use Transaction ID to check delivery status

Confidential 12

SMS Send JSON Example

{ "outboundSMSMessageRequest": { "address": ["tel:+16045551212"], "clientCorrelator": "10002", "outboundSMSTextMessage":

{ "message": "Test SMS from 7511" }, "senderAddress": "tel:7511", "senderName": "Super Send" }}

Confidential 13

SMS Send Response

https://oneapi-gw.gsma.com/smssend/2_0/smsmessaging/outbound/tel%3A7511/requests{ "resourceReference" : { "resourceURL" :

"https://oneapi-gw.gsma.com:443 /SendSmsService/OneAPI_REST_v2_0 /routing/2_0/smsmessaging/outbound /tel:7511/requests/222405168"

}}

Confidential 14

Checking SMS Status

https://oneapi-gw.gsma.com/smssend/2_0/smsmessaging/outbound/tel:7511/requests/222405168/deliveryInfos{ "deliveryInfoList" : { "resourceURL" :

"https://oneapi-gw.gsma.com:443/SendSmsService/OneAPI_REST_v2_0/routing/2_0/smsmessaging/outbound/tel:7511/requests/222405168/deliveryInfos",

"deliveryInfo" : [ { "address" : "tel:+16045551212", "deliveryStatus" : "DeliveredToNetwork" } ] …

Confidential 15

Location Query

1. Whitelist phone number

2. Get permission to retrieve position (once only, per app, privacy API)

3. User authorizes

4. Retrieve user’s location

Confidential 16

Location Response

https://oneapi-gw.gsma.com/location/2_0/location/queries/location?address=tel%3A%2B16045551212&requestedAccuracy=5000{ "terminalLocationList" : { "terminalLocation" : [ { "address" : "tel:+16045551212", "locationRetrievalStatus" : "Retrieved", "currentLocation" : { "latitude" : 49.248688, "longitude" : -123.19475, "altitude" : 0.0, "accuracy" : 769, "timestamp" : "2012-05-30T17:41:37.000-04:00" } } ] …

Confidential 17

Location API Example

1. Add phone number to Whitelist

2. Ask permission to retrieve location

POST https://oneapi-gw.gsma.com/privacy HTTP/1.1Content-Type: application/x-www-form-urlencodedaddress=tel%3A%2B16045551212&callbackUrl=http%3A%2F%2Fwww.example.com

Confidential 18

Location API Example

3. User responds to text with “ALLOW”4. Check status (or use callback)https://oneapi-gw.gsma.com/privacy?address=tel%3A%2B16045551212<?xml version="1.0"

encoding="UTF-8"standalone="yes"?><PrivacyResponse status="ALLOWED"/>

All future location requests are enabled for the app for that user.

Confidential 19

Location API Example

5. Retrieve locationhttps://oneapi-gw.gsma.com/location/2_0/location/queries/location?address=tel%3A%2B16045551212&requestedAccuracy=5000 { "terminalLocationList" : { "terminalLocation" : [ { "address" : "tel:+16045551212", "locationRetrievalStatus" : "Retrieved", "currentLocation" : { "latitude" : 49.248688, "longitude" : -123.19475, "altitude" : 0.0, "accuracy" : 769, "timestamp" : "2012-05-30T17:41:37.000-04:00" } } ] }}

Confidential 20

Payment API

1. Create Payments Sandbox Group (if not already created)

2. Add “subscribers” to the group, by phone number

3. Call Payment API to “charge” money

4. Call Payment API to detect status

Confidential 21

Payment Example

1. Create Payments Sandbox Grouphttps://oneapi-gw.gsma.com/sandboxdataservice/Payment_Sandbox

2. Add phone numbers to grouphttps://oneapi-gw.gsma.com/sandboxdataservice/Payment_Sandbox/tel%3A%2B16045551212

Confidential 22

Payment Example

1. Create payment request JSON{ "amountTransaction": { "clientCorrelator": "100003", "endUserId": "tel:+16045551212", "paymentAmount": { "chargingInformation": { "amount": "10.01", "currency": "CAD", "description": [”Our product"] }, "chargingMetaData" : { "onBehalfOf" : "Viafo Inc", "purchaseCategoryCode" : "Game", "taxAmount" : "0" } }, "referenceCode": "REF-NJD-12345a", "transactionOperationStatus": "CHARGED" }}

Confidential 23

Payment Example

2. Call Payment function API

https://oneapi-gw.gsma.com/sandboxpayment/2_1/payment/tel%3A%2B16045551212/transactions/amount

Confidential 24

Payment Example

3. Payment call’s response{ "amountTransaction": { "clientCorrelator": "1234569", "endUserId": "tel:+13107486358", "paymentAmount": { "chargingInformation": { "amount": 5.0, "currency": "CAD", "description": [ "Alien Invaders Game" ] }, "chargingMetaData": { "onBehalfOf": "Example Games Inc", "purchaseCategoryCode": "Game", "taxAmount": 0 }, "totalAmountCharged": 5.0 }, "referenceCode": "REF-005", "resourceURL":

"https://oneapi-gw.gsma.com:443/PaymentService/OneAPI_REST_v2_1/sandbox/2_1/payment/tel%253A%252B13107486358/transactions/amount/REF-005-175",

"serverReferenceCode": "REF-005-175", "transactionOperationStatus": "CHARGED" }}

Confidential 25

Payment Example

4. Check payment request statushttps://oneapi-gw.gsma.com/payment/2_1/payment/tel%3A%2B16045551212/transactions/amount/REF-005-175

Confidential 26

Speakers & Your Developer Evangelists

Caroline Lewko Bill Lee David O’Neill

Confidential 27

http://bit.ly/oneapi-usage-notes

http://www.slideshare.net/oneapilive/using-the-gsma-oneapi-gateway