Netsize Online Payment SDK - Authentication - Technical Annex 3-c To Mpayment

Netsize Online
Payment -
Software Development Kit
End-User Authentication V1.1
Annex 3-C to Netsize mPayment

Service General Legal Conditions
Date 11/03/09
Document Version 1.8
NS Online Payment SDK
End-User Authentication
Table of Contents
History ...................................................................................................................................... 3
Legal Information .................................................................................................................... 3
Contacts ....................................................................................................................................... 3
Overview .................................................................................................................................. 4
Audience ...................................................................................................................................... 4
What is Netsize End-User Authentication? .............................................................................. 5
Definition...................................................................................................................................... 5
Netsize End-User Authentication notions .........................................................................................5
End-User Authentication process ....................................................................................................6
NOP Test Platform.................................................................................................................... 7
Getting Started ........................................................................................................................ 8
API implementation process ...........................................................................................................8
Requirements ............................................................................................................................... 8
Settings the API methods ........................................................................................................ 9
Authenticate method .....................................................................................................................9
GetUserID method ...................................................................................................................... 12
Appendix ................................................................................................................................ 15
Netsize End-User Authentication localizations ................................................................................. 15
Authentication events .................................................................................................................. 15
Retry Status ................................................................................................................................ 15
Return codes .............................................................................................................................. 16
Connection details to Test platform ............................................................................................... 17
Language ISO codes.................................................................................................................... 18
© Netsize 1998 - 2009. All rights reserved. Confidential. Page 2/2

History
Version Date Comments / Status
1.0 30/06/2006 First version
1.2 06/07/2006 Review of the whole document
1.3 25/07/2006 Update of Appendix section
1.4 01/08/2006 Deletion of countries where Netsize End-User Authentication solution is available.
1.5 09/08/2007 Updates to be documented
Addition of:
• Test platform information
1.6 30/11/2007 • Warning information regarding
the Return URLs
output parameters added by Netsize for implementation reasons.
Update of Test environment URL
Update of:
• Error codes
• URL access
1.7 21/04/2008 • Test Environment URL
Additions of:
• Retry status
• Marketing Use
• Product status, product type and product nature code optional
1.8 11/03/2009 Update of URL to view example of methods (p17)
Legal Information
The information supplied in this document is Netsize S.A. 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.
Netsize™ is protected by French, EEC and international intellectual property laws.
All other trademarks quoted are the sole property of their respective owners.
Contacts
NETSIZE S.A.
75, rue d’Anjou Tel: +33 (0) 1 53 05 58 00
75008 Paris Fax: +33 (0) 1 53 05 59 00
FRANCE
http://www.netsize.com

Overview
Part of the Netsize Online Payment Platform
Audience
This document is intended for technical architects and application developers. Readers are supposed to be
familiar with HTTP requests, XML flows and more generally the Web or WAP development.

What is Netsize End-User Authentication?

Definition
This API allows Customers to retrieve the End-User identity information. This API is useful for Customers
to get the subscription status of each End-User, to know if he has already subscribed to a service and then
to allow (or prevent) him to access content.
This API is based on Payment Provider rules that are transparent for the End-Users.
This API is only available on WAP sites wherever Payment Providers provide automatically End-User
authentication.
For WEB sites, the Customer manages the End-User authentication on his own.
Netsize gets the End-User identity information based on a specific Payment Provider contract.
As soon as the Payment Provider provides a MSISDN, encrypted or not, the Customer can use this API to
get the End-User authentication.
For Payment Providers that do not provide any MSISDN, the Customer shall manage the End-User
authentication on his own to know if he has already subscribed to a service.
This feature is linked to the Netsize Online Payment offer, and can be implemented only within such a project.
As described in the following section, NOP allows integrating NOP API evolutions progressively, without
damaging Customers’ running services thanks to the NOP Test platform.
Netsize End-User Authentication notions

