Payment API Single Entry Point flow€¦ · Payment API Single entry point flow Integration Copyright © 2013 Centili | All rights reserved | Payment page will be loaded using Country
Post on 07-Jul-2020
4 Views
Preview:
Transcript
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
Payment API Single Entry
Point flow
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | 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
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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 :
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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):
http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb
&price=1.5&returnurl=http://www.google.com&reference=DemoForDocument
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
If parameter country=GB is added than MNO page for entering Pin will be shown
http://api.centili.com/payment/widget?apikey=971014d1755c5a07de61e6a8751655cb&country=gb
&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:
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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) :
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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.
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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×tamp=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.
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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
Centili_PPO@infobip.com
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×tamp=1449502720750
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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×tamp=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
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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×tamp=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)
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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"
}
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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
sign (def0a0ba4f188cf174d383dc4d7f7041e358ba92) Signature parameter
created using issued key for signing request (optional)
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.
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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
sign (def0a0ba4f188cf174d383dc4d7f7041e358ba92) Signature parameter
created using issued key for signing request (optional)
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
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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
timestamp - used to differentiate every request as unique one per
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×tamp=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
timestamp - used to differentiate every request as unique one per
sign Signature parameter created using issued key for signing request (optional)
Payment API Single entry point flow Integration
Copyright © 2013 Centili | All rights reserved | www.centili.com
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
sign (def0a0ba4f188cf174d383dc4d7f7041e358ba92) Signature parameter
created using issued key for signing request (optional)
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
top related