Nvia API Specification

for DCB
Version 3.0.10

26/09/2017

Legal Information

The information supplied in this document is Nvia Gestion de Datos S.L. sole property and copyright.
It is intended for strictly informational use. It is not binding and might be subject to changes without notice.
Any unauthorized disclosure shall be considered as unlawful.
NVIA GESTION DE DATOS S.L
Calle la Oliva 18, Las Rozas- Madrid, Spain.

www.nviasms.com
C ONTROL DE V ERSIONES

Versión Fecha Descripción de cambios

3.0 22/06/2015 Creation of the document supporting the old documentation 2.0.
The interface and internal systems are completely changed.
3.0.1 25/06/2015 Client uses transaction_request.php interface to get the URL to
which he must redirect the user
3.0.2 01/07/2015 Normalization of XML return
3.0.3 02/07/2015 Change of WEB OTP interfaces
3.0.4 03/07/2015 Migration of the old billing interfaces: mtalertan and mtalertalista
3.0.5 07/07/2015 Review
3.0.6 27/10/2015 The cancellation_request interface is removed to make way for a
clearer and simpler unsubscription_request interface.
Review of payment interfaces make_payment and
n_make_payment
3.0.7 27/11/2015 Documentation Review
3.0.8 08/01/2016 Including necessary response from the client to confirm the
reception of notifications.
Contact email will be required to inform about possible incidents in
the service.
3.0.9 07/03/2016 Added API identification_request.php that will be used for the
recognition of the MSISDN and operator data associated with a
mobile device. This identification can only be made in certain
operators when the mobile device is navigating the operator's own
network (2G, 3G or 4G ...)
A new functionality is added to the API transaction_request.php to
allow a client to notify about a new purchase or subscription
attempt for those cases where there is no reliable traceability
between said requested transaction and the subsequent
registration. Normally these cases will be useful for purchases or
type subscriptions, IVR, USSD and even SMS in such a way that it will
allow the NVIA to associate very closely the registration with the
transaction already initiated by this methodology.
3.0.10 26/09/2017 Review.
Included new cache system.
Included new balancing system between servers.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 2 de 15
 1. TABLE OF CONTENTS
Version Control............................................................................................................................................. 2
Introduction.................................................................................................................................................. 4
Comunication and use of the interface ........................................................................................................ 4
Suscription Flow WAP/2G/3G/4G ................................................................................................................ 5

Request a WAP Transaction /2G/3G/4G/IVR/USSD/S@T/SMS ............................................. 6

Cancellation Flow ....................................................................................................................................... 10

Canceling a subscription / service .......................................................................................... 10

Notifications ............................................................................................................................................... 13
Data to be provided for the integration: .................................................................................................... 15

On the Nvia side ..................................................................................................................... 15

On the Cliente side: ................................................................................................................ 15

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 3 de 15
I NTRODUCTION
The purpose of this document is to explain the communication interface and flows to follow
for the realization of subscriptions, purchases and payments through the Nvia platform. The
possible variants for the integration, management and sale of products both through WAP /
2G / 3G networks and fixed networks through the WEB OTP process will be explained. In this
way there will always be the possibility of carrying out the purchase or subscription process by
making the payments directly through the user's mobile operator. We will define this
methodology as DCB (Direct Carrier Billing)

C OMMUNICATION AND USE OF THE INTERFACE

All the interfaces shown in the document work through http requests with the parameters
sent by the GET method. There will be two types of requests:

 S2S (Sever to Server): Calls will be made to the interfaces directly made from the client
software without the user acting.
 Redirections: The client will only redirect the user's navigation to the URLs necessary
for the identification of the device or for the interaction with the user.
 Interaction: In these requests, the user's browser will directly perform the operations
required for approval, cancellation, etc.

In all cases in which the control of navigation is controlled by Nvia, this control will be returned
to the client at the end of the process. Good to report the acceptance or decline of the user's
actions.

Each registration, cancellation and payment event will be notified to the client via http with
GET method to a series of URLs that the client can provide. It's not mandatory. See section
notifications.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 4 de 15
S UBSCRIPTION F LOW WAP /2G/3G/4G
This flow will be used in order to subscribe a user to a service or make the purchase of a
product. The only difference between purchase and subscription, at the interface level, will
depend on the service contracted with Nvia. In the case of subscription, recurring charges will
be allowed following the definition of the service and in the case of purchase, it will be charged
at the time without the possibility of carrying out the same operation again.

This type of flow can only be made in the mobile networks of the operators. If the device can
not be identified through the navigation network, the interface will return an error to inform
that this type of registration can not be used.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 5 de 15
A brief description of the steps to follow is the following:

Step Description
1 User accesses the client's landing
2 Client uses transaction_request.php interface to get the URL to which he
must redirect the user
3 Nvia returns an XML with the redirect URL (redirUrl)
4 Client redirects the user to redirUrl
5 Nvia carries out the tasks of identification, provisioning and billing of the
service with the operator.
* Depending on the country and operator, the user will have to carry out
a series of operations to accept the product or service (payment and / or
subscription)
** Only the networks detected as mobile will be able to perform this
operation otherwise it will have to proceed with the registration via WEB
/ OTP using the interfaces otp_request.php and otp_validate.php.
6 The operation is confirmed by sending a welcome message to the user.
7 Nvia redirects the user to callbackUrl configured for the product.
8 Nvia notifies, asynchronously, the subscription and billing events.
5* If during the process, the user does not accept the operation, it will be
redirected to errorCallbackUrl with action = error
5** If during the identification process it is detected that the network does
not allow the subscription operation, the client will be redirected to
not3GCallbackUrl. If the otp_request.php and otp_validate.php
interfaces are available, they may have to be used.

Request a WAP/2G/3G/4G/IVR/USSD/S@T/SMS Transaction

Interface: transaction_request.php

This API will allow requesting a transaction start of a subscription or purchase process
(depending on the product) when the client is browsing through his mobile operator's network
(WAP / 2G / 3G). The use of the API will be through an S2S call (Server to Server). The return
will be an XML that will contain a parameter called redirUrl with the URL where the user
should be redirected. In case of error the XML will contain an error code and a description of it.
The parameters that must be used to use this interface are the following:

PARAMETER DESCRIPTION TYPE

clientd client identifier (ex .: 2192) Mandatory
countryId Country telephone code (eg: 351 for Portugal, 34 for Mandatory
Spain, 66 for Thailand, etc.
user Login to identify yourself on the platform Mandatory
password Password associated with the login Mandatory
productId Identification of the product / service Mandatory
op Alias of the operator Optional
cTid Customer transaction identifier Optional
Informative If the value is YES it will define that the transaction Optional
should be treated as informative for later association
with the discharge in case of not having reliable
correlation. Its use should be limited to high type IVR,
USSD, S @ T or SMS.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 6 de 15
informative_channel It will be used when the transaction is requested in Optional
informative mode. This field will contain the channel
through which the user will try to subscribe: IVR, USSD, S
@ T or SMS. This data will improve the way in which
registrations can be correlated or purchases of products
generated by these channels
callbackUrl URL where the user will be redirected in case of success. Opcional
If this parameter does not exist, the user will be
redirected to the URL configured by default.
errorCallbackUrl URL where the user will be redirected in case of failure. If Opcional
this parameter does not exist, the user will be redirected
to the URL configured by default.
not3GCallbackUrl URL URL where the user will be redirected if they can not Opcional
be processed via WAP. If this parameter does not exist,
the user will be redirected to the URL configured by
default.

The answer will be an XML with the following format:

Respuesta Formato
XML <?xml version="1.0" encoding="UTF-8" ?>
<data>
<code>Código de Operación</code>
<description>Operation Description </description>
<redirUrl>
<![CDATA[URL where the user should be redirected]]>
</redirUrl>
<transaction_id> Transaction identifier</transaction_id>
</data>

Possible operation, description and detail codes for the interface:

Operation Code Description Details

0 Success Transaction created successfully
1 Parameters missing Missing API parameters
2 Unable to load configuration The specified configuration does not
exist. Verify productId and
credentials.
3 Client productId and countryId mismach Configuration parameters
4 Service not available in country The requested service does not exist
in the required country.
5 User validation failed Incorrect credentials.
8 Service not available for operator There is no integration for the
specified operator

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 7 de 15
Practical examples of the use of the interface.

Request/Response Example
S2S Request Transaction general mode:
http://test.panelwap.com/development/transaction_request.php?clientI
Begin Transaction d=2192&countryId=351&user=user01&password=Efows2102&productId=351221

Transaction informative mode:

http://test.panelwap.com/development/transaction_request.php?clientI
d=2192&countryId=351&user=user01&password=Efows2102&productId=351221
&informative=YES

Response Success <?xml version="1.0" encoding="UTF-8" ?>

<data>
General Mode. <code>0</code>
<description>Success</description>
<redirUrl>
<![CDATA[http://test.panelwap.com/development/redir.php?clientId=279
9&tId=1121286&subid=53171518c5509]]>
</redirUrl>
<transaction_id>53171518c5509</transaction_id>
</data>
Response Success <?xml version="1.0" encoding="UTF-8" ?>
<data>
Informative Mode. <code>0</code>
<description>Success</description>
<redirUrl>
<![CDATA[http://test.panelwap.com/development/redir.php?clientId=279
9&tId=1121286&subid=53171518c5509]]>
</redirUrl>
<transaction_id>53171518c5509</transaction_id>
<informative>YES</informative>
</data>
Response Fails. <?xml version="1.0" encoding="UTF-8" ?>
<data>
<code>2</code>
<description>
Unable to load configuration. Please check request parameters.
</description>
</data>

Redirection of the user to redirect Url

Once captured redirUrl, the client must redirect the user's navigation said URL to continue
with the purchase or subscription process. An example, with redirUrl from the previous
example is the following:

http://test.panelwap.com/development/redir.php?clientId=2799&tId=1121286&subid=53171
518c5509

PHP example to request a transaction and resend user to redirURL:

<?php
$url =
"http://test.panelwap.com/development/transaction_request.php?clientId=2192&countryId=35
1&user=user01&password=Efows2102&productId=351221";
$xml = file_get_contents($url);
$o_xml = simplexml_load_string($xml,null,LIBXML_NOCDATA);
#Be careful uncomment the lines below because headers
#will have been wrotten before header command (WARNING and not redirect)
#print_r($o_xml);//Print XML object $o_xml
#echo $o_xml->redirUrl;//Print redireUrl
header("Location: $o_xml->redirUrl");

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 8 de 15
In these cases the subscription or purchase process will begin. Depending on the operator, the
user must follow the flow required for the confirmation / acceptance of purchase of the
product or subscription of the service. Within this flow, the user can perform several actions
that will be returned to the client in the following way:

Action User will be redirected to: With additional variables

User accept the whole process callbackUrl action=new
User cancel the process errorCallbackUrl action=decline
User already subscribed callbackUrl action=subscribed

In addition, the registration action may also be notified to the address specified by the client.
* See section notificaciones.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 9 de 15
C ANCELLATION F LOW
Cancellation of a subscription / service
Interface: unsubscription_request.php

A description of the steps to follow is the following:

Step Description
1 User accesses the Web Portal of the client and requests the withdrawal.
2 A customer manager wants to cancel a service.
3 Nvia requires requesting the withdrawal of a customer service. This process is
not usual but due to legal issues this capacity must exist.
4 For cases 1 and 2 the client will use the unsubscription_request.php interface
5 Nvia will manage the cancellation of the service with the operator.
6 A confirmation SMS will be sent to the user to inform him / her of the
withdrawal process.
7 Through the notification URL of withdrawal, Nvia will inform the customer of the
event.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 10 de 15
This API will allow the withdrawal of a subscription service. Once this operation is performed,
the user's service billing processes can not be performed. There will be two modalities:

 Total unsubscription: In this modality, all the products associated with the MSISDN will
be canceled.
 Discharge of a product: The MSISDN will be discharged only in the selected product.

The parameters required for this interface are the following:

Parameter Description Type

clientId client identifier (ex .: 2192) Mandatory
countryId Country telephone code (eg: 351 for Portugal, 34 for Spain, 66 Mandatory
for Thailand, etc.
user Login to identify yourself on the platform Mandatory
password Password associated with the login
productId Identification of the product / service Mandatory*
msisdn Identifier of the mobile number that wants to be canceled. The Mandatory
mobile number will NOT carry the international prefix.
subscriptionId Unique identifier of the user's subscription returned in the Optional
registration notification.
* Obligatory: It will only be mandatory for the withdrawal of a product. In case of total
withdrawal it will not be necessary.

The response format will be an XML that will have the following format:

Response Format
XML <?xml version="1.0" encoding="UTF-8" ?>
<status>
<code>Operation Code</code>
<description>Operation Description</description>
</status>

The operation, description and detail codes for this interface are the following:

Operation Code Description Detail

OK EVERYTHING_OK The cancellation was made.
*MSISDN_ALREADY_CANCELLED The user was already canceled
KO -1 USER_CREDENTIALS_FAIL Incorrect credentials.
MISSING_PARAMS There are missing parameters in the
API.
KO -2 MSISDN_NOT_FOUND The MSISDN was not registered.
SUBSCRIPTION_ID_NOT_FOUND The subscription identifier was not
found.
KO -3 OPERATOR_ERROR Error returned by the operator.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 11 de 15
Practical examples of use:

Request / Response Example

S2S Cancellation Total Unsubscription:
unsubscription_request.php?
Request countryId=51&clientId=2799&user=smsuser&password=smspassword&msisdn=
898246565

Product unsubscription:
unsubscription_request.php?
countryId=51&productId=5139824&clientId=2799&user=smsuser&password=s
mspassword&subscriptionId=121104273200428814&msisdn=898246565

Successfully <?xml version="1.0" encoding="UTF-8" ?>

<status>
Response <code>OK</code>
<description>EVERYTHING_OK</description>
</status>
Failed Response <?xml version="1.0" encoding="UTF-8" ?>
<status>
<code>KO -2</code>
<description>MSISDN_NOT_FOUND</description>
</status>

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 12 de 15
N OTIFICATIONS
The Nvia system will allow notifications of high, low and payment events.

The notifications will be made through HTTP interfaces using the GET method to the URLs
provided by the client.

Notifications Description
Subscription URL where the client will receive a notification each time a user subscribes or
purchases a product.
Unsubscription URL where the customer will receive a notification when the user cancels a
subscription.
Billing URL where the user will receive a notification each time a billing operation is
performed

Parameter Description Sub Unsub billing

msisdn MSISDN associated with the notification
uid This identifier will be necessary to use it when the system
requires to use a subscriptionId
countryId Country code of the notification
op Operator associated with the operation
productId Identifier of the associated product
ts (TimeStamp) Date and time when the notified event occurred
STATUS  ACK if the payment was correct.
 NACK if the payment could not be made.

CODE  ACK
o 0: Charged
 NACK
o 1: No balance
o 10:MSISDN does not belong to the operator
o 11:MSISDN user blocked by operator
o 12:MSISDN is not registered in the operator
o 13:Full mailbox of the MSISDN
o 14:Incorrect technology or protocol
o 15:MSISDN does not belong to the list in the DB
o 16:Session not active for the MSISDN
o 20:Service temporarily unavailable
o 21:Service not available
o 30:Daily limit exceeded
o 31:Weekly limit exceeded
o 32:Monthly limit exceeded
o 33:Limit operator exceeded
o 40:Syntax error
o 50:Unknown error
In all cases, the client must return "OK" in plain text to confirm that the notification was
received. If this confirmation is not received, the notification will try to be sent in 4 other
occasions (at the minute, 2, 4 and 5 minutes later).

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 13 de 15
In case of not answering "OK" in all retries, an email will be sent to the account associated with
the user with the failed URI.

Response Example
Sucessfully OK
* The user has received the notification
Response
Failed Response KO
ERROR
ERR
* The system will evaluate as negative any response other than "OK"
** The shipment will be made again for 4 more occasions.
Email sent in case of NVIA error notification service
not responding at Date: DD / MM / YYYY Time: HH24: II: SS
any time Nvia error The following url has not responded to any of our access attempts:
notification service http://url.notificacion.del.cliente?productId=45225&countryId=45&ts=&host=9
99999&msisdn=123456789&op=WI&alias=MYSERVICEKEYWORD&serviceId=225
&&id_mensaje=WI0
Please check that the URL is correct and that you are answering correctly.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 14 de 15
D ATA TO PROVIDE FOR INTEGRATION :
Both the client and Nvia must provide the parameters for the development, integration and
production of the service.

For the development and integration phase, Nvia will provide credentials that can be used in
the development environment. Once the development phase is completed, it will be necessary
for the client to facilitate the landing to obtain the pertinent approvals according to the
current legislation in each country.

Nvia side
Nvia will provide the following data that should be used for the use of the interfaces.

Parameter description
clientId Client identifier
countryId Country code where the product will be marketed
user Login Identification credential in the system.
password Password. Identification card.
productId Unique product identifier.

The domains where the interfaces are hosted are the following:

Entorno URL de servicio

Development http://test.panelwap.com/development/
Production http://www.panelwap.com/service/

In each country Nvia will deliver an annex to this document, explaining the exceptions or
customizations associated with the location of the service. In the same way, a guide of good
praxis will be delivered for the accomplishment of the landing pages with the purpose that the
client can build his page according to the effective legislation in each country.

Client side
The following parameters must be provided by the client:

Parámetro Descripción
callbackUrl URL where the user will be redirected in case of success. If this
parameter does not exist, the user will be redirected to the URL
configured by default
not3GCallbackUrl URL where the user will be redirected if they can not be processed via
WAP. If this parameter does not exist, the user will be redirected to the
URL configured by default
errorCallbackUrl URL where the user will be redirected in case of failure. If this
parameter does not exist, the user will be redirected to the URL
configured by default
Subscription Notify URL Client URL where you will receive notifications of subscription events.
Unsubscription Notify Client URL where you will receive notifications of unsubscription events.
URL
Billing Notify URL Client URL where you will receive notifications of billing events.
Contact email Email account where the customer will be alerted of possible incidents
in the service.
Service IP P from where the interfaces will be used. Nvia will need to control that
only from those IPs can services be accessed.

Nvia API Specification for DCB

©Nvia Gestión De Datos SL

Página 15 de 15