Access Points
Netsize Online Payment is based on a distributed architecture. Customers have therefore to localize the
End-Users to redirect them to the appropriate Netsize Online Payment instance.
Customers shall ask for their Netsize local contact to get the exhaustive list of the countries covered by
Netsize Online Payment.
Accounts
Authentication API uses the same account(s) as those used for other Netsize Online Payment APIs.
AuthenticateExperienceID
Netsize End-User Authentication is a comprehensive single entry point that is able to manage different
channels: WEB, WAP.
AuthenticateExperienceID is a way, for Customers, to define the type of authentication, on a specific
channel.
AuthenticateExperienceID Explanation Comments
Silent WAP Authentication (implies MSISDN This is the only value
10
forwarding). It is transparent to the End-User. authorized.
UserID & MNC

The UserID identifies the End-User. According to Payment Providers, it can be a MSISDN or an encrypted
MSISDN.
End-User Authentication API returns UserID when Payment Providers give this information automatically.
MNC is always returned.
Does Payment Provider provides MSISDN or UserID MNC
enables MSISDN encrypted Forwarding?
Yes Filled Filled
No Not Filled Filled

End-User Authentication process
Steps Description Comments
The End-User accesses the Customer home page.
The Customer home page, calls (from server to server) the

Authenticate method of the API.
The Netsize Online Payment server checks the request and
sends back to Customer an URL where the End-User has to be
redirected.
For instance:
The Customer HTTP server redirects the End-User to the http://NOPes.netsizeonline.com/P3NL/F8BA54
URL returned by the Netsize Online Payment server. 30E2D61C753A7F931E1CCC212AB637D9E8/Au
thenticate.wml
The End-User accesses the NOP server to be
authenticated…
… and is immediately redirected to the Customer page.
The End-User gets connected to the return URL.

The Customer server gets the UserID retrieved on step 4 by
requesting the GetUserId method.
The Customer gets the End-User identifier and is able to
perform a request in his own database to get, for example,
the subscription status of the End-User.

NOP Test Platform

Mobile services follow life cycle from creation to release, and improvements such as country coverage
extension, new billing methods implementation …
Developing and improving services may not require to be really charged each time the payment procedure
is tested.
The NOP test platform enables:
• Running service without waiting for the operator environment provisioning
• Performing as many tests as wanted, without spending remaining credits allowed by operator
subscriptions
• Interfacing new NOP features (e.g. new billing method), keeping current services available for end-
users.
This platform becomes the mandatory step in the development cycle before end-to-end validation in real
operator environment.
How does it work?

Using the same login and password of the usual technical account, the mobile service in development has
to request NOP methods over the specific test platform URL. Switching operational to test platform
requires only changing the URL.
The test platform simulates transactions over a “virtual operator”. These transactions are expected to pass
with standard parameters. However, a price higher than authorized range shall return an error status.
The NOP test platform enables:
• running services with a large range of price points, in several currencies;
• applying a Pay per Use or Subscription scenarios with standard WAP Billing pages or Credit Card;
• using Authentication API;
• analyzing simulated transactions over the Request tool in NOP WebCare.
NOTE: Any technical parameter necessary to run the Test platform is detailed in the Getting Started section.
All details are available in the Appendix section.

