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
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 |
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 |
---|---|---|
active | Checking if subscription is active or not. | true - user is subscribed false - user is not subscribed |
valid | 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. |
status | Indicates status of the current request. | ACCEPTED INVALID_REQUEST *SERVER_ERROR |
errorMessage | Error 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:
Parameter | Description |
---|---|
"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. |
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 |
status | Indicates status of the current request. |
*errorMessage | Error 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 |
---|---|---|
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. | http://www.example.com | 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×tamp=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×tamp=1409755651301&sign=def0a0ba4f188cf174d383dc4d7f7041e358ba92
Next step...
Updated over 4 years ago