payment api single entry point flow€¦ · payment api single entry point flow integration...

Payment API Single entry point flow Integration

Copyright © 2013 Centili | All rights reserved | www.centili.com

Payment API Single Entry

Point flow

https://www.centili.com/



Table of Contents Introduction ...........................................................................................................................3

How to integrate ....................................................................................................................3

Redirection before/after payment transaction ......................................................................7

Subscription identification mechanism................................................................................ 10

Unsubscribe process ........................................................................................................... 14

User identification ............................................................................................................... 15

Transaction refund .............................................................................................................. 16




Introduction

Centili provide straight forward integration into our payment system via API called

Single Entry Point. This type of integration allows very easy integration process with

minimum effort required from your side.

This kind of flow provides better end user experience and higher conversion rates.

Integration of our payment system into your solution is simply done by redirecting

end user from your solution to our payment link. Based on the fact that there is only

one action needed for this type of integration we called it Single Entry Point Integration

(SEP integration).

How to integrate

In order to start payment process under Centili platform you are requested to

redirect user to Centili SEP redirect URL given below:

http://api.centili.com/payment/widget?

Adding parameters to redirect URL will define flow which will be presented to end

user during payment. API key is the only mandatory parameter which must be sent

and is issued by Centili in order to start payment process.

Redirect URL will be :

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a875165

5cb&country=gb

When opening redirect URL payment page will be loaded.

For current example page opened from UK will look like this :




http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb




Payment page will be loaded using Country GeoIP recognition from your current

location. In order to see how will page look like for some other country you can add

parameter country=XX where XX is international country code prefix (e.g. for United

Kingdom prefix is GB).

All possible initiation parameters are given below:

apikey - Service key Centili issued, unique for every payment service.

e.g. apikey= f31a355df6dad07e49ba474db7ff9b07 mandatory

price - e.g. price=1.45 optional if you wouild like to skip page where

end user is choosing price this parameter must be added

operator -

end user belongs to, e.g. ES_VODAFONE optional- in some cases it is

possible to skip page for entering msisdn if this parameter has been sent

msisdn - e.g. 381631234567 optional page for entering msisdn will

be skipped if msisdn parameter is sent

returnurl - URL to which user is redirected after successful payment e.g.

returnurl=http://www.google.com - optional reference unique identification parameter under your system (pass-

through variable) e.g. reference=appID1 - optional userid identification of the end user performing payment optional redirecttimeout - redirect timeout in seconds (0 instant redirect on status

page > 0 wait for auto redirect)

sign represents signed string of all concatenated request parameters

sorted alphabetically with Centili issued key using previously agreed

encoding algorithm e.g. 1f7a5457f65f745787h7a7e578

In case of successful initiation Centili will complete all steps needed for successful

transaction. During payment process Centili system can prompt user for entering

optional parameters if those are not sent in initial request.

One example of properly set initiation URL for UK can be found below (country GB,

price 1.5 GBP, with return URL and reference):


&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument


http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument



If parameter country=GB is added than MNO page for entering Pin will be shown


&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument&operator=GB_O2

Please be aware that changing request parameters sent in initial request on SEP

redirect URL will define desired flow. Flow also depends on technology supported by

MNO`s in desired country.

Given example is for UK and represents DMB Pin flow. If in desired country only

available technology for mobile payments is Premium SMS than flow will differentiate

on last step where MNO page is displayed. Instead of MNO page instruction for sending

SMS will be shown and it will look like this:


http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument&operator=GB_O2

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument&operator=GB_O2



In this example instruction for sending SMS with content TEST to shortcode 80556

is localized to United Kingdom with price of 1.00 GBP. (In this case we have added few

parameters and localized flow and number of pages shown to the end user.

Example request is given below:

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a875165

5cb&country=gb&language=en&returnurl=http://www.google.com&reference=DemoF

orDocument&msisdn=447773511688

Furthermore, flow can be adjusted by enabling WAP in countries where WAP

identification is possible. Such kind of flow is possible on demand only. For the list of

possible countries where WAP can be enabled please contact your dedicated Account

Manager.

Example of DMB flow with PIN and WAP (one tap) billing pages through Vodafone,

Spain are presented below:

DMB: pin required WAP (one tap) :


http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb&language=en&returnurl=http://www.google.com&reference=DemoForDocument&msisdn=447773511688





In this case example of request is given below:

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=es

&returnurl=http://www.google.com&reference=DemoForDocument&price=1.50&msisdn=34666603561

Request will be the same in both cases(for DMB and WAP). Difference between DMB

and WAP will be set on Centili side. Please keep in mind that those pages are payment

pages of Mobile Network Operator and in most cases are not subject of change and

could not be customized.

Redirection before/after payment

transaction

Based on the flow and the country for which payment has been initiated Centili

widget will automatically use its advanced features to identify user and his

subscription. If there is a way to identify end user and identification of the user went

successfully we will try to check his subscription status under our system.

If you are trying to subscribe end user which is already subscribed to Centili system

we will do automatic redirection to returnurl initially sent in payment request.

Parameters received back will contain information about user subscription and

according to those values you can base your logic to turn user to content directly if he

is subscribed.

Redirection process after successful, canceled or failed transaction depends on

parameters sent in initial request. In cases when is sent with valid value

user will be returned to URL specified. In case of this parameter not being sent in initial

request, our system will display default final payment page and remain on it.

In case when user is redirected to return URL, our system will forward additional

parameters in order to supply you with all necessary data about the particular

transaction and its status.

Those parameters will be added to return URL and are described below:

When initiating payment request for subscription services our Widget will

automatically check is there any active subscription under our system for current user,

and if user is not subscribed will proceed to payment. In case of one-time payment

requests end user will be forwarded to payment page immediately by skipping this

check.


http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=es&returnurl=http://www.google.com&reference=DemoForDocument&price=1.50&msisdn=34666603561

http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=es&returnurl=http://www.google.com&reference=DemoForDocument&price=1.50&msisdn=34666603561



Parameter list which will be returned back is presented below:

trid unique identifier of transaction in Centili system e.g. 34212026

userid - identification of the end user performing payment

status status of finished transaction (success or failed)

reference - unique identification parameter under your system (pass-

through variable) e.g reference=appID1

operator end user mobile network operator

subscriptionid optional parameter- if user is subscribed you will get

id of his subscription under Centili system

activesub optional - gives you information is user already subscribed

to this service

validsub optional - gives you information was user charged in the past

for the service and

timestamp - used to differentiate every request as unique unix time

sign - represents signed string of all concatenated request parameters

sorted alphabetically with Centili issued key using previously agreed

encoding algorithm e.g. 1f7a5457f65f745787h7a7e578

If you are trying to subscribe end user to subscription service to which he is already

subscribed you will get additional params and ( values can be

true or false ) If he is already subscribed you should provide him with content

immediately (the same thing should occur if he has valid but not active subscription).

In case when subscription is neither valid nor active user will be redirected to payment

page.

In our above mentioned example where return URL is set to be Google user will be

redirected to :

http://www.google.com?trid=XXX&status=XXX&userid=XXX&reference=DemoForD

ocument&sign=12a4fs3d6aXXXXXXXXX

If user is subscribed to current service to which you are trying to subscribe him end

user will be returned back to :

http://www.google.com?userid=60165175712&activesub=true&validsub=true&sub

scriptionid=3685958&timestamp=1449069171015

Following this example for subscribe process you can see that user have active

subscription under our system and that user should be redirected to content.


http://google/

http://www.google.com/?trid=XXX&status=XXX&userid=XXX&reference=DemoForDocument&sign=12a4fs3d6aXXXXXXXXX

http://www.google.com/?trid=XXX&status=XXX&userid=XXX&reference=DemoForDocument&sign=12a4fs3d6aXXXXXXXXX

http://www.google.com/?userid=60165175712&activesub=true&validsub=true&subscriptionid=3685958&timestamp=1449069171015

http://www.google.com/?userid=60165175712&activesub=true&validsub=true&subscriptionid=3685958&timestamp=1449069171015



Redirection parameters when payment is being canceled :

If transaction is CANCELED before user entered his mobile number into Centili

widget user will be returned back to initially sent returnurl during payment request

with params: status=canceled.

If transaction is CANCELED by user during payment flow we will return user back

to returnURL with following params:

status=canceled,

trid=231xxxxx,

userid= <userid>,

msisdn=<enduser_msisdn>,

operator=<enduser_mno>,

reference=<your_transaction_identifier >.

If transaction is in FAILED state some error occurred during payment flow and

user will also be returned back with following parameters:

status=failed,

trid=231xxxxxx,

userid=<userid>,

reference=<passthrough variable from your system>,

error_description=<description of the error which caused transaction to

fail>

Depending on the country parameter list can be different during redirection. For

final update please check with Centili Platform Operations team via

[email protected]

If status of payment flow is SUCCESS end user will be redirected to returnurl and

end user should be redirected directly to content.

One example of the redirection flow both for One Time and Subscription is presented

below:

OTP:

http://www.google.com?trid=123456789&status=success&userid=testuser&refere

nce=DemoForDocument&sign=12a4fs3d6aXXXXXXXXX

Subscribe:

http://www.google.com?status=success&operator=XXXXXXX&reference=201512d4

5xxxxxxxx&userid=34xxxxxxx&msisdn=346668xxxxx&timestamp=1449502720750


http://www.google.com/?trid=123456789&status=success&userid=testuser&reference=DemoForDocument&sign=12a4fs3d6aXXXXXXXXX

http://www.google.com/?trid=123456789&status=success&userid=testuser&reference=DemoForDocument&sign=12a4fs3d6aXXXXXXXXX

http://www.google.com/?status=success&operator=XXXXXXX&reference=201512d45xxxxxxxx&userid=34xxxxxxx&msisdn=346668xxxxx&timestamp=1449502720750

http://www.google.com/?status=success&operator=XXXXXXX&reference=201512d45xxxxxxxx&userid=34xxxxxxx&msisdn=346668xxxxx&timestamp=1449502720750



In some cases when WAP flow is enabled you can get also unique identifier of the

Subscription identification mechanism

Subscription identification with user redirection:

In order to identify valid subscription you need to redirect users on our identification URL.

http://api.centili.com/payment/pages/subIdentify.jsf

Parameters which have to be sent using GET method are:

apikey - Application key Centili issued, unique for every payment service

e.g. apikey= f31a355df6dad07e49ba474db7ff9b07

returnurl - URL to which user is redirected after identify process

e.g. returnurl=http://www.google.com

timestamp - used to differentiate every request as unique one per

sign - Signature parameter created using issued key for signing request (optional)

After that user will be redirected to your return URL sent in initial request and we

will return user back with additional parameters which will validate subscription.

One example of Sub Identify Request is given below:

http://api.centili.com/payment/pages/subIdentify.jsf?apikey=1111111111&returnurl=http://w

ww.merchant.com&timestamp=1409757900&sign=f71bfbf1c75bab0da59f4bb6cdab4b7450988

f06

Once successful identification occurs we will trigger your return URL and send

following data using regular HTTP GET method:

userid -Unique userID under Centili platform

timestamp - desired timestamp for checking subscription validation, Unix time

sign - Signature parameter created using issued key for signing request


http://api.centili.com/payment/pages/subIdentify.jsf

http://api.centili.com/payment/pages/subIdentify.jsf?apikey=1111111111&returnurl=http://www.merchant.com&timestamp=1409757900&sign=f71bfbf1c75bab0da59f4bb6cdab4b7450988f06





If userid is returned back than user has valid subscription under Centili System,

otherwise user doesn't have valid subscription and should proceed to payment.

For above mentioned example, after initial subscription identification request

following URL will be triggered based on return URL parameter previously sent in

initial request:

http://www.merchant.com/?userid=username&timestamp=1409755651301&sign=def

0a0ba4f188cf174d383dc4d7f7041e358ba92

where:

userid (e.g username) means that subscription is active under Centili

system type string

timestamp (1409755651301) - used to differentiate every request as

unique ,Unix time

sign (def0a0ba4f188cf174d383dc4d7f7041e358ba92) Signature parameter

created using issued key for signing request (optional)

This timestamp is additional parameter which is mandatory for each request.

Timestamp parameter allows Centili system to differentiate every request as unique

one, so fraudulent activities can be eliminated together with signature through sign.

Subscription identification using unique user identifier

In order to identify valid subscription you need to send JSON formatted request to

our subscription identification URL.

https://api.centili.com/payment/rest/subidentify?

Parameters which have to be sent using POST method are:

apikey - Application key Centili issued, unique for every payment

service e.g. apikey= f31a355df6dad07e49ba474db7ff9b07

userid - unique user identifier-userid used when user initiated his

subscription process e.g. userid=3466603421 or userid= =1-A-3214ASD

timestamp - used to differentiate every request as unique one unix time

sign - Signature parameter created using issued key for signing request

(optional)


http://www.merchant.com/?userid=username&timestamp=1409755651301&sign=def0a0ba4f188cf174d383dc4d7f7041e358ba92

http://www.merchant.com/?userid=username&timestamp=1409755651301&sign=def0a0ba4f188cf174d383dc4d7f7041e358ba92

https://api.centili.com/payment/rest/subidentify?



If subscription identification process has been executed successfully you will get

appropriate HTTP response STATUS 200 OK.

JSON formatted response will contain following parameters:

activesub - true or false depending on subscription status- e.g if user

is subscribed you will get active=true

validsub - true or false depending on fact was end user charged during

last renewal attempt for subscription period

msisdn - original end user msisdn number

operator - original end user mobile network operator

expirationdate unix timestamp

userid

process

One example of SubIdentify Request is given below:

POST request to https://api.centili.com/payment/rest/subidentify?

JSON formatted params:

{

"apikey":"278e9ea30d473dbfb5609b90de4572b9",

"userid":"60165175712",

"timestamp":"1449063016",

"sign":"1a72cf7dc8032e1c1d4ce457ef68e1988ea25893"

}

Response: HTTP Status 200 OK

Params:

{

"active": "true",

"valid": "true",

"msisdn": "60165175712",

"operator": "MY_DIGI",

"userid": "60165175712"

}


https://api.centili.com/payment/rest/subidentify



where:

activesub=true means that subscription is active under Centili system and

you should not try to subscribe user once again

validsub=true means that user was already charged in the past and that

he should still receive service for his payment

msisdn end user mobile number

operator end user operator

expirationdate - moment in the future until end user subscription is valid



If parameters active and valid are both with returned value false you should try to

perform payment process.

If parameter active is true while valid is false than user renewal charge process is

pending and you should wait for payment to occur.

If parameter active is false but valid is true you should send user directly to his

content because he already paid and he is not able to pay once again.




Unsubscribe process

In order to unsubscribe user from Centili platform you must use HTTP POST method

on following URL with described parameters in application/json format.

Opt-out URL: http://api.centili.com/payment/rest/optout

Parameters:

subscriptionid - optional, if subscription id is used than user id parameter can

be skipped type string

userid - optional , if user id is used than subscription id parameter can be

skipped type string

apikey - mandatory - service key issued from Centili platform - type string

timestamp - mandatory - Unix time calculated from 1 January 1970



One example for unsubscribe request JSON formatted is given below:

URL: http://api.centili.com/payment/rest/optout

Method: POST

Content type: application/json

{

"subscriptionid":"3466xx",

"apikey":" cd309e5822e5d5d5d5d5ecc6c8d6042c2a8b",

1409755651301

5d5ecc6c8d6042c2a8bf6t3g2a1d3b7m2v5673gf32

}

Possible server response to your request can be:

HTTP 202 unsubscribe successful user has been successfully unsubscribed

HTTP 400 bad request unsubscribe request is bad

HTTP 406 not accepted if subscription has expired

HTTP 500 server error if some unexpected internal server errors occurs


http://api.centili.com/payment/rest/optout

http://api.centili.com/payment/rest/optout



User identification

Use of internet on mobile phones gives us opportunity to identify user and his

MSISDN number. In some cases recognized number can be some hashed value instead

of his msisdn. One user identified through Centili identification system while using

mobile internet will always have the same value of identification params.

In order to identify user you have to redirect him to :

http://api.centili.com/payment/pages/userIdentify.jsf

Parameters which have to be sent are:

apikey - Application key Centili issued, unique for every payment service

e.g. apikey= f31a355df6dad07e49ba474db7ff9b07

returnurl - URL to which user is redirected after identify process

e.g. returnurl=http://www.google.com


sign - Signature parameter created using issued key for signing request (optional)

One example of correctly configured URL for user identification is:

http://api.centili.com/payment/pages/userIdentify.jsf?apikey=971014d1755c5a07d

e61e6a8751655cb&returnurl=http%3A%2F%2Fwww.google.com&timestamp=140975

5651301&sign=5d5ecc6c8d6042c2a8bf6t3g2a1d3b7m2v5673gf32

When identification is finished user will be redirected back to return URL sent in

initial request with following params :

identid unique identification ID of user in Centili system must be used for

initiating charge process

msisdn - e.g. 381631234567 optional page for entering msisdn will be

skipped if msisdn parameter is sent

operator returned back if user is identified


sign Signature parameter created using issued key for signing request (optional)


http://api.centili.com/payment/pages/userIdentify.jsf

http://api.centili.com/payment/pages/userIdentify.jsf?apikey=971014d1755c5a07de61e6a8751655cb&returnurl=http%3A%2F%2Fwww.google.com&timestamp=1409755651301&sign=test






Transaction refund

In order to refund user with money deducted from his balance through payment

process over Centili platform you must use HTTP POST method on following URL with

described parameters in application/json format.

Refund URL: http://api.centili.com/payment/rest/refund

Parameters:

transactionid id of the original transaction which would like to be refunded

type string

timestamp - mandatory - Unix time calculated from 1 January 1970



One example for refundrequest JSON formatted is given below:

URL: http://api.centili.com/payment/rest/refund

Method: POST

Content type: application/json

{

"transactionid":"7433346xxx",

5d5ecc6c8d6042c2a8bf6t3g2a1d3b7m2v5xxxxx

}

Possible server response to your request can be:

HTTP 202 refund successful user amount has been successfully refunded

HTTP 400 bad request refund request is bad

HTTP 406 not accepted if refund is not supported for that transaction

HTTP 500 server error if some unexpected internal server error occurs


http://api.centili.com/payment/rest/refund

payment api single entry point flow€¦ · payment api single entry point flow integration...

Documents