Getting Started
API implementation process
This section describes the steps you need to implement to make the Netsize End-User Authentication API
run.
Requirements
The following type of information is necessary to connect to and/or use the Netsize End-User
Authentication API.
1. You provide Netsize with
your HTTP Server IP address to Netsize.
This address, necessary to perform the first request to the Netsize End-User Authentication
platform, is then authorized on the Netsize firewall.
2. Netsize provides you with two types of information, whether you want to run production or test
platform.
1. For Production environment:
one or several login / password parameters, in case you perform billing requests in
different countries;
NOTE: View Security requirements in the following section.
the Netsize End-User Authentication HTTP server address where to perform request.
NOTE: View Appendix section to view some addresses.
2. For Test environment, be aware that the production login/pwd is the same than for production
environment.
Netsize provides you with:
the Netsize Online Payment HTTP server URL where to perform requests in test;
the Netsize Online Payment HTTP server URL where to view examples of methods.
NOTE: View Appendix section to get all necessary details
In addition, Netsize provides you with necessary documentation to perform online payment with
Netsize.
Security requirements
This section lists requirements you shall consider regarding the login/password information and web
service addresses.
Login & password
• Each request of the API needs a login and password.
• End-User Authentication account information is shared with your Netsize Online Payment
account.
• You are responsible to keep this information in a safety place.
• The password has to be encrypted using the SHA1 encryption method.
This method is case sensitive.
NOTE: Customers may find existing algorithm in the System.Web.Security class of
the .NET Framework.
Password to be
SHA1 encryption:
encrypted:
Example 1 Password 8BE3C943B1609FFFBFC51AAD666D0A04ADF83C9D
Example 2 password 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8
SSL
Netsize strongly recommends you to connect using SSL since data transferred through Netsize Web
Service are sensitive and confidential.
SSL guaranties the data encryption of the login and password enclosed in each request performed. The
Netsize End-User Authentication SSL server certificate is signed by Netsize.

Settings the API methods
Authenticate method
Description
This request is used to launch the authentication process.
Request
Authenticate.dll is an HTTP request where input parameters are given by the POST method.
For example – connection to Belgium web server:

https://NOPbe.netsizeonline.com/NUA/1.1/Authenticate.dll
Synopsis
Authenticate(
[in] string Login,
[in] string Password,
[in] string Lang,
[in] int AuthenticateExperienceID,
[in] string ReturnURL,
[in, optional] int ProductNatureCode,
[in, optional] int ProductTypeCode,
[in, optional] int ProductClassCode,
[in, optional] string OptionalParameter1,
[in, optional] string OptionalParameter2,
[in, optional] string OptionalParameter3
[out] int ReturnCode,

[out] int RetryStatus
[out] string Reason,
[out] string URL,
[out] string AuthenticateID,
[out] string Lock
)

Input parameters
Parameter Data type Description Comments
Login String Your login to access this API. This field has to be URL encoded. Mandatory
Provisioned by Netsize
Password String The password corresponding to the login. Mandatory
It is case sensitive and must be encrypted using SHA1
method.
This field has to be URL encoded.
Password to
SHA1 encryption:
be encrypted:
Lang String A 2-letters ISO code. For details, refer to the ISO Code list in the Mandatory
Appendix section. This field has to be URL encoded.
Authenticate Integer A unique identifier Netsize has defined to manage End-User Mandatory
ExperienceID Authentication.
The only value authorized is 10, i.e. Silent WAP Authentication.
ReturnURL String Return URL that will be called after the Authentication process. Mandatory
The nature of the page depends on the
AuthenticateExperienceID.
The only value authorized is 4, i.e. WAP page.
This URL has to be URL encoded as shown in the example
below:
Example:
URL: http://www.YourWebSite.com/index.aspx?a=0&b=2
Encoded URL http%3a%2f%2fwww.YourWebSite.com%2findex.aspx%3fa%3d0%
26b%3d2
WARNING: Return URLs shall always begin by http or https. Any other
type of return URL will fail.
ProductNatureCode Integer A list of values used to identify type of product delivered. Optional
Code Label
1000 Phone
2000 Web
3000 Service
4000 Physical
ProductTypeCode Integer A list of values used to identify type of product delivered. Optional
Code Label Code Label Code Label
100 News 106 Home 112 Information
101 Business 107 Food 113 Opinion
102 Sport 108 Gambling 114 Debate
103 Entertainment 109 Search 115 Voting
104 Travel 110 Mobile games 116 Image
105 Shopping 111 Guide 117 Tone
ProductClassCode Integer A list of values used to identify type of product delivered. Optional
Code Label
1 Adult
2 Other
OptionalParameter1 String Field dedicated to your purpose. This field has to be URL Optional
encoded.
encoded.
encoded.

Output parameters
Authenticate method returns an XML flow with the following parameters:
Parameter Data type Description
ReturnCode Integer 0 means that Authenticate request is validated. Any other value implies that there
was an error.
See Appendix section for the exhaustive list.
RetryStatus Integer Gives the retry possibility associated to the error
Reason String Gives the reason why the request was rejected.
ReturnCode is different from 0.
XML encoded field
URL String URL where to redirect the End-User
This field is not filled if ReturnCode is different from 0.
XML encoded field
AuthenticateID String Unique identifier of the Authentication transaction on the Netsize End-User
Authentication platform.
Customer should store this key as this is the only identifier of the transaction.
XML encoded field
Lock String Hash key of the transaction.
XML encoded field
Example:
<?xml version="1.0" encoding="utf-8" ?>
<AuthenticateOutput xmlns:ns1="http://www.netsize.com/webservices/">
<ReturnCode>0</ReturnCode>
<RetryStatus>0</RetryStatus>
<Reason>Success</Reason>
<Url>http://nopse.netsizeonline.com/MPN9G2Y/3B6AF8/Authenticate.aspx</Url>
<AuthenticateID>MPN9G2Y</AuthenticateID>
<Lock>3B69DAF8B5859A830A9156FF40899B2410605E8F</Lock>
</AuthenticateOutput>
You shall make sure that

• your application is configured in a way to ignore some new output parameters, added in the returned
XML flow, when necessary for Netsize to implement new features;
• your application tests all return codes for each request;
• the return code is set to 0 when successful; any other value is an error;
• errors are correctly logged.
For more information on return codes, refer to the Appendix section Return / error codes.

GetUserID method
Description
This request is used to retrieve a UserID from an AuthenticateiID.
Request
GetUserID.dll is an HTTP request where input parameters are given by the POST method.
For example – connection to Belgium web server:

https://NOPbe.netsizeonline.com/NUA/1.1/GetUserID.dll
Synopsis
GetUserID(
[in] string Login,
[in] string Password,
[in] string AuthenticateID,
[in] string Lock
[out] int ReturnCode,

[out] int RetryStatus,
[out] string Reason,
[out] string AuthenticateStatus,
[out] string AuthenticateEvent,
[out] string UserIDType,
[out] string UserID,
[out] string MarketingUse,
[out] int MCC,
[out] int MNC,
[out] string OptionalParameter1,
ErrorDetail(
[out] integer LastReturnCode,
[out] integer LastRetryStatus,
[out] string LastReason
)
)
Input parameters
Parameter Data type Description Comments
Login String Your login to access this API. This field has to be URL encoded. Mandatory
Provisioned by Netsize
Password String The password corresponding to the login. Mandatory
It is case sensitive and must be encrypted using SHA1 method.
Password to
SHA1 encryption:
be encrypted:
AuthenticateID String The unique transaction identifier received on the Authenticate Mandatory
method.
Lock String The hash key of the transaction identifier. Also returned by the Mandatory
Authenticate method.

Output parameters
The GetUserID method returns an XML flow with the following parameters:
Parameter Data type Description
ReturnCode Integer 0 means that GetUserID request is validated. Any other value implies that there was
an error.
RetryStatus Integer Gives the retry possibility associated to the error.
Reason String Gives the reason why the request was rejected.
ReturnCode is different from 0.
XML encoded field
AuthenticateStatus Integer Indicates the exact status of the Authentication.
Code Value Comment
1 Pending Authentication is pending.
2 Authenticated The Authentication succeeded.
3 Not Authenticated The Authentication failed.
AuthenticateEvent Integer Gives detailed information in case the transaction is in status Pending or Not
Authenticated.
UserIDType Integer Defines what the UserID field contains. It is only filled if Return code is different from
0.
Code Value Explanation / UserID field result
Netsize End-User Authentication cannot get any
0 Unknown End-User identifiers.
Field UserID will be blank.
1 MSSIDN Field UserID should contain a real MSISDN.
2 Encrypted MSISDN Field UserID should contain an encrypted MSISDN.
UserID String Identifies the End-User. This value depends on the UserIDType field.
XML encoded field
MarketingUse String Allow Merchants to use End-user’s MSISDN for marketing cases.
Code Explanation
0 Not allowed to use
1 End-user’s MSISDN use is free
2 Merchant needs to ask End-User’s opt-in before using the MSISDN
MCC Integer Mobile Country Code of the Payment Provider to which the End-User has subscribed.
MNC Integer Mobile Network Code of the Payment Provider to which the End-User has subscribed.
OptionalParameter1 String Optional parameter given as input on the Authenticate method.
XML encoded field
XML encoded field
XML encoded field
LastReturnCode Integer Last error code returned for this transaction
LastRetryStatus Integer Last retry status associated with the last return code
LastReason String Last reason of the last error code

Example:
<?xml version="1.0" encoding="utf-8" ?>
<GetUserIDOutput xmlns:ns1="http://www.netsize.com/webservices/">
<ReturnCode>0</ReturnCode>
<RetryStatus>0</RetryStatus>
<Reason>Success</Reason>
<AuthenticateStatus>2</AuthenticateStatus>
<AuthenticateEvent>201</AuthenticateEvent>
<UserIDType>1</UserIDType>
<UserID>+33672221439</UserID>
<MarketingUse>1</MarketingUse>
<OptionalParameter1></OptionalParameter1>
<ErrorDetail>
<LastReturnCode>0</LastReturnCode>
<LastRetryStatus>0</LastRetryStatus>
<LastReason>Success</LastReason>
</ErrorDetail>
</GetUserIDOutput>
You shall make sure that

• your application is configured in a way to ignore some new output parameters, added in the returned
XML flow, when necessary for Netsize to implement new features;
• your application tests all return codes for each request;
• the return code is set to 0 when successful; any other value is an error;
• errors are correctly logged.
For more information on return codes, refer to the Appendix section Return / error codes.

Appendix
Netsize End-User Authentication localizations
Depending on the End-User country, you will need to connect to corresponding Netsize Web server dedicated
to the Netsize End-User Authentication API.
The following table gives a non-exhaustive list of Netsize Web server addresses.
Country MCC Netsize Web server address
Belgium 206 https://NOPbe.netsizeonline.com/NUA/1.1
Germany 262 https://NOPde.netsizeonline.com/NUA/1.1
Spain 214 https://NOPes.netsizeonline.com/NUA/1.1
Sweden 240 https://NOPse.netsizeonline.com/NUA/1.1
Authentication events
Status Code Authentication Event
1 100 Waiting End-User Access
Pending 101 Pending
2
201 Success
Authenticated
301 Operator Not Found
3 302 User Id Not Found
Not Authenticated 310 Internal Error
320 No End-User Access
Retry Status
The customer should consider following delays as non-binding and should use it to improve retry policy.
Code Reason
0 Retry is not necessary.
1 Merchant can retry within 1 minute.
2 Merchant can retry within 1 hour.
3 Merchant can retry within 1 day.
4 Merchant can retry within 1 week.
5 Merchant can retry within 1 month.
6 Merchant can retry next mandate period (will not be return in Authenticate API).

Return codes
Errors are split in four tables depending on the origin. 0 return code is used as success code.
End-User Error Codes

Code Reason Explanation
1001 End-User Authentication Failed Unable to identify the End-User
1002 End-User Not Allowed The End-user is not allowed to access the service
1010 End-User Missing Mandatory Parameter One or more required fields are not provided by the End-
User.
1011 End-User Sent An Invalid Parameter Invalid parameter value (NULL, wrong type …).
1012 End-User Sent An Invalid Request
1030 End-User Cancelled This Transaction End-User cancelled his purchase
1031 End-User Closed This Transaction
1040 End-User Connection Error End-User disconnected or timed out
Merchant Error Codes

2001 Merchant Authentication Failed Possible explanations are:
• Wrong password for login;
• Login does not exist;
• Login does not belong to the organization.
2002 Merchant Not Allowed Merchant is not allowed to access this payment platform
or on the P.P.
2010 Merchant Missing Mandatory Parameter One or more required fields are not provided.
2011 Merchant Sent An Invalid Parameter Invalid parameter value (NULL, wrong type, …).
2015 Merchant Sent An Invalid Transaction ID The transaction ID parameter is invalid.
2016 Merchant Sent An Invalid Lock The transaction Lock parameter is invalid.
2017 Merchant Sent A Duplicate External ID This External transaction ID was already sent for this
country.
2020 Merchant Reached a Threshold You reached a P.P. Threshold.
2025 Merchant Request is not allowed Possible explanations are:
• Price exceed limit mandate amount
• Price exceed maximum price per event
• Request already done
• Transaction / Mandate not authorized / closed.
2030 Merchant Rejected / Cancelled This
Transaction
2031 Merchant Closed This Transaction
Netsize Error Codes

3030 Netsize Rejected / Cancelled This Netsize cancelled this transaction.
Transaction
3031 Netsize Closed This Transaction
3045 Provisioning Error A mandatory parameter is missing during a Netsize
internal process. Please ask your Netsize local contact.
3050 Internal Error Please ask your Netsize local contact.
Payment Provider Error Codes

4010 P.P. Missing Mandatory Parameter One or more required fields are not provided by the P.P.
4030 P.P. Rejected / Cancelled This request P.P. rejected this request.
4040 P.P. Connection Error P.P. disconnected or timed out.
4041 P.P. Overload P.P. cannot handle a large amount of requests.
4050 P.P. Internal Error Please ask your Netsize local contact.

Connection details to Test platform
To connect to the Test Platform, you need the following information.
A login / password:
use the one you already have for accessing NOP Production platform
An URL to access the Test platform:
http://nopqa.netsizeonline.com/QA1/
An URL to view examples of methods:

http://nopqa.netsizeonline.com/QA1/NUA/1.1/Authenticate.dll
http://nopqa.netsizeonline.com/QA1/NUA/1.1/GetUserID.dll
View test transactions in NOP WebCare

From your NOP WebCare, you can track fake transactions thanks to the Request Tool.
To process, just filter the Access Point to NOP QA.
All 0-shop transactions are the ones performed in test, providing you have appropriately set any shop
parameter of you billing APIs to 0.

Language ISO codes

The following table lists, for each language, the related ISO language code.
Language ISO code Language name
BE Belgian
DA Danish
DE German
EN English
ES Spanish
FI Finish
FR French
IT Italian
NL Dutch
NO Norwegian
PL Polish
PT Portuguese
SV Swedish

Netsize Online Payment SDK - Authentication - Technical Annex 3-c To Mpayment

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Netsize Online Payment SDK - Authentication - Technical Annex 3-c To Mpayment

Diunggah oleh

Hak Cipta:

Format Tersedia

Netsize Online

Annex 3-C to Netsize mPayment

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 2/2

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 3/3

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 4/4

What is Netsize End-User Authentication?

Netsize End-User Authentication notions

UserID & MNC

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 5/5

End-User Authentication process

Steps Description Comments

The End-User accesses the Customer home page.

The Customer home page, calls (from server to server) the

… and is immediately redirected to the Customer page.

The End-User gets connected to the return URL.

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 6/6

NOP Test Platform

How does it work?

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 7/7

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 8/8

For example – connection to Belgium web server:

[out] int ReturnCode,

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 9/9

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 10/10

You shall make sure that

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 11/11

For example – connection to Belgium web server:

[out] int ReturnCode,

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 12/12

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 13/13

You shall make sure that

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 14/14

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 15/15

End-User Error Codes

Merchant Error Codes

Netsize Error Codes

Payment Provider Error Codes

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 16/16

An URL to view examples of methods:

View test transactions in NOP WebCare

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 17/17

Language ISO codes

© Netsize 1998 - 2009. All rights reserved. Confidential. Page 18/18

Anda mungkin juga menyukai