Identify Subscription

The Centili subscription payments option allows you to automatically charge your users over mobile phone bill, on a daily, weekly or monthly basis.

There are 2 basic ways to identify if user is already subscribed and using your service:

Subscription identification using Unique User Identifier (server-to-server)

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 to be sent using POST method

Parameter
Description
Example
Required

apikey

Centili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters.

f31a355df6dad07e49ba474db7ff9b07

mandatory

userid

unique user identifier - used when user initiated his subscription process

userid=3466603421 or userid= =1-A-3214ASD

mandatory

timestamp

Unix timestamp used to differentiate every request as a unique one. The number string represents seconds.

1462888063

mandatory

sign

Signature parameter created using key issued for signing request.

NOTE: Please refer to the signature key generation guide.

def0a0ba4f188cf174d383dc4d7f7041e358ba92

optional

If subscription identification process has been executed successfully you will get appropriate HTTP response – STATUS 200 OK.

JSON formatted response will contain following parameters:

Parameter
Description
Example

activesub

Checking if subscription is active or not.

  • true - user is subscribed
  • false - user is not subscribed

validsub

Checking if an end user was charged during last renewal attempt for subscription period.

  • true - user was charged
  • false - user wasn't charged

msisdn

Original end user msisdn number.

4477781234567

operator

Mobile Network Operator code.

ES_VODAFONE

expirationdate

Unix timestamp, moment in the future until end user subscription is valid. The number string represents seconds.

1462888063

userid

“userid” used during subscribe step and checked during this process.

usrId1983

NOTE: If the value is not set within payment request, this field will contain MSISDN of the particular customer.

Example using Unique User Identifier

  • POST request you need to send:
POST https://api.centili.com/payment/rest/subidentify?

{
"apikey":"278e9ea30d473dbfb5609b90de4572b9",
"userid":"60165175712",
"timestamp":"1449063016",
"sign":"1a72cf7dc8032e1c1d4ce457ef68e1988ea25893"
}
  • The response you will receive:
HTTP Status 200 OK

{
  "activesub": "true",
  "validsub": "true",
  "msisdn": "60165175712",
  "operator": "MY_DIGI",
  "userid": "60165175712",
	"expirationdate": "1462888063"
}

where:

Parameter
Description

"activesub=true"

Subscription is active under Centili system and you should not try to subscribe user once again.

"validsub=true"

Subscription is valid under Centili system and you should grant access to content for this user.

msisdn

Original end user msisdn number.

operator

Mobile Network Operator code.

expirationdate

Unix timestamp, moment in the future until end user subscription is valid. The number string represents seconds.

sign

1a72cf7dc8032e1c1d4ce457ef68e1988ea25893

Possible outcomes

Depending on the value of parameters activesub and validsub, these are the possible outcomes:

Parameter "ACTIVESUB"
Parameter "VALIDSUB"
Outcome

false

false

Try to perform the payment process.

true

false

User renewal charge process is pending and you should wait for payment to occur.

false

true

Send user directly to his content, because he already paid for it and he is not able to pay once again.

Subscription identification using User Redirection

warning

Please refrain from using this method without consulting Centili tech team first !

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

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

Parameters to be sent using GET method

Parameter
Description
Example
Required

apikey

Centili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters.

f31a355df6dad07e49ba474db7ff9b07

mandatory

returnurl

URL to which user is redirected after subscription identification process. In case of GET requests, URL must be URLencoded.
Additional query parameters defined by the client and forwarded through returnurl parameter will be passed back when user is returned, with Centili parameters attached.

mandatory

timestamp

Unix timestamp used to differentiate every request as a unique one. The number string represents seconds.

1462888063

mandatory

sign

Signature parameter created using key issued for signing request.

NOTE: Please refer to the signature key generation guide.

def0a0ba4f188cf174d383dc4d7f7041e358ba92

optional

After this, 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.

Example of Sub Identify Request

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

Note:

Timestamp is additional parameter which is mandatory for each request. Timestamp parameter allows Centili platform to differentiate every request as unique one, so fraudulent activities can be eliminated together with signature through sign parameter.

Once successful identification occurs we will trigger your return URL and send following data using regular HTTP GET method:

Parameter
Description
Example

userid

Identification of the end user performing payment.

usrId1983

NOTE: If the value is not set within payment request, this field will contain MSISDN of the particular customer.

timestamp

Unix timestamp used to differentiate every request as a unique one. The number string represents seconds.

1462888063

sign

Signature parameter created using key issued for signing request.

NOTE: Please refer to the signature key generation guide.

f71bfbf1c75bab0da59f4bb6cdab4b7450988f06

Note:

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.

In example mentioned above, after initial subscription identification request is sent, following URL will be triggered based on return URL parameter that was sent in that initial request:

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

Next step...

Identify Subscription