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/api/payment/1_4/subscription

Parameters to be sent using POST method

ParameterDescriptionExampleRequired
apikeyCentili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters.f31a355df6dad07e49ba474db7ff9b07 mandatory
useridunique user identifier - used when user initiated his subscription processuserid=3466603421 or userid= =1-A-3214ASD mandatory
signSignature parameter created using key issued for signing request.

NOTE: Please refer to the signature key generation guide.
def0a0ba4f188cf174d383dc4d7f7041e358ba92optional

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


JSON formatted response will contain following parameters:

ParameterDescriptionExample
activeChecking if subscription is active or not. true - user is subscribed
false - user is not subscribed
validChecking if an end user was charged during last renewal attempt for subscription period. true - user was charged
false - user wasn't charged
msisdnOriginal end user msisdn number.4477781234567
operatorMobile Network Operator code.ES_VODAFONE
expirationdateUnix 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.
statusIndicates status of the current request.ACCEPTED
INVALID_REQUEST
*SERVER_ERROR
errorMessageError description in case of failed transaction request.Bad request, otherwise the value is null

Example using Unique User Identifier

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

{
"apikey":"278e9ea30xxxxxxx",
"userid":"60165xxxx",
"sign" : "488d3b60e3c8bf879148d1aa0c48cb31xxxxxx"
}
  • The response you will receive:
HTTP Status 200 OK

{
    "status": "ACCEPTED",        
    "errorMessage": null,
    "active": "false",
    "valid": "false",
    "msisdn": "60165xxxx",
    "userId": "60165xxxx",
    "operator": "MY_DIGI",
    "expirationDate": "1452692098817",
    "subscriptionId": "3685958"
}

where:

ParameterDescription
"active=true"Subscription is active under Centili system and you should not try to subscribe user once again.
"valid=true"Subscription is valid under Centili system and you should grant access to content for this user.
msisdnOriginal end user msisdn number.
operatorMobile Network Operator code.
expirationdateUnix timestamp, moment in the future until end user subscription is valid. The number string represents seconds.
sign1a72cf7dc8032e1c1d4ce457ef68e1988ea25893
statusIndicates status of the current request.
*errorMessageError description in case of failed request.

Possible outcomes

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

Parameter "ACTIVESUB"Parameter "VALIDSUB"Outcome
falsefalseTry to perform the payment process.
truefalseUser renewal charge process is pending and you should wait for payment to occur.
falsetrueSend 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

ParameterDescriptionExampleRequired
apikeyCentili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters.f31a355df6dad07e49ba474db7ff9b07mandatory
returnurlURL 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.
http://www.example.commandatory
timestampUnix timestamp used to differentiate every request as a unique one. The number string represents seconds.1462888063mandatory
signSignature parameter created using key issued for signing request.

NOTE: Please refer to the signature key generation guide.
def0a0ba4f188cf174d383dc4d7f7041e358ba92optional

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:

ParameterDescriptionExample
useridIdentification 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.
timestampUnix timestamp used to differentiate every request as a unique one. The number string represents seconds.1462888063
signSignature 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...