SMS

v.2
Elaborated by Resonance Tech, R&D Department
 SMS

1. VERSION HISTORY .................................................................................................................................... 2

2. INTRODUCTION .......................................................................................................................................... 3
3. AUTHENTICATION ..................................................................................................................................... 4
4. MO ................................................................................................................................................................ 5
5. MT ................................................................................................................................................................ 6
6. DLR .............................................................................................................................................................. 8
7. SUBSCRIPTION .......................................................................................................................................... 9
8. UNSUBSCRIPTIONS ................................................................................................................................. 11
9. NOTIFICATIONS ....................................................................................................................................... 13
10. ERROR CODES ....................................................................................................................................... 14

Page 1
 SMS

1. Version History

Version Coments
1 Initial Version
2 Change API domain from enabler.dvbs.com to
telcos.dvpass.com

Page 2
 SMS

2. Introduction
The following document describes calls and flows involved in the operator and payment services
subscriptions of the platform.

There is the possibility of configuring services in “Test” mode to assist in the integration tasks. A service
in test mode behaves like any other service, with the difference that the API calls do not include the
connection with the operator, so that all the methods can be implemented without impact of the balance
consumed.

Page 3
 SMS

3. Authentication
All calls to the API will be made with basic HTTP Authentication over SSL secure channel. The
connection credentials will be provided to the merchant at the beginning of the integration.

For more information see in https://en.wikipedia.org/wiki/Basic_access_authentication

Page 4
 SMS

4. MO
Inconming messages from a user are routed from the operator to the client through the Enabler. When a
service is registered, a notification URL can be configured. The parameters that will be added to the
notification URL are the following:

Name Description
type Ty of event notify, in this case "MO"
mcc_mnc Client operator Identifier
msisdn User msisdn, in case it can be provided according to the regulations of the service
/ operator. Format with international prefix, without "zeros" or signs "+".
shortnum Short Number
service_id Service Identifier
date Transaction date (UTC). YYYY-MM-DDTht:mm:ss
text Message Text
mo_id MO Identifier

The system accept any response with http code 200 as a delivered notification. Otherwise, the system
will retry to deliver the notification up to 5 times in 5 minute intervals.

Page 5
 SMS

5. MT
Each MO needs an MT to close the session opened by the user. The call of the MT is made by the client
indicating the MO id or the subscription (alerts) to which it refers. In the case of MO-MT, the session
expiration time to send the MT is 30 minutes.

URL: GET https://telcos.dvpass.com/api/sms/send10

Input Parameters

Name Required Description

service_id Y Service Identifier
text Y Message text
charge N Indicates whether the message should be charged or not. "0" = not charged.
"1" = the price of the service is used. "2" = a fixed price of 0.1 is used
(according to the operator)
mo_id N MO Id. In a push alerts case, it will be not necessary to indicate it.
subscription_id N ID Subscription, only for sending alerts. It will not be necessary in case of an
MT that closes session of an MO. (Point 6).

Response Parameters (JSON)

Name Description
result Operation Result. Possible Values: "OK", "ERROR"
id MT ID, will server to identify the corresponding DLR.
error_code In case of an "ERROR" result, an error code identify the type of error.
message In case of an "ERROR" result, descriptive text of the error.

Example correct answer:

{
"result": "OK",
"id": "033c2320-0119-a22f-2d57-00005ab4c7d9"
}

Example wrong answer:

Page 6
 SMS

{
"result": "ERROR",
"error_code": "MO_ID_SESSION_EXPIRED",
"message": "MO session expired"
}

If the answer of the call is satisfactory, we will try to send the message to the operator inmediately and
once we have proof of its status, we will generate a SRL back to the client.

Page 7
 SMS

6. DLR
For each MT that the client sends, a report will be generated indicating if the message could be sent or
not. This DRL wil be done by calling the same service notification URL, with the following parameters:

Name Description
type Event type notified, "DLR" o "DLR_ERROR"
mt_id MT Identifier
error_code In case of an "DLR_ERROR", an error code identify the type of error.
message In case of an "DLR_ERROR", descriptive text of the error.

The system will consider any response with http code 200 as a delivered notification. Otherwise, the
system will retry to deliver the notification up to 5 times in 5 minute intervals. If the type is "DLR" it will be
considered sent, indicating only the MT ID.

Page 8
 SMS

7. Subscription
When a subscription-type MO-MT session us completed, it is necessary to call the following API to
excecute the subscription. This call will return the subscription id to the client so that it subsequently
sends messages to the user's subscription.

URL: GET https://telcos.dvpass.com/api/sms/subscribe10

Input Parameters

Name Required Description

mo_id Y First MO
session
identifier

Response Parameters (JSON)

Name Description
result Operation Result. Possible Values: "OK", "ERROR"
id Subscription identifier
error_code In case of an "ERROR" result, an error code identify the type of error.
message In case of an "DLR_ERROR", descriptive text of the error.

Example correct answer:

{
"result": "OK",
"id": "0451a7a8-0119-a186-c3f2-00005ac356f2"
}

Example wrong answer:

Page 9
 SMS

{
"result": "ERROR",
"error_code": "SERVICE_NO_SUBSCRIPTION",
"message": "Subscription not aplicable by service"
}

Page 10
 SMS

8. Unsubscriptions
Through the following call the merchant can cancel a user subscription.

URL: GET https://telcos.dvpass.com/api/unsubscribe10

Input Parameters

Name Required Description

subscription_id Y Subscription to be
canceled identifier

Parámetros de respuesta (JSON)

Name Description
result Operation Result. Possible Values: "OK", "ERROR"
msisdn User msisdn, in case it can be provided according to the regulations of the service / operator.
Format with international prefix, without "zeros" or signs "+".
alias Unique user identifier. Replaces the msisdn and identifies the client in case that cannot be
provided to merchant. Provided according to service / operator regulations.
mcc_mnc Client operator Identifier
date Transaction date (UTC). YYYY-MM-DDTht:mm:ss
subscription_id Unique subscription identifier
error_code In case of an "ERROR" result, an error code identify the type of error.
message In case of an "ERROR" result, descriptive text of the error.

Example correct answer:

{
"result":"OK",
"msisdn":"34667790520",
"mcc_mnc":"214_3",
"date":"2017-11-21T10:18:32",
"subscription_id":"034797f0-0119-a022-1962-00005a0ef482"
}

Page 11
 SMS

Example wrong answer:

{
"result":"ERROR",
"error_code":"ALREADY_DISABLED",
"message":"Subscription already disabled"
}

{
"result":"ERROR",
"error_code":"SUBSCRIPTION_NOT_FOUND",
"message":"Subscription not found"
}

Page 12
 SMS

9. Notifications
When you create a service on our platform it is possible to configure a notification URL. Enabler will
notify to this URL the following events:

SUBSCRIPTION

UNSUBSCRIPTION

The system accepts any response with http code 200 as a delivered notification. Otherwise, the system
will retry to deliver the notification up to 5 times in 5 minute intervals.

The parameters that will be added to the URL of notifications are the following:

Name Description
type Event type
mcc_mnc Client operator Identifier.
msisdn User msisdn, in case it can be provided according to the regulations of the service
/ operator. Format with international prefix, without "zeros" or signs "+".
alias Unique user identifier. Replaces the msisdn and identifies the client in case it
cannot be provided to merchant. Provided according to service / operator
regulations.
service_id Service identifier
subscription_id Unique subscription identifier.
date Transaction date (UTC). Format YYYY-MM-DDTht:mm:ss

Page 13
 SMS

10. Error Codes

This is a list of possible errors that may appear in calls to APIs and also in notifications:

error_code message
LOGIN_ERROR Login Error
INVALID_MSISDN Invalid msisdn
MSISDN_NOT_FOUND MSISDN not found in SMSC
BLACKLISTED Blacklisted
BLOCKED Blocked
PIN_LIMIT_REACHED Pin tries limit reached
PIN_SEND_LIMIT_REACHED Pin sending limit reached
PIN_ALREADY_SENT Pin already sent
ALREADY_SUBSCRIBED Already Subscribed
SUBSCRIPTION_LIMIT_REACHED Subscription limit reached
SUBSCRIPTION_TIME_LIMIT_REACHED Subscription time limit reached
SUBSCRIPTION_NOT_FOUND Subscription not found
SUBSCRIPTION_INACTIVE Subscription Inactive
ALREADY_DISABLED Subscription already disabled
NOT_CONFIRMED Not confirmed
INVALID_PRICE Invalid Price
INVALID_PIN Invalid Pin
EXPIRED Expired request
ALREADY_RUNNING Request already running
FLOODING_ERROR Flooding error
UNABLE_TO_IDENTIFY Unable to identify the user
CARRIER_NOT_FOUND Carrier not found
INVALID_SERVICE Invalid service
SERVICE_NOT_FOUND Service not found
SERVICE_NOT_AVAILABLE Service not available
INVALID_MERCHANT Invalid merchant
MERCHANT_NOT_FOUND Merchant not found
MERCHANT_NOT_AVAILABLE Merchant not available
PAYMENT_NOT_FOUND Payment not found
OUT_OF_PERIOD Out of period
NOT_REFUNDABLE Payment not refundable
CHARGE_LIMIT_REACHED Charge limit reached
REFUND_NOT_ENABLED Refund system not enabled
REFUND_OUT_OF_PERIOD Refund out of period
CHARGE_AMOUNT_EXCEEDED Charge amount exceeded
CANCELLED_BY_USER Subscription cancelled by user
AUTH_ERROR Invalid user/password
METHOD_NOT_ALLOWED Method not allowed
SERVICE_NO_SUBSCRIPTION Subscription not aplicable by service
SERVICE_CHARGE_MANDATORY Charge is mandatory for this service
SERVICE_NO_CHARGEABLE Charge not allowed for this service
MO_ID_MANDATORY mo_id parameter is mandatory
MT_NOT_FOUND MT not found
MO_NOT_FOUND MO not found
MO_ID_SUBSCRIPTION_ID mo_id and subscription_id are exclusives
MO_ID_SESSION_EXPIRED MO session expired

Page 14
 SMS

error_code message
INCORRECT_MSISDN Incorrect destination address
MISSING_MSISDN Missing destination address
INVALID_MULTIPLE_CHARGING Charging not allowed for multiple destinations
NO_CREDIT No credit
PRICE_LIMIT_REACHED Price limit reached
INVALID_BILLING_ADDRESS Invalid billing address
INVALID_TARIFF Invalid tariff
TIMEOUT Timeout
INVALID_RESERVATION Invalid Reservation
INVALID_DATA Invalid data
MISSING_PARAMETERS Missing parameters
WRONG_PARAMETERS Wrong parameters
CARRIER_CONNECTION_ERROR Carrier connection error
CARRIER_TIMEOUT Carrier timeout
UNKNOWN_CARRIER Unknown carrier
GENERIC_ERROR Generic error
RUNTIME_ERROR Runtime error
INTERNAL_SERVER_ERROR Internal server error
UNKNOWN_ERROR Unknown error
PARENTAL_BLOCK Blocked by parental control

Page 15
 Gateway WAP Portugal MEO

resonancetech.com
Juan Ignacio Luca de Tena 1, Planta 3ª - 28027 Madrid.
Tel. 902 01 02 01 Page 27