payment api - centili · centili api web service (payment api uri) merchant must expose following...
TRANSCRIPT
Payment API
1. Change Log .......................................................................................................... 3
2. Introduction .......................................................................................................... 4
3. Flow summary ...................................................................................................... 4
3.1 Flow Overview ............................................................................................................. 4
3.2 Premium SMS flow ..................................................................................................... 6
3.3 Pin Flow ...................................................................................................................... 7
3.4 Redirect Flow .............................................................................................................. 8
3.5 SMS Handshake Flow ................................................................................................. 9
4. One-time payment API........................................................................................ 10
4.1 Step 1: Payment Initialization ................................................................................... 10
4.2 Exception / Mid step for Singapore ....................................................................... 12
4.3 Step 2: Payment Flow notification ............................................................................ 15
4.4 Payment flow and status information................................................................... 16
4.5 Step 3: Payment data update ................................................................................... 17
4.6 Step 4: Payment update status ................................................................................ 19
4.7 Step 5: Final Payment result notification(??) ........................................................... 19
5. Mobile subscriptions API .................................................................................... 21
5.1 Subscription initiation example ................................................................................ 21
5.2 Unsubscribe initiation example ................................................................................ 23
5.3 Administration unsubscribe example ...................................................................... 25
5.4 Subscription status ................................................................................................... 27
6. Obtaining price identificators ............................................................................. 28
6.1 Obtaining packages example ................................................................................... 28
6.2 Obtaining intervals example .................................................................................. 31
6.3 Obtaining MNO codes ............................................................................................... 33
6.4 Obtaining service info ............................................................................................... 35
1. Change Log
Version Description Date
1.1 Upgrade of system from version 1.0 26.07.2013.
Added parameters revenuePreferred and currencyPreferred in
Obtatining price packages [6.1]
02.09.2013.
1.2 Upgrade of system from version 1.1 25.09.2013.
1.3 Added returnurl parameter 25.10.2013
1.4 18.06.2014
2. Introduction
This API document describes web and mobile initiated purchase flows and parameters. At
this moment we have described 4 different purchase flows that user might encounter
during the purchase process with our service. These flows are heavily dependent on
technology provided by the mobile network operators. However we are constantly
improving the flows and purchase experience. Partner might not implement all the
supported flows since some targeted destinations / countries might use only limited
number of flows.
You might also use Centili Identification service document in case of wap channel. Please
refer to Identification service document for further instructions.
3. Flow summary
1. Merchant calls Payment API restful web service and initiates payment
2. Charge notification is asynchronously delivered on server notification
URI (configured in Partner Panel)
Requirements
Centili exposes following web service:
Centili API web service (Payment API URI)
Merchant must expose following web service:
Payment Notification web service (notification URI)
3.1 Flow Overview
Step 1
Every payment transaction is initiated via IntitiatePayment web method with MSISDN as
one of the parameters. In case of mobile flow this parameter can be omitted. Centili
system will query this MSISDN against our HLR lookup system internally in order to
resolve the home network of the subscriber.
Step 2
Once the home network and the flow are resolved on Centili side, partner response url will
be invoked with the detailed flow parameters.
Steps 3 and 4
Furthermore depending on the flow type partner might or might not implement the steps 3
and 4 as they are specific for One Time Pin flow and in case of other flows they can be
omitted.
Step 5
Finally each transaction is finalized by triggering notification URL with actual payment
result.
Figure bellow represents logical overview of the integration points between partner and
Centili system.
Web Payments:Centili provides support for 4 separate flows for Web payments:
1. Premium SMS flow. For backward compatibility reasons, we do support the flow
with premium SMS reply for some territories.
2. Pin Flow. This flow is the preferred flow for mobile payments on the web. One-
Time-Pin is generated on Centili side and sent to the user.
3. Redirect. In this case Partner is required to redirect the user to the operator
landing page in order to complete the transaction.
4. SMS Handshake. This flow actually uses direct billing interface with MO SMS
confirmation from the user.
Wap/OneTap Payments on mobile devices:
1. Redirect Flow to Operator landing page.
3.2 Premium SMS flow
There are two different flows in premium SMS technology that can be provided by Mobile
Network Operators:
Flows in which payments are made immediately after the message is sent to a
provided short code (MO flow)
Flows in which payments are made after final message is received on the mobile
phone (MT flow)
Centili platform provides support for both of these cases depending on Partner business
needs.
MO billing: When user enters phone number and initiates payment he will be provided with
-short code, CENT-keyword).
After Mobile Network Operator (MNO) receives this MO SMS from the user it charges him
for the service and informs Centili about successful payment. In the next step Centili will
replay on it with MT notification to the User witch can be customized by Partner. At this
point process is completed and we will send payment notification to our Partner.
MT billing: When Mobile Network Operator (MNO) receives MO SMS from the user it just
forwards it to Centili. Then we will replay with MT notification message which is
chargeable for the end user. After processing of this MT SMS MNO will charge the user
and return delivery report to Centili about result of payment. At the end we will send
payment notification to our Partner. Steps required for implementation: 1, 2 and 5.
Figure above represents the actuall steps with premium flow.
3.3 Pin Flow
When user initiates payment Centili will generate PIN and send it via SMS to the user. This
PIN will not be sent to our Partner. When the user receives PIN he will have to enter it if
he wants to finish the payment. This PIN will be sent to the Partner and he will redirect it
to Centili for validation. If the PIN is valid Centili will invoke payment process and user will
be charged using Operator's Billing system. In case of wrong PIN we will notify and enable
PIN re-entering process. As a final step, Centili notifies Partner about payment result, so
he can take appropriate actions related to his own business.
Steps required for implementation:1, 2, 3, 4 and 5.
Figure above represents the actuall steps with pin flow.
3.4 Redirect Flow
In some cases Mobile Network Operator insists on redirecting the user to his own payment
page. The reason for this approach is increased level of security. Centili will provide
the payment process is over, the Operator will inform Centili and we will forward payment
confirmation to the Partner.
Steps required for implementation: 1, 2 and 5.
Figure above represents the actuall steps with redirect flow.
3.5 SMS Handshake Flow
SMS Handshake represents MT-MO SMS exchange flow. When user initiates payment he
will receive MT message which will ask him to reply on that message in order to confirm
the payment. After the user replies with MO SMS, he will be charged using Operator's
Billing system. As a final step, Centili notifies Partner about payment result, and Partner
can take appropriate actions related to his own business.
Steps required for implementation:1, 2 and 5.
Figure above represents the actuall steps with SMS handshake flow.
4. One-time payment API
Centili exposes Payment API web service on following URI:
https://api.centili.com/api/payment/1_3/transaction
4.1 Step 1: Payment Initialization
In order to initiate payment request must be sent as HTTPS POST request. As Content-Type you ca
use application/json or application/xml.
POST https://api.centili.com/ api/payment/1_3/transaction HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json
{
"apikey": "918no8a7sdrh50o05ah43ej000",
"msisdn":"9991234567",
"price":"10"
}
Parameters
Required
apikey Application key Centili issued String
priceid Payment price identificator
(If you choose to put this parametar then the price parametar
will be unnecessary)
Numeric
price Payment price
(If you choose to put this parametar then the only needed
parameter besides this one will be msisdn/mccmnc)
Numeric (19.3)
wallet Wallet identificator
String
msisdn Message sender s MSISDN. Conforms to the following format:
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
mccmnc Mobile country and mobile network code
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String, more than 5
digits
mno which end
user belongs to (ex. FR_ORANGE)
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String
NOTE: If the flow is DMB or HANDSHAKE then msisdn is mandatory! Otherwise, transaction will be
rejected.
Optional
username Account username String
password Account password String
paymenttype
that user accessed channel is WAP you should set this parameter to
country
paramethers
String
clientid Custom ID assigned by Merchant to payment transaction. It will be
returned in payment notification and can be used as reference.
String
wapid For wap payment type this is wapid reference retireved from wap
idetification service (only if
String
language String
country Country ISO- String(2)
returnurl URL to final page on which end user will be redirected after end of
payment
coutries in which mobile operators require this)
String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionid":88739,
"clientid":null,
"redirecturl":null,
"params":null
}
JSON Success response parameters
errorMessage message with status description String
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
INVALID_PRICE price is invalid
INACTIVE service is inactive
SERVER_ERROR all other server errors
String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
clientid Custom ID assigned by Merchant to payment transaction String
redirecturl URL on which end user is redarected after successful payment String
params - String
4.2 Exception / Mid step for Singapore
In some countries after initiating a payment process you must confirm that process by asking user
for confirmation. When payment process is started for country Singapore user must be asked to
confirm started payment process. Merchant will be informed about this midstep by notifcation
which is subbmited to merchant payment notification URI .
Payment proces will look like this:
Merchant starts payment process
If payment proces is started in Singapore, user must confirm payment proces
Merchant is notified on notification URL with parameter flow=CUSTOM_PAGE
After receiving notification Merchant needs to ask customer for confirmation about
payment proces
After user confirms payment proces Merchant submits confirmation with HTTPS POST
request payment data update with parameter confirmed=yes
After this steps everything contiues like described in point 4.3.
Example of notification when user confirmation is needed
Payment notification for confirmation is submitted as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values.
POST http://<MERCHANT URI> HTTP/1.1
Accept: application/json
Host: <MERCHANT HOST>:80
Content-Type: application/x-www-form-urlencoded
xxxxxx
Parameters
Required
msisdn Phone number of the subscriber in international format without
the plus sign. For Example 4366124567
Number
clientid Unique ID of the client that you have supplied to us. This
parameter is sent back to you so that you can connect the
payment with the exact unique user or resource in your system
String
transactionid Unique payment id generated by our system. You should keep this
id in your database
Number
apikey Service identifier. It uniquely identifies the service which has been
defined with the service creation wizard
String
flow CUSTOM_PAGE String
Example of payment data update with confirmation parameter
Payment confirmation notification is submitted as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values.
POST https://api.centili.com/api/payment/1_3/transaction/<TRANSACTION-ID> HTTP/1.1
Host: api.centili.com:443
Content-Type: application/x-www-form-urlencoded
apikey=xxxxx&username=xxxxx&password=xxxxxx&confirmed=yes&paymenttype=mobile
Parameters
Required
apikey Application key Centili issued String
username Account username String
password Account password String
confirmed Yes or No depending on user decision String
paymenttype mobile wap . In case that Identification service has
confirmed that user accessed channel is WAP you should set
this parameter to wap
String
The response content type is application/JSON.
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"message" : "Request accepted",
"status" : "ACCEPTED",
"transactionid" : "xxxxx",
}
JSON Success response parameters
message message with status description String
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
INVALID_PRICE price is invalid
INACTIVE service is inactive
SERVER_ERROR all other server errors
String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
4.3 Step 2: Payment Flow notification
Payment flow notification is submitted as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values. Notifcation is subbmited to Merchant
payment notification URI.
POST http://<MERCHANT URI> HTTP/1.1
Accept: application/json
Host: <MERCHANT HOST>:80
msisdn=491626839553&transactionid=505478&flow=premium&apikey=<apikey>&clientid=AB123D
NB
Parameters
Required
msisdn Phone number of the subscriber in international format without
the plus sign. For Example 4366124567
Number
clientid Unique ID of the client that you have supplied to us. This
parameter is sent back to you so that you can connect the
payment with the exact unique user or resource in your system
String
transactionid Unique payment id generated by our system. You should keep this
id in your database
Number
apikey Service identifier. It uniquely identifies the service which has been
defined with the service creation wizard
String
flow premium, pin, url_redirect, handshake, error String
Optional
service_number Short code number on which user must send MO message in
order to confirm payment for premium flow
String
message_text Exact sms message text that user has to send to shortcode for
premium flow
String
redirect_url Url on which uers must be redirected in order to perform
payment for url redirect flow
String
message_info Information text that can be presented to user payment
instruction message in local language (valid for premium, pin,
sms handshake flow)
String
4.4 Payment flow and status information
In case that service does not have notification URL set we provide a method which can be called for
obtaining the information about the flow and transaction status in the same time.
GET https://api.centili.com/ api/payment/1_3/transaction/<TRANSACTION-ID> HTTP/1.1
Host: api.centili.com:443
Parameters
Required
transactionid Unique payment id generated by our system. You should keep this
id in your database
Number
Optional
username Account username String
password Account password String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionId":12830,
"sessionId":12387,
"apiKey":"1cdf6af85d9fa192051b9d012da34d9f",
"chargeURL":"http://inspectb.in/cbde43d3",
"wap":false,
"price":104.0,
"clientId":null,
"countryCode":"rs",
"msisdn":"38160xxxxxxx",
"mnoCode":"RS_VIP",
"mcc":"220",
"mnc":"05",
"walletCode":null,
"action":"PIN",
"sessionStatus":"PENDING",
"urlRedirect":null,
"pin_pattern":null,
"premiumInstructions":null,
"handshakeInstructions":null,
"shortCode":null,
"mtShortCode":null,
"smsBody":null,
"message":null,
"popUp":false,
"urlSufix":null,
"width":0,
"height":0,
"scrollX":0,
"scrollY":0,
"paymentApiCustomPageRuleDTO":null
}
4.5 Step 3: Payment data update
Optional Step needed only for Pin flow
In order to update payment data request must be sent as HTTPS POST. URI for sending payment
update https://api.centili.com/api/payment/1_3/transaction/<transaction-id> where <transaction-
id> is id of payment transaction for which updated data are submitted.
This method is used both for One Time service transactions and Subscription service transactions
(OPT-IN, OPT-OUT).
POST https://api.centili.com/ api/payment/1_3/transaction/<TRANSACTION-ID> HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json, application/xml
{
"pin": "98739"
}
Parameters
Required
apikey Application key Centili issued String
pin User obtained pin value (only in case of PIN flow)
String
confirmed Yes or No depending on user decision (alternative to pin)
String
The response content type can be JSON or XML.
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionid":12832,
"clientid":xxxxxxxxxxxxxx,
"redirecturl":null,
"params":null
}
JSON Success response parameters
message message with status description String
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
INVALID_PRICE price is invalid
INACTIVE service is inactive
SERVER_ERROR all other server errors
String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
clientid Custom ID assigned by Merchant to payment transaction
redirecturl URL on which end user is redarected after successful payment
params -
4.6 Step 4: Payment update status
Optional Step executed only for Pin flow if user has entered invalid Pin.
Payment flow notification is submitted as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values. Notifcation is subbmited to Merchant
payment notification URI.
POST http://<MERCHANT URI> HTTP/1.1
Accept: application/json
Host: <MERCHANT HOST>:80
Content-Type: application/x-www-form-urlencoded
msisdn=491626839553&transactionid=505478&flow=PIN&apikey=<apikey>&clientid=AB123DNB&s
tatus=DATA_INVALID
Parameters
Required
msisdn Phone number of the subscriber in international format without
the plus sign. For Example 4366124567
Number
transactionid Unique transaction identifier assigned to this particular
transaction,
String
apikey Service identifier. It uniquely identifies the service which has
been defined with the service creation wizard
String
clientid Unique ID of the client that you have supplied to us. This
parameter is sent back to you so that you can connect the
payment with the exact unique user or resource in your system
String
status DATA_INVALID (wrong pin is submitted, you should try again)
or FATAL_ERROR (transaction failed due to too many failed pin
submit attempts, you should not try again)
String
4.7 Step 5: Final Payment result notification
Payment notification web service receives call when payment is finished. Notification is submitted
to Merchant payment notification URI as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values.
POST http://<MERCHANT URI> HTTP/1.1
Accept: application/json
Host: <MERCHANT HOST>:80
Content-Type: application/x-www-form-urlencoded
msisdn=491626839553&transactionid=505478&service=<apikey>&clientid=AB123DNB&country=de
&status=success&event_type=one_off&enduserprice=10.00
Parameters
Required
msisdn Phone number of the subscriber in international format without the
plus sign. For Example 4366124567
Number
country The country code of the subscriber's mobile operator. We are using
ISO 3166-1standard for the code. For example FR for France, ES for
Spain etc.
String
mno Mobile Network Operator which end user belongs to. Mobile country
code and mobile network code (mcc + mnc concatenated), e.g. 50219. In some cases (WAP,..) this parameter will not be sent through
payment result notification
String
mnocode
belongs to, e.g. FR_ORANGE
amount Amount of credits purchased (for subscriptions it will always be 1) Number
status Status of the payment. This parameter will be either success or
failed as it defines the outcome of the transaction. You should
always check this parameter
String
clientid Unique ID of the client that you have supplied to us. This parameter is
sent back to you so that you can connect the payment with the exact
unique user or resource in your system
String
enduserprice End user price that the user has paid in local currency with VAT
included, decimal number. (example: 8.000)
Number
transactionid Unique payment id generated by our system. You should keep this id
in your database
Number
service Service identifier. It uniquely identifies the service which has been
defined with the service creation wizard
String
event_type This parameter actually identifies the event type during the
subscription process.Possible values: one_off (default), opt_in,
opt_out, recurring_billing.
String
We are expecting that payment confirmation page returns HTTP status 200. In that case
we are treating the transaction as completed. However if your server goes offline or any
other error occurs we will keep retrying to notify you during the next 24 hours.
Undelivered transactions will be marked in the partner panel transaction log and you will
also be able to resend them to your server manually.
5. Mobile subscriptions API
Mobile subscriptions use the same mechanism as one-time payments, except payment
initiation (Step 1). Instead of Step 1, subscriptions have two operations subscribe and
unsubscribe exposed at following URIs:
https://api.centili.com/ api/payment/1_3/subscribe
https://api.centili.com/ api/payment/1_3/unsubscribe
Both operations share the same process as one-time payments.
5.1 Subscription initiation example
In order to initiate subscription, request must be sent as HTTPS.
POST https://api.centili.com/ api/payment/1_3/subscribe HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json, application/xml
{
"apikey": " de7c30e0f89cdaab62ee4af6bb498358",
"msisdn":"999xxxxxxx",
"priceid":"25"
}
Parameters
Required
apikey Application key Centili issued String
priceid Subscription price/interval identificator Numeric
price String
msisdn Message
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
mccmnc Mobile country and mobile network code
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String, more than 5
digits
mno
user belongs to (ex. FR_ORANGE)
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String
Optional
paymenttype
mobile wap . In case that Identification service has
confirmed that user accessed channel is WAP you should set
this parameter to wap
String
clientid Custom ID assigned by Merchant to payment transaction. It will
be returned in payment notification and can be used as
reference.
String, max 30
characters
wapid For wap payment type this is wapid reference retireved from
wap idetification service
String
The response content type can be JSON or XML.
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionid":88744,
"redirecturl":null,
"params":null
}
JSON Success response parameters
message message with status description String
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
INVALID_PRICE price is invalid
INACTIVE service is inactive
SERVER_ERROR all other server errors
String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
clientid Custom ID assigned by Merchant to payment transaction String
redirecturl URL on which end user is redarected after successful payment String
params - String
In case that the subscription is valid and response to subscribe is HTTP 200 OK next steps will be:
1. Flow notification
2. Final result notification
Parameters of these flows depend on payment flow type and will have different values because of
the subscription process.
5.2 Unsubscribe initiation example
In order to initiate unsubscribe operation, request must be sent as HTTPS POST with Content-
Type: application/xwww-form-urlencoded composed of parameters with associated values.
POST https://api.centili.com/ api/payment/1_3/unsubscribe HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json, application/xml
{
"apikey": " de7c30e0f89cdaab62ee4af6bb498358",
"msisdn":"999xxxxxxx",
}
Parameters
Required
apikey Application key Centili issued String
msisdn
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
mccmnc Mobile country and mobile network code
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String, more than 5
digits
mno
user belongs to (ex. FR_ORANGE)
(If you choose to put this parametar than the msisdn parametar
will be unnecessary)
String
The response content type can be JSON or XML
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionid":88745,
"redirecturl":null,
"params":null
}
JSON Success response parameters
errorMessage message with status description String
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
INVALID_PRICE price is invalid
INACTIVE service is inactive
SERVER_ERROR all other server errors
String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
clientid Custom ID assigned by Merchant to payment transaction String
redirecturl URL on which end user is redarected after successful payment String
params - String
In case that the subscription is valid and response to unsubscribe is HTTP 200 OK next steps will
be:
1. Flow notification
2. Final result notification
Parameters of these flows depend on payment flow type and will have different values because of
subscription process.
5.3 Administration unsubscribe example
In order to initiate unsubscribe operation, request must be sent as HTTPS POST .
POST https:// api.centili.com/ api/payment/1_3/unsubscribeadmin HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json, application/xml
{
"apikey": " de7c30e0f89cdaab62ee4af6bb498358",
"msisdn":"999xxxxxxx",
}
Parameters
Required
apikey Application key Centili issued String
msisdn
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
The response content type can be JSOn or XML
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"transactionid": "24121"
}
JSON Success response parameters
status ACCEPTED Payment request is accepted!
INVALID_REQUEST Invalid request parameters
INVALID_SERVICE Invalid service (apikey is invalid)
UNAUTHORIZED Invalid auth.: username,password,IP
BANNED IP address is banned
INVALID_MSISDN msisdn is invalid
status
INVALID_PRICE price is invalid
INVALID_PIN the PIN is not valid on update transaction if required.
EXISTING_SUBSCRIPTION trying to create new subscription for
already subscribed msisdn on same service.
NONEXISTING_SUBSCRIPTION trying to unsubscribe already
unsubscribed number or never subscribed number on selected
service.
INACTIVE service is inactive
SERVER_ERROR all other server errors
errorMessage Message with status description String
transactionid Unique transaction identifier assigned to this particular transaction, it
will be returned every time in payment transaction notification
Numeric
In case that the subscription is valid and response to unsubscribe is HTTP 200 OK next steps will
be:
Final result notification
Parameters of these flows depend on payment flow type and will have different values because of
subscription process.
5.4 Subscription status
In order to initiate subscription status check, request must be sent as HTTPS GET
GET https://api.centili.com/api/payment/1_3/subscription?apikey=[apikey]&msisdn=xxxxxx
Parameters
Required
apikey Application key Centili issued String
msisdn
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
Optional
username Account username String
password Account password String
paymenttype
mobile , wap . In case that Identification service has
confirmed that user accessed channel is WAP you should set
this parameter to wap
String
expires Date and time in UTC when subscription will expire if value is
SUBSCRIBED, for any other value is NULL (??)
String
Subscription status can be one of the following:
Subscription for service and MSISDN never arrived - NOTSUBSCRIBED,
Subscription created and active SUBSCRIBED,
User unsubsrcribed-UNSUBSCRIBED
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"subscriptionStatus":"UNSUBSCRIBED",
"expires":""
}
6. Obtaining price identificators
Price identificators can be obtained through following URIs:
https://api.centili.com/ api/payment/1_3/packages, for one-time payment services
https://api.centili.com/ api/payment/1_3/intervals, for subscription services
6.1 Obtaining packages example
This is request in order to fetch price identificators for one-time payment service.
The response will contain all available packages for country, if country parameter is sent, and
packages for resolved operator if any of other 3 paramethers is sent.
GET https://api.centili.com/api/payment/1_3/packages?apikey=[apikey]&country=rs HTTP/1.1
Host: api.centili.com:443
Parameters
Required
apikey Application key Centili issued String
Required, only one of following (used to determine which payment packages are available and to return appropriate revenue)
mccmnc Mobile country and mobile network code
(example: 22005)
String, more than 5
digits
mno Mobile network operator code String
country ISO 3166 country code (if this parameter is passed, along with
username and password, revenue will be approximated using
revenues for MNOs in that country)
String, exactly 2
characters
msisdn s MSISDN. Conforms to the following format:
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
Optional
username Account username String
password Account password String
paymenttype
confirmed that user accessed channel is WAP you should set
String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"name":"Demo",
"merchantName":"Demo",
"packages":[
{
"id":9016,
"amount":1,
"unit":"item",
"price":104.0,
"revenue":null,
"currency":"RSD",
"currencySign":null,
"revenuePreferred":null,
"currencyPreferred":null,
"type":"mobile",
"operatorCode":null,
"operatorName":null,
"country":"rs"
},
{
"id":9018,
"amount":2,
"unit":"item",
"price":207.0,
"revenue":null,
"currency":"RSD",
"currencySign":null,
"revenuePreferred":null,
"currencyPreferred":null,
"type":"mobile",
"operatorCode":null,
"operatorName":null,
"country":"rs"
}
] }
JSON Success response parameters
id Price identificator Numeric
currency Currency price is displayed in String
unit Unit name of goods being sold using that service String
amount Amount of units in that particular package Numeric
price Package price Numeric
revenue Revenue in returned currency (optional) Numeric
revenuePreferred Revenue in merchant's payout currency (optional) String
currencyPreferred Payout currency (optional) String
type Type of package: mobile, wallet or wap String
operatorCode mnoCode if type is mobile and wallet value during initialization of
transaction if type is wallet
String
operatorName Name of mno or wallet via package can be charged String
country Selected country in which service is active String
Note: Now you can get both wallet and mobile packages in the following way:
1. If you put only mccmnc, you will get all wallet packages from that country (based on
mcc) and mobile packages for that mccmnc.
2. If you put only msisdn the same effect as in 1.
3. If you put only country you will get all wallet and mobile packages but in that case you
will not get operatorCode nor operatorName for mobile packages (the value will be
value null).
4. If you put country &( msisdn OR mccmnc) it will act as only msisdn OR mccmnc are
entered.
6.2 Obtaining intervals example
This is request in order to fetch price identificators for subscription service.
GET https://api.centili.com/api/payment/1_3/intervals?apikey=[apikey]&country=rs HTTP/1.1
Host: api.centili.com:443
Parameters
Required
apikey Application key Centili issued String
Required, only one of following (used to determine which payment packages are available and to return appropriate revenue)
mccmnc Mobile country and mobile network code
(example: 22005)
String, more than 5
digits
mno Code of Mobile
user belongs to (ex. FR_ORANGE)
String
country ISO 3166 country code (if this parameter is passed, along with
username and password, revenue will be approximated using
revenues for MNOs in that country)
String, exactly 2
characters
msisdn s MSISDN. Conforms to the following format:
(example: Vodafone DE MSISDN 491626839553)
Country code (49)
National Destination Code (162)
Subscriber Number (6839553)
Numeric, max. 17
digits
Optional
username Account username String
password Account password String
paymenttype
. In case that Identification service has
confirmed that user accessed channel is WAP you should set
String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"name":"Subscription Service 1",
"merchantName":"Demo",
"intervals":[
{
"id":210,
"interval":"month",
"price":568.0,
"revenue":null,
"currency":"RSD",
"currencySign":null,
"active":true
},
{
"id":211,
"interval":"day",
"price":114.0,
"revenue":null,
"currency":"RSD",
"currencySign":null,
"active":true
},
]
}
JSON Success response parameters
id Price identificator Numeric
currency Currency price is displayed in String
active True if interval can be used Boolean
price Package price Numeric
revenue Revenue in returned currency Numeric
interval Period on which basis customer will be charged Numeric
6.3 Obtaining MNO codes
MNO codes can be obtained through following URI:
https://api.centili.com/ api/payment/1_3/mnos
GET https://api.centili.com/api/payment/1_3/mnos?apikey=[apikey]& country=rs HTTP/1.1
Host: api.centili.com:443
Parameters
Required
apikey Application key Centili issued String
country
ISO 3166 country code String, exactly 2
characters
Optional
username Account username String
password Account password String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"mnos":[
{
"code":"RS_MTS",
"name":"m:ts Serbia",
"mccmncs":[
"22003"
]
},
{
"code":"RS_TELENOR",
"name":"Telenor Serbia",
"mccmncs":[
"22001"
]
},
{
"code":"RS_VIP",
"name":"VIP Mobile Serbia",
"mccmncs":[
"22005"
]
}
],
"wallets":[
{
"code":"paypal",
"name":"PayPal"
},
{
"code":"QIWI_RS",
"name":"Qiwi Serbia"
}
]
}
JSON Success response parameters
name MNO name Numeric
code MNO code String
mccmncs List of mccmncs that MNO is using String,
more than
5 digits
6.4 Obtaining service info
Information about service can be obtained through following URI:
https://api.centili.com/ api/payment/1_3/service/<APIKEY>
GET https://api.centili.com/api/payment/1_3/service/apikey=[apikey] HTTP/1.1
Host: api.centili.com:443
Parameters
Required
apikey Application key Centili issued String
The response content type can be JSON or XML:
200 Success response body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status":"ACCEPTED",
"errorMessage":null,
"countries":[
{
"code":"rs",
"name":"Serbia",
"prefix":"381",
"msisdnPreferred":true,
"mnoPreferred":false,
"mnos":[
{
"code":"RS_MTS",
"name":"m:ts Serbia",
"mccmncs":[
"22003"
]
},
{
"code":"RS_TELENOR",
"name":"Telenor Serbia",
"mccmncs":[
"22001"
]
},
{
"code":"RS_VIP",
"name":"VIP Mobile Serbia",
"mccmncs":[
"22005"
]
}
],
"wallets":[
{
"code":"paypal",
"name":"PayPal"
},
{
"code":"QIWI_RS",
"name":"Qiwi Serbia"
}
]
}
}