Documentation

ZGateway API

Welcome to ZGateway Documentation

  • Created: 25 November, 2017
  • Update: 07 May, 2024

Introduction

ZGateway allow execute several kind of transactions like Air-Time TopUps, Data provisioning, SMS MT and others using our easy custom designed API.

  1. The ZGateway API contains the following methods.
    • HTML/assets – Contains all of the assets referenced.
    • getAuthToken – This method is responsible for the generation of a token for security.
    • executeTopUp – Request to process an air-time TopUp.
    • pushStatus – Notify to the customer the status of a TopUp transaction.
    • getStatus – Returns the status of the TopUp transaction.
    • getSmsStatus – Returns the status of the Sms transaction.
    • getBalance – Returns the remaining prepaid balance of an account.
    • getTopUpReport – Returns the history of TopUps.
    • carrierLookUp – Gets the carrier that belongs a mobile number. Deprecated
    • carrierLookUp V2 – Gets the carrier that belongs a mobile number.
    • executeDirectTopUp – Request to process an air-time TopUp.
    • sendSms V3 – Send Sms.
    • moSMSCallback – Notify the costumer the MOs Transaction.
    • sendSmsLight – Send Sms.
    • sendSmsFlash – Send Sms.
    • mtSMSCallback – Notify the costumer the MTs transaction.
    • executeTopUpCamp Request to process an air-time TopUp with sms confirmation.

Security

As part of Zorya’s security policies, for any method that you would like to use (executeTopUp, executeDirectTopup, getStatus, getSmsStatus, getBalance, getTopUpReport, executeTopUpCamp, carrierLookUp V2, sendSms V3, sendSmsLight or sendSmsFlash) you need a token. Use this token for each method that you want to instantiate. The token must be obtained through the getToken method. It’s mandatory that all requests that you need, use a header enrichment parameter: ZRTAuth , with the token value acquired. 



1.  request.EndPoint = "https://[ServiceURLTopUp]/api/getBalance";   

2.  request.Method = HttpVerb.GET;  

3.  request.ContentType = "application/json";   

4.  request.Header = "ZRTAuth";   

5.  request.HeaderValue = "d4d2089a5f49a7273a3be8e9d1fe403c3eeda304";
It has a validity of 24 hrs, after that time, you need to renew it.

API Methods

Documentation for RestFull API

getAuthToken

This method is responsible for the generation of a token to increase transaction security.

EndPoint

https://[SecurityURLAuth]/auth/api/getAuthToken/{clientID}/{securePassword}

HTTP Method

GET

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
securePassword String YES Client Password (Request it to your account manager)

Response

Parameter Data Type Description
zrtauth String Access token

Request Example

https://[SecurityURLAuth]/api/getAuthToken/1234-ABCD-1234/myPsw135

Request the [ServiceURLTopUp] to your account manager.

Response Example



1. {   

2.    "code": 200,   

3.    "message": "Auth Token generated successfully",   

4.    "response": {  

5.         "zrtauth": "sipx7YVFJ920220810"  

6.    },     

7.    "error": null  

8. }

getSmsStatus

Return the status of an SMS transaction.

EndPoint

https://[ServiceURLZGateway]/api/getSmsStatus/{clientID}/{txID}

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

GET

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
txID String YES Transaction ID generated in method: executeTopUp

Response

Parameter Data Type Description
txID Integer Transaction ID generated in method: executeTopUP
carrierID Integer Carrier identifier
carrierName String Carrier Name
mnc string Mobile Network Code
mcc String Mobile Country Code
msisdn String Mobile number with country code (example 525512345678)
cost Decimal SMS Amount
status String Transaction status (See Table 2 -Received or Rejected)
smsCount Integer Number of SMS charged
charactersCount Integer Number of characters charged
coding String Encoding used
sentOn DateTime DateTime Transaction datetime (MM-dd-yyyy HH:mm:ss)

Request Example

https://[ServiceURLZGateway]/api/getSmsStatus/1234-ABCD-1234/txID12345

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "Request of transaction Status Successful",   

4.      "response": {   

5.          "txID": "txID12345",   

6.          "carrierID ": 33401,   

7.          "carrierName ": "Telcel",

8.          "mnc ": "020",

9.          "mcc ": "334",

10.         "msisdn": "525512345678",   

11.         "cost": 0.20000,   

12.         "status": 103,   

13.         "smsCount": 1,   

14.         "charactersCount": 17,   

15.         "coding": "USC-2",   

16.         "sentOn": "01-11-2023T03:22:35",    

17.    }    

18.    "error": [

19.         null

20.    ]   

21. }

getBalance

Return an account remaining balance.

EndPoint

https://[ServiceURLZGateway]/api/getBalance/{clientID}

HTTP Method

GET

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)

Response

Parameter Data Type Description
clientID String Client ID (Request it to your account manager)
balance Decimal Account Remaining balance

Request Example

https://[ServiceURLZGateway]/api/getBalance/1234-ABCD-1234

Request the [ServiceURLZGateway] to your account manager.

Response Example



1. {   

2.      "code": 200,   

3.      "message": "Successfully Obtained Balance",   

4.      "response": {   

5.          "clientID": "1234-ABCD-1234",   

6.          "balance": 549,950.0500000000 

7.      },   

8.      "error": null   

9. }

executeTopUp

Request to process an Air-time TopUp.

EndPoint

https://[ServiceURLTopUp]/api/executeTopUp/

Request the [ServiceURLTopUp] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
MSISDN String YES Mobile number with country code
amount Decimal YES TopUp Amount

Response

Parameter Data Type Description
status String Transaction status (See Table 2 -Received or Rejected)
msisdn String Mobile number with country code (example 525512345678)
amount Decimal TopUp Amount
amountCurrency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String Transaction Detail
dateTimeTransaction DateTime dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)

Request Example



1. {   

2. "clientID": "1234-ABCD-1234",    

3. "MSISDN": "525512345678",   

4. "amount": 20.00  

5. }

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "TopUp Successfully Received",   

4.      "txID": "B9WN0dzTgTMdbosoU9Jp20220811",   

5.      "response": {    

6.          "status": 100,   

7.          "msisdn": "525512345678",   

8.          "amount": 20.00,   

9.          "amountCurrency": "MXN",   

10.         "cost": 20.01,   

11.         "detail": "Operation Received ",   

12.         "dateTimeTransaction": "2022-08-11T04:03:18"   

13.     },      

14.     "error": [

15.         null

16.     ]   

17. }

Response Failure Example



1. {

2.      "code": 400,

3.      "message": "Bad Request",

4.      "txID": "yY6K3yrHYbdAMX5gW00720220811",

5.      "response": null,

6.      "error": null

7. }

getTopUpReport

Returns a list of TopUps received in a period of time.

EndPoint

https://[ServiceURLTopUp]/api/getTopUpReport/{clientID}/{beginDate}/{endDate}

Request the [ServiceURLTopUp] to your account manager.

HTTP Method

GET

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
beginDate Date YES Initial date of transactions [MM-dd-yyyy]
endDate Date YES End date of transactions [MM-dd-yyyy]

Response

Parameter Data Type Description
txID Integer Transaction ID generated in method: executeTopUP
carrierID Integer Carrier identifier
msisdn String Mobile number with country code (example 525512345678)
amount Decimal TopUp Amount
amountCurrency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String Transaction Detail
dateTimeTransaction DateTime dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)
dateTimeStatus DateTime Last Status datetime (MM-dd-yyyyTHH:mm:ss)

Request Example

https://ServiceURLTopUp]/api/getTopUpReport/1234-ABCD-1234/08-09-2022/08-12-2022/

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "TopUp Report Successful Executed",   

4.      "count": 1,   

5.      "response": [   

6.          {   

7.              "txID": "oqxPyWDidLSVruFVxdI220220811",   

8.              "carrierId": 79,   

9.              "msisdn": "525512345678",   

10.             "amount": 30.00,   

11.             "amountCurrency": "MXN",   

12.             "cost": 0.1160,   

13.             "status": 0,   

14.             "detail": "ServiceProv: 188",   

15.             "dateTimeTransaction": "08-11-2022T03:22:35",   

16.             "dateTimeStatus": "08-11-2022T03:22:35"   

17.         }  

18.     ],   

19.     "error": [

20.         null

21.     ]   

22. }

executeDirectTopUp

Request to process an Air-time TopUp.

EndPoint

https://[ServiceURLTopUp]/api/executeDirectTopUp/

Request the [ServiceURLTopUp] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
ZCode String YES Product Code (See table 3)
amount Decimal YES TopUp Amount
MSISDN String (12 Characters) YES Mobile number with country code

Response

Parameter Data Type Description
status String Transaction status (See Table 2 -Received or Rejected)
msisdn String Mobile number with country code (example 525531371074)
amount Decimal TopUp Amount
amountCurrency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String Transaction Detail
dateTimeTransaction DateTime dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)

Request Example



1.  {   

2.  "clientID": "1234-ABCD-1234",    

3.  "MSISDN": "525545891076",   

4.  "amount": 20.00,  

5.  "ZCode":"TELTA"

6.  }

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "Direct TopUp Successfully Received",   

4.      "txID": "oWA7Os8WC8HIikj1vgS220220811",   

5.      "response": {           

6.          "status": 100,   

7.          "msisdn": "525545891076",   

8.          "amount": 20.00,   

9.          "amountCurrency": "MXN",   

10.         "cost": 20.01,   

11.         "detail": "Operation Received ",   

12.         "dateTimeTransaction": "2022-09-11T04:25:25"   

13.     },      

14.     "error": [

15.         null

16.     ]   

17. }

Response Failure Example



1. {

2.      "code": -312,

3.      "message": "Invalid ClientID",

4.      "txID": "hRmvPsvbLrXr2v94W7op20220811",

5.      "response": null,

6.      "error": null

7. }

executeTopUpCamp

Request to process an air-time TopUp with sms confirmation.

EndPoint

https://[ServiceURLTopUp]/

Request the [ServiceURLTopUp] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
campaign String YES Campaign code
msisdn String (12 Characters) YES Mobile number with country code

Response

Parameter Data Type Description
status String Transaction status (See Table 2 -Received or Rejected)
msisdn String Mobile number with country code (example 525512345678)
amount Decimal TopUp Amount
amountCurrency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String Transaction Detail
dateTimeTransaction DateTime dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)

Request Example



1. {

2. "msisdn": "525512345678",

3. "clientID": "XXXXXXX",

4. "campaign": "campaignTest1",

5. }

carrierLookUpDeprecated

Gets the carrier that belongs a mobile number.

EndPoint

https://[ServiceURLZGateway]/api/carrierLookUp/

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
MSISDN String YES Mobile number with country code

Response

Parameter Data Type Description
msisdn String Mobile number with country code (example 525531371074)
mcc String Mobile Country Code
mnc String Mobile Network Code
networkId String Network ID
serviceProviderId String Id Of Service Provider
serviceProviderDesc String Description of Service Provider
currency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String String Transaction Detail
dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)

Request Example

https://[ServiceURLZGateway]/api/carrierLookUp/



1. {   

2. "clientID": "1234-ABCD-1234",    

3. "MSISDN": "525545891076"   

4. }

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "CarrierLookUp Successfully Executed",   

4.      "txID": "FZRP5c3ewdvN24vntwaI20220810",   

5.      "response": {   

6.          "msisdn": "525545891076",

7.          "mcc": "334",

8.          "mnc": "020",

9.          "networkID": "188",

10.         "network": "Telcel",

11.         "serviceProviderID": "188",

12.         "serviceProviderDesc": "Telcel",

13.         "cost": 0.1160,

14.         "currency": "MXN",

15.         "detail": "Data obtained from central DB",

16.         "dateTimeTransaction": "08-09-2022T17:03:11"

17.     },

18.     "error": [

19.         null

20.     ]

21. }

Response Failure Example



1 {   

2.      "code": 400,

3.      "message": "Invalid Destination number",

4.      "txID": "mhXHC7APjGnBSeQwCVU620220210",

5.      "response": null,

6.      "error": null

7. }

carrierLookUp V2

Gets the carrier that belongs a mobile number.

EndPoint

https://[ServiceURLZGateway]/v2/api/carrierLookUp/

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
MSISDN String YES Mobile number with country code

Response

Parameter Data Type Description
msisdn String Mobile number with country code (example 525531371074)
mcc String Mobile Country Code
mnc String Mobile Network Code
networkId String Network ID
serviceProviderId String Id Of Service Provider
serviceProviderDesc String Description of Service Provider
NumberType String
  • 1 - Mobile
  • 2 - Fixed
  • 3 - Other
IsPorted Boolean The subscriber's number is ported or not (e.g. True, False)
PortingDate DateTime Date of number porting (YYYY-MM-DD HH:MM)
currency String TopUp Currency
cost Decimal Customer cost for the Tx
detail String String Transaction Detail
dateTimeTransaction DateTime Transaction datetime (MM-dd-yyyyTHH:mm:ss)

Request Example

https://[ServiceURLZGateway]/api/carrierLookUp/



1. {   

2. "clientID": "1234-ABCD-1234",    

3. "MSISDN": "525545891076"   

4. }

Response Success Example



1. {   

2.      "code": 200,   

3.      "message": "CarrierLookUp Successfully Executed",   

4.      "txID": "FZRP5c3ewdvN24vntwaI20220810",   

5.      "response": {   

6.          "msisdn": "525545891076",

7.          "mcc": "334",

8.          "mnc": "020",

9.          "networkID": "188",

10.         "network": "Telcel",

11.         "serviceProviderID": "188",

12.         "serviceProviderDesc": "Telcel",

13.         "numberType": "1",

14.         "isPorted": true,

15.         "portingDate": "2022-07-19 02:00",

16.         "cost": 0.1160,

17.         "currency": "MXN",

18.         "detail": "Data obtained from central DB",

19.         "dateTimeTransaction": "08-09-2022T17:03:11"

20.     },

21.     "error": [

22.         null

23.     ]

24. }

Response Failure Example



1 {   

2.      "code": 400,

3.      "message": "Invalid Destination number",

4.      "txID": "mhXHC7APjGnBSeQwCVU620220210",

5.      "response": null,

6.      "error": null

7. }

sendSms V3

Send sms to Mobile number.

EndPoint

https://[ServiceURLZGateway]/v3/api/sendSms

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
message String YES Message to send
msisdn String (12 Characters) YES Mobile number with country code
sender String YES Alphasender or Shortcode to be used

Response

Parameter Data Type Description
msisdn String Mobile number with country code (example 525531371074)
cost Decimal sms Cost
encoding String Encoding used
segments Integer Number of SMS segments charged
mcc String Mobile Country Code
mnc String Mobile Network Code

Request Example



1. {

2. "msisdn": "525545891076",

3. "clientID": "XXXXXXX",

4. "sender": "99999",

5. "message": "Holá"

6. }

Response Success Example



1. {

2.      "code": 200,

3.      "message": "SMS sent successfully",

4.      "txID": "9DR0lZqiqBFoHGKkYn40",

5.      "response": {

6.          "msisdn": "525545891076",

7.          "cost": 0.2900,

8.          "encoding": "USC-2",

9.          "segments": 1,

10.         "mcc": "334",

11.         "mnc": "050"

12.     },

13.     "error": [

14.         null

15.     ]

16. }

Response Failure Example



1. {

2.      "code": -208,

3.      "message": "Destination number invalid",

4.      "txID": "oarZnxrH1zYFLzWPchx4",

5.      "response": null,

6.      "error": null

7. }

sendSmsLight

Send sms to Mobile number.

EndPoint

https://[ServiceURLZGateway]/v1/api/sendSmsLight

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
message String YES Message to send
msisdn String (12 Characters) YES Mobile number with country code
sender String YES Alphasender or Shortcode to be used

Response

Parameter Data Type Description
status String Transaction status (See Table 2 -Received or Rejected)
detail String Transaction Detail

Request Example



1. {

2. "msisdn": "525545891076",

3. "clientID": "XXXXXXX",

4. "sender": "99999",

5. "message": "Holá"

6. }

Response Success Example



1. {

2.      "code": 200,

3.      "message": "SMS sent successfully",

4.      "txID": "9DR0lZqiqBaFadT435CVa0",

5.      "response": {

6.          "status": "200",

7.          "detail": "Operation Received"

8.     },

9.     "error": [

10.         null

11.     ]

12. }

Response Failure Example



1. {

2.      "code": -208,

3.      "message": "Destination number invalid",

4.      "txID": "oarZnxrH1zYFLzWPchx4",

5.      "response": null,

6.      "error": null

7. }

sendSmsFlash

Send sms to Mobile number.

EndPoint

https://[ServiceURLZGateway]/v1/api/sendSmsFlash

Request the [ServiceURLZGateway] to your account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
message String YES Message to send
msisdn String (12 Characters) YES Mobile number with country code
sender String YES Alphasender or Shortcode to be used

Response

Parameter Data Type Description
msisdn String Mobile number with country code (example 525531371074)
cost Decimal sms Cost
encoding String Encoding used
segments Integer Number of SMS segments charged
mcc String Mobile Country Code
mnc String Mobile Network Code

Request Example



1. {

2. "msisdn": "525545891076",

3. "clientID": "XXXXXXX",

4. "sender": "99999",

5. "message": "Holá"

6. }

Response Success Example



1. {

2.      "code": 200,

3.      "message": "SMS sent successfully",

4.      "txID": "9DR0lZqiqBFoHGKkYn40",

5.      "response": {

6.          "msisdn": "525545891076",

7.          "cost": 0.2900,

8.          "encoding": "USC-2",

9.          "segments": 1,

10.         "mcc": "334",

11.         "mnc": "050"

12.     },

13.     "error": [

14.         null

15.     ]

16. }

Response Failure Example



1. {

2.      "code": -208,

3.      "message": "Destination number invalid",

4.      "txID": "oarZnxrH1zYFLzWPchx4",

5.      "response": null,

6.      "error": null

7. }

Setting up Hooks

Hooks are a common tool to communicate when an event happens to a subscribed platform. It sends an automated message to a server or email providing an automated form of communication between two systems.


What events are notified via Hooks?

Subscribing to hooks in Zorya will help you to receive MOs.

Webhooks

This type of notification will be done by performing an HTTPS POST request to the endpoint you provide. This request’s body will contain the information related to the event being notified.

Please note that this information will be sent in the request as a JWT (Json web token). This is a compact and self-contained way to transmit information securely between two parties in the form of a JSON object.

How to decode the JWT?

To parse the received token we are going to use the jwt.Parse(...) function, which expects the token as the first argument and a verification function as the second argument, where you will check that both the signing algorithm and the secret obtained from parsing the token are the expected ones. (otherwise you will know that the token has been altered).

As you can see in the example below, the jwt.Keyfunc function will allow you to make the pertinent validations on the token in question. This function will be used by the jwt.Parse method to detect possible alterations during such parsing.

Please note that this information will be sent in the request with the following data parameters:

  • We send the data in the next format
  • Has a requirement we need that your URL have CORS enable.
  • Is mandatory to have SSL support in the URL.

pushStatus

Notify the status of a Top Up transaction when it is finished successfully or with any error if it cannot be retried.

EndPoint

https://[CustomerEndPoint]/{clientID}/{txID}/{status}

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
clientID String YES Client ID (Request it to your account manager)
txID String YES Transaction ID generated in method: executeTopUp
MSISDN String YES Mobile number with country code
amount Decimal YES TopUp Amount
status String YES Final Transaction Status(See Table 2 - Successful or Error)

Expected Response

Parameter Data Type Description
ack Integer 1 – Status Received

Request Example

https:// [CustomerEndPoint]/ 1234-ABCD-1234/txID12345/100

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.

Response Example



1. {   

2.      "ack": 1

3. }

moSMSCallback

Deliver de MOs sent by subscribers to a SC.

EndPoint

https://[CustomerEndPoint]/

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
txID String YES Transaction ID
msisdn String YES Mobile number with country code
message String YES Message sent by the user of the mobile line to a SC
dateTimeTransaction DateTime YES dateTimeTransaction DateTime Transaction datetime (yyyy-MM-ddTHH:mm:ss)

Expected Response

Parameter Data Type Description
ack Integer 1 – Status Received

Request Example

https://[CustomerEndPoint]/

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.



1. {   

2. "txID": "100000001",   

3. "msisdn": "525545891076", 

4. "message": "Hola",  

5. "dateTimeTransaction": "2022-07-28T12:11:53"

6. }

Response Example



1. {   

2.      "ack": 1

3. }

mtSMSCallback

Deliver de MTs sent by subscribers to a SC.

EndPoint

https://[CustomerEndPoint]/

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.

HTTP Method

POST

Request

Parameter Data Type Required Description
msisdn String YES Mobile number with country code
cost Decimal YES Customer cost for the Tx
encoding String YES Enconding used
segments Integer YES Number of SMS segments charged
dateTimeTransaction DateTime YES dateTimeTransaction DateTime Transaction datetime (yyyy-MM-ddTHH:mm:ss)
mcc String YES Mobile Country Code
mnc String YES Mobile Network Code

Expected Response

Parameter Data Type Description
ack Integer 1 – Status Received

Request Example

https://[CustomerEndPoint]/

Customer needs to give the [CustomerEndPoint] to their Zorya account manager.



1. {

2.      "code": 200,

3.      "message": "SMS sent successfully",

4.      "txID": "9DR0lZqiqBFoHGKkYn40",

5.      "response": {

6.          "msisdn": "525545891076",

7.          "cost": 0.2900,

8.          "encoding": "USC-2",

9.          "segments": 1,

10.         "mcc": "716",

11.         "mnc": "",

12.         "dateTimeTransaction": "2022-07-28T12:11:53"

13.     },

14.     "error": [

15.         null

16.     ]

17. }

Response Example



1. {   

2.      "ack": 1

3. }

Response Failure Example



1. {

2.      "code": -208,
                                                        
3.      "message": "SMS ERROR",
                                                        
4.      "txID": "oarZnxrH1zYFLzWPchx4",
                                                        
5.      "response": null,
                                                        
6.      "error": null
                                                        
7. }

SMPP Connection

The SMPP (Short Message Peer-to-Peer) protocol is an open, industry standard protocol designed to provide a flexible data communications interface for the transfer of short message data between External Short Message Entities (ESME), Routing Entities (RE) and Message Centres (MC). It is a means by which applications can send and receive SMS messages to and from mobile devices.
If you have high SMS volumes it is the right protocol to use in your connection to Zorya’s platform to send SMS A2P.

Connection Setup

Required Information to setup your bind:

    • Origin IP of your server to enable it in our firewall

Required Information provided by your account manager:

Parameter Description
Server IP IP of Zorya Technologies SMPP server
Server Port Port of Zorya Technologies SMPP server
System ID ID provied by Zorya Technologies for our clients
Password Account password provied by Zorya Technologies

By default your SMS MT will delivered using a Shared Shortcode, if you need an Alpha Sender or Dedicated Short Code, request it to your account manager, may apply extra fees.
If you require MOs your bind must be transceiver, or set up a second bind reciever, in other case if you only will send MT, you can configure your bind only as sender.

Throughput Managment

TPS are assigned by Zorya to each SMPP account, by default are 5 TPS. In case that you need more TPS request it to your account manager.
You will be able to set up multiple sender binds according to your volume, ask to your account manager about how many binds is allowed in your account and how increase it.

Delivery Receipt Confirmation (DLR)

Handset DLR requires special configuration with the carriers and each SMS MT sent with DLR request has double cost.
By default, if you request DLR we will deliverer you an ACK (Fake DLR) when the MT is delivered and accepted by the carrier.
In case that you need Real DLR from handset request it to your account manager, it will require a dedicated Short Code assigned to your account.

Package Details: Send MT

Parameter Description
Source Address Source Address SC or Alphanseder to be used, if it is not configured in your account a default shared SC will be used to deliver the SMS MT
Destination Address Destination Mobile Number in international format
Data Coding Default, GSM-7, UCS-2 o Latin1
Registered Delivery IRegistered Delivery By default, if you request DLR we will deliverer you an ACK (Fake DLR) when the MT is delivered and accepted by the carrier. If you need Handset DLR request a dedicated Short Code to your account manager to by requested to the carriers.
Short Message Message to send

Package Details: MO Response

Parameter Description
Source Address Mobile Number
Destination Address SC or Alphanseder to be used
Data Coding Default, GSM-7, UCS-2 o Latin1
Short Message Message to send

Tables

Tables used in the API

Table 1 - Response Code

Code Description
200 Successful Transaction
400 Bad Request
-201 Operation failed
-202 Operation not found
-203 Operation denied
-204 Invalid Auth Token
-205 Expired Auth Token
-206 Invalid amount
-208 Destination number not found
-209 Please retry in 10 minutes
-210 There is not enough funds
-211 Unauthorized destination number

Table 2 - Status

Code Description
-1 Rejected
100 Received
101 Carrier LookUp
102 Queue
103 Successful
104 Retrying
-105 Invalid
-203 Operation denied

Table 3 - Top Up Amounts

ZCode Description Amounts Avaliable
MOVITA MOVISTAR Tiempo Aire $10.00, $10.00, $20.00, $30.00, $50.00, $60.00, $80.00, $100.00, $120.00, $150.00, $200.00, $300.00, $500.00
MOVIPDI MOVISTAR Paquete Internet $10.00, $20.00, $100.00, $150.00, $200.00
TELPA TELCEL Internet Paquete Amigo $20.00, $30.00, $50.00, $80.00, $100.00, $150.00, $200.00, $270.00, $300.00, $400.00, $500.00
TELPI TELCEL Internet $20.00, $30.00, $50.00, $80.00, $100.00, $150.00, $200.00, $300.00, $500.00
TELTA TELCEL Tiempo Aire $10.00, $20.00, $30.00, $50.00, $80.00 $100.00, $150.00, $200.00, $300.00, $500.00
UNETA UNEFON Tiempo Aire $10.00, $15.00, $20.00, $30.00, $50.00, $70.00, $100.00, $120.00, $150.00, $200.00, $300.00, $500.00, $1000.00
ATTTA AT&T Tiempo Aire $10.00, $15.00, $20.00, $30.00, $50.00, $70.00, $100.00, $120.00, $150.00, $200.00, $300.00, $500.00, $1000.00
OUITA OUI Tiempo Aire $10.00, $15.00, $20.00, $25.00, $30.00, $35.00, $40.00, $45.00, $50.00, $60.00, $80.00, $100.00, $120.00, $150.00, $200.00, $240.00, $300.00, $350.00
VIRTA VIRGIN MOBILE Tiempo Aire $10.00, $20.00, $30.00, $50.00, $80.00, $100.00, $150.00, $200.00, $300.00
FLTI FLASH MOBILE Tiempo Aire $10.00, $20.00, $30.00, $40.00, $50.00, $60.00, $70.00, $80.00, $90.00, $100.00, $120.00, $150.00, $200.00, $250.00, $300.00, $400.00, $500.00
WETI WEEX Tiempo Aire $10.00, $20.00, $30.00, $40.00, $50.00, $60.00, $70.00, $80.00, $90.00, $100.00, $120.00, $150.00, $200.00, $250.00, $300.00, $400.00, $500.00
BAITTA BAIT Tiempo Aire $30.00, $50.00, $60.00, $100.00, $120.00, $125.00, $200.00, $230.00, $300.00
ABIBTA ABIB Tiempo Aire $35.00, $55.00, $65.00, $80.00, $100.00, $110.00, $117.00, $120.00, $130.00, $140.00, $150.00, $200.00 $220.00, $297.00, $499.00,
PILLOTA PILLOFON Tiempo Aire $90.00, $200.00, $350.00, $420.00, $600.00
COMPARTTA COMPART Tiempo Aire $30.00, $50.00, $100.00, $200.00
GUGAINTA GUGAIN Tiempo Aire $120.00, $389.00, $489.00, $599.00
TELMOVILTA TELMOVIL Tiempo Aire $30.00, $50.00, $100.00, $200.00, $300.00
MIMOVILTA MIMOVIL Tiempo Aire $50.00, $80.00, $100.00, $125.00, $150.00, $200.00, $280.00, $400.00, $500.00, $750.00, $1350.00, $1400.00, $2500.00
VALORTATA VALOR Tiempo Aire $35.00, $55.00, $100.00, $120.00, $165.00, $220.00, $290.00
FREEDOMTA FREEDOM Tiempo Aire $30.00, $50.00, $80.00, $100.00, $150.00, $200.00
NEWWWTA NEWWW Tiempo Aire $59.00, $100.00, $120.00, $135.00, $200.00, $230.00, $330.00, $525.00
YOBITA YOBI Tiempo Aire $20.00, $30.00, $50.00, $100.00, $150.00, $200.00, $300.00, $500.00
JRMOVILTA JRMOVIL Tiempo Aire $65.00, $75.00, $125.00, $130.00, $149.00, $150.00, $250.00, $260.00
JRMOVILPB JRMOVIL Plan Basico $99.00
JRMOVILP10 JRMOVIL Plan JR10 Mas $149.00
WIKTA WIK Tiempo Aire $30.00, $50.00, $100.00, $200.00, $400.00, $749.00, $825.00, $1200.00, $2100.00
WIMTA WIMO Tiempo Aire $35.00, $65.00, $125.00, $130.00, $190.00, $250.00, $375.00, $625.00
SORIANAMOVTA SORIANAMOV Tiempo Aire $5.00, $10.00, $20.00, $30.00, $50.00, $100.00, $150.00, $200.00, $500.00
SIMPATITA SIMPATI Tiempo Aire $20.00, $50.00, $100.00, $150.00, $300.00, $500.00
DIRITA DIRI Tiempo Aire $80.00, $150.00, $200.00, $300.00, $400.00, $500.00
TUETA TUENTI Tiempo aire $50.00, $80.00, $100.00, $150.00, $250.00, $300.00
ALOTA ALO Tiempo aire $10.00, $20.00, $30.00, $50.00, $100.00, $200.00, $300.00, $500.00
BAITDC MiBait Internet Casa $99.00, $349.00
BAITI MiBait Internet Portatil $110.00, $210.00, $410.00
BAITPA MiBait Paquete $550.00, $800.00, $1050.00, $1500.00, $2000.00, $2900.00
BAITDM MiBait Móviles $110.00, $210.00, $410.00
CFEIP CFE Sumate Plus $45.00, $150.00, $300.00
GUGATA GUGACOM Tiempo Aire $40.00, $65.00, $129.00, $130.00, $195.00, $250.00, $380.00
SORIANAMAH SORIANA Mas Ahorro $30.00, $50.00, $100.00, $140.00, $180.00, $280.00
CFESUM CFE Sumate $30.00, $50.00, $60.00, $99.00, $100.00, $120.00, $200.00, $230.00
TELPP Telcel Ilimitado $10.00, $15.00
VALORTE VALOR Telecom $30.00, $50.00, $55.00, $60.00, $89.00, $100.00, $109.00, $120.00, $140.00, $230.00, $239.00, $300.00, $319.00, $360.00, $369.00, $420.00, $439.00, $450.00, $499.00, $590.00
JRMOVILMF JRMovil Tiempo Aire $130.00, $230.00, $290.00, $520.00, $650.00
ULTCEL Ultravisión Tiempo Aire $55.00, $65.00, $99.00, $105.00, $110.00, $125.00, $135.00, $150.00, $210.00, $240.00, $250.00, $299.00, $330.00, $359.00, $399.00, $429.00, $475.00, $510.00, $625.00
AXIOSM Axios Tiempo Aire $25.00, $30.00, $50.00, $60.00, $100.00, $120.00, $200.00, $230.00, $300.00, $500.00, $550.00, $1000.00, $1050.00, $2000.00
AXIOPA Axios Paquete Internet $99.00, $119.00, $229.00, $279.00, $299.00, $349.00, $439.00, $499.00
BIENESTARI Bienestar Tiempo Aire $50.00, $60.00, $99.00, $100.00, $120.00, $200.00, $230.00
BIENESTARPA Bienestar Paquete Internet $100.00, $200.00, $300.00, $400.00
VALORIC Valor Internet en Casa $99.00, $110.00, $349.00, $399.00, $439.00

Table 4 - MT Status

Code Description
200 SMS sent successfully
201 SMS Delivered successfully
-208 SMS ERROR

Contenido de GSM Character Set

GSM-7 Character Set

Basic character set:

0x10 0x20 0x30 0x40 0x50 0x60 0x70 0x80
0x00 @ Δ SP 0 ¡ P ¿ p
0x01 £ _ ! 1 A Q a q
0x02 $ Φ " 2 B R b r
0x03 ¥ Γ # 3 C S c s
0x04 è Λ ¤ 4 D T d t
0x05 é Ω % 5 E U e u
0x06 ù Π & 6 F V f v
0x07 ì Ψ ' 7 G W g w
0x08 ò Σ ( 8 H X h x
0x09 Ç Θ ) 9 I Y i y
0x0A LF Ξ * : J Z j z
0x0B Ø ESC + ; K Ä k ä
0x0C ø Æ , < L Ö l ö
0x0D CR æ - = M Ñ m ñ
0x0E Å ß . > N Ü n ü
0x0F å É / ? O § o à
0x00 @ Δ SP 0 ¡ P ¿ p

Extension of the basic character set, these characters occupy 2 positions:

0x10 0x20 0x30 0x40 0x50 0x60 0x70 0x80
0x00|
0x02
0x03
0x04^
0x05€
0x06
0x07
0x08{
0x09}
0x0AFF
0x0BSS2
0x0C[
0x0DCR2~
0x0E]
0x0F\