A Easy Step by Step Guide on How to get started using the GSMA OneAPI Gateway

1. GSMA OneAPI Gateway
It's a Cross Carrier play
Here's where APIs get really exciting!
Confidential 1

2. OneAPI — Registration
1. Register at:
https://oneapi-gw.gsma.com
2. Confirm email
3. Log in
Provides access to dashboard and developer
documentation
Confidential 2

3. Creating an Application
Click on
Company Name
Log In Go to Dashboard
in Developer
Profiles
Complete the Click ‗Create
Enter application form and click Application‘
name ‗create
application‘ Bottom of page
Add test phone Click ―Create
numbers Application‖
Confidential 3

4. Manage Application
You can find this page
from the Dashboard:
1. Go to Dashboard
2. 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 4

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 5

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 6

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 7

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

9. RESTClient
Confidential 9

10. APIs Supported
 Sending SMS from short code to phone
 Receiving SMS (to short code)
 Location (latitude/longitude)
 Payment — Charge to phone bill
Confidential 10

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 11

12. SMS Send JSON Example
{
"outboundSMSMessageRequest":
{
"address": ["tel:+16045551212"],
"clientCorrelator": "10002",
"outboundSMSTextMessage":
{ "message": "Test SMS from 7511" },
"senderAddress": "tel:7511",
"senderName": "Super Send"
}
}
Confidential 12

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 13

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_v
2_0/routing/2_0/smsmessaging/outbound/tel:7511/requ
ests/222405168/deliveryInfos",
"deliveryInfo" : [ {
"address" : "tel:+16045551212",
"deliveryStatus" : "DeliveredToNetwork"
} ] …
Confidential 14

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 15

16. Location Response
https://oneapi-gw.gsma.com/location/2_0/location/
queries/location?address=tel%3A%2B16045551212&requestedAccur
acy=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 16

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.1
Content-Type: application/x-www-form-urlencoded
address=tel%3A%2B16045551212&callbackUrl=http%3A%2F%2
Fwww.example.com
Confidential 17

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 18

19. Location API Example
5. Retrieve location
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 19

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 20

21. Payment Example
1. Create Payments Sandbox Group
https://oneapi-gw.gsma.com
/sandboxdataservice/Payment_Sandbox
2. Add phone numbers to group
https://oneapi-gw.gsma.com
/sandboxdataservice/Payment_Sandbox/tel%3A
%2B16045551212
Confidential 21

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 22

23. Payment Example
2. Call Payment function API
https://oneapi-gw.gsma.com/sandboxpayment/
2_1/payment/tel%3A%2B16045551212/transactions/amount
Confidential 23

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%252B131
07486358/transactions/amount/REF-005-175",
"serverReferenceCode": "REF-005-175",
"transactionOperationStatus": "CHARGED"
Confidential } 24
}

25. Payment Example
4. Check payment request status
https://oneapi-gw.gsma.com/payment/2_1/payment/
tel%3A%2B16045551212/transactions/amount/REF-005-175
Confidential 25

26. Speakers & Your Developer Evangelists
 Caroline Lewko
 Bill Lee
 David O‘Neill
Confidential 26

27. http://bit.ly/oneapi-usage-notes
http://www.slideshare.net/oneapilive/using-the-gsma
-oneapi-gateway
Confidential 27