Initiate Subscription
Initiate a subscription transaction
In order to initiate a subscription with Centili Payment API, you need to send an HTTP POST request with Content-Type: application/json composed of parameters with associated values.
Before initiating a subscription request you will need to obtain an access token
URL to which a request should be sent
https://capi.centili.com/payments/v3/subscriptions/init
POST subscription request
https://capi.centili.com/payments/v3/subscriptions/init HTTP/1.1
Host: capi.centili.com:443
Content-Type: application/json
Authorization:bearer token
{
"userIdentifier": {
"country": "rs",
"imsi": null,
"msisdn": "381644150105",
"operator": "RS_MTS",
"identId": null
},
"price": "30.00",
"serviceKey": "2ea0e6c989b433d6c591633f91c67e07",
"clientData": {
"clientUserId": null,
"pageCustomization": {
"itemName": null,
"designId": null,
"language": null
},
"clientReference": null,
"returnURL": "http://www.google.com"
}
}
All possible initiation parameters:
| Parameter | Description | Example | Required as |
|---|---|---|---|
| serviceKey | Centili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters. | f31a355df6dad07e49ba474db7ff9b07 | mandatory both for 3G and WiFi flow |
| price | End user price for an ongoing transaction. | 1.45 | mandatory both for 3G and WiFi flow |
| userIdentifier | End user related identifier parameters. See (https://dev.centili.com/docs/initiate-subscription-1#user-identifier) | { "country": "rs", "imsi": null, "msisdn": "381644150105", "operator": "RS_MTS", "identId": null } | mandatory /optional |
| clientData | Client related parameters. See (https://dev.centili.com/docs/initiate-subscription-1#client-data) | { "clientUserId": null, "pageCustomization": { }, "clientReference": null, "returnURL": "http://www.google.com" } | optional |
User identifier
| Parameter | Description | Example | Required as |
|---|---|---|---|
| country | 2 letter country parameter. We are using "ISO 3166-1 alpha-2" standard. Here is full list of 2 letter country codes. | rs (for Serbia) | optional |
| msisdn | Customer mobile phone number. NOTE: The number must be in E.164 format, excluding the plus ("+") character. | 381644150105 | optional ( mandatory for WiFi flow) Look for "Keep in mind" callout box underneath this table. |
| operator | Code of Mobile Network Operator in Centili’s system which end user belongs to. | RS_MTS (for Telekom Serbia) | mandatory / optional Look for "Keep in mind" callout box underneath this table. |
| imsi | International mobile subscriber identity (MCC + MNC + MSIN) | 313460000000001 | optional |
| identId | ID of the identification transaction that preceded the payment request. | eyJyaSI6IjAxYjUzZjkwLWMzMDAtN | optional ( mandatory for 3G flow) |
Client Data
| Parameter | Description | Example | Required as |
|---|---|---|---|
| clientUserId | Identification of the customer. | usrId1983 | optional |
| clientReference | Unique identification parameter under your system (pass-through variable). | appID1 | optional |
| returnURL | URL to which user is redirected after payment. | http://www.example.com | optional |
| pageCustomization | Page customization parameters. See (https://dev.centili.com/docs/initiate-subscription-1#page-customization) | { "itemName": null, "designId": null, "language": null } | optional |
Page customization
| Parameter | Description | Example | Required as |
|---|---|---|---|
| itemName | Name of the item the client is selling | item1 | optional |
| designId | Allows adding design_id parameter in request if merchant want customized payment page. Any page customization must be allowed by MNO. | design10 | optional |
| language | 2 letter language parameter. Language which will be used for all message localization. We are using "ISO 3166-1 alpha-2" standard. Here is full list of 2 letter country codes. | en | optional |
Keep in mind:
"operator" parameter is:
- mandatory for 3G flow, with value equal to value of "operator" parameter received in previous Identify User response
- mandatory for WiFi flow as well, but only if used instead of "msisdn" parameter (supported for certain Mobile Network Operators).
POST subscription response
Once a request has been received, Centili will synchronously respond an appropriate HTTP response containing a list of parameters and values in JSON format:
200
Subscription transaction initiated
HTTP/1.1 200 OK
Content-Type: application/json
{
"transactionType": "SUB_START",
"country": "rs",
"requestId": "be987aa6-d6a7-4176-969b-5bc185cf746a",
"clientData": {
"clientUserId": null,
"clientReference": null
},
"operation": {
"userInstruction": null,
"urlRedirect": null,
"type": "PIN",
"shortcode": null,
"keyword": null,
"urlReturn": "http://www.google.com"
},
"msisdn": "381644150105",
"transactionId": "17000002453",
"operator": "RS_TELEKOM"
}
Response parameters:
| Parameter | Description | Example |
|---|---|---|
| transactionId | Unique identifier of transaction in Centili system. | 17000002453 |
| clientData | Client related parameters. See (https://dev.centili.com/docs/initiate-payment-2#client-data) | { "clientUserId": null, "clientReference": null } |
| country | Two-letter ISO 31661 international standard code. | rs (for Serbia) |
| operator | Code of Mobile Network Operator in Centili’s system which end user belongs to. | RS_MTS (for Telekom Serbia) |
| msisdn | Customer mobile phone number. NOTE: The number must be in E.164 format, excluding the plus ("+") character. | 381644150105 |
| operation | Signifies type of flow for the initiated transaction. See (https://dev.centili.com/docs/initiate-subscription-1#operation) | { "userInstruction": null, "urlRedirect": null, "type": "PIN", "shortcode": null, "keyword": null, "urlReturn": "http://www.google.com" } |
| transactionType | Action that is performed by this transaction. Possible values: CHARGE, SUB_START, SUB_CANCEL, SUB_RENEW, REFUND | SUB_START |
| requestId | Unique request ID | be987aa6-d6a7-4176-969b-5bc185cf746a |
Operation
| Parameter | Description | Example |
|---|---|---|
| userInstruction | Instruction to be shown to end user explaining the operation need to continue the transaction If operation code is MO, HANDSHAKE or PIN this will not be NULL. | Please send CENT to 1234 in order to confirm purchase. NOTE: instruction is displayed in a local language. Check our country coverage. |
| urlRedirect | End user should be redirected to this URL. If operation code is URL_REDIRECT this will not be NULL. | http://www.google.com |
| type | Flow type. Possible values: MO, PIN, HANDSHAKE, URLREDIRECT _NOTE: look for these instructions how to regulate further flow according to data received in our response (underneath this table). | PIN |
| shortcode | End user has to send a SMS to this short code to continue the transaction. If operation code is MO or HANDSHAKE this will not be NULL. | 1234 |
| keyword | End user should put this keyword at a start of SMS message he sends to supplied short code. If operation code is MO or HANDSHAKE this will not be NULL. | CENT |
| urlReturn | URL to which user is redirected after payment. | http://www.google.com |
4xx client error / 5xx server error
400 - Subscription transaction can not be created - check message for details.
401 - Invalid credentials
500 - Request can not be processed at the current time
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"code": "CHARGING_FAILED",
"message": "Charging failed"
}
| Parameter | Description | Example |
|---|---|---|
| code | Error response code | CHARGING_FAILED |
| messag | Error response message | Charging failed |
Once transaction reaches a final state Payment Result Notification will be delivered to your system.
Instructions depending on the "Action type" parameter value
Regulate further flow according to data received in our response:
| "Action type" parameter value | Centili instruction |
|---|---|
| URL_REDIRECT | Redirect user to URL provided as a value of urlRedirect parameter mentioned in the table above. Once redirected, you should expect that user will be returned to URL provided in your initial request under returnurl parameter, according to the logic described in Redirect after Payment guide. |
| MO | You have two options: Display instruction message to user, using text you received in Centili response under **_premiumInstructions parameter, _ Use Short code and Keyword you received in response under shortCode and smsBody** parameters and create instruction message on your own. Once transaction reaches a final state, next step is Payment Result Notification which will be delivered to URL defined under your Partner Panel service. |
| PIN | Please refer to PIN Payment Flow Update guide for complete reference how to forward PIN after user enters it and track its status. |
| HANDSHAKE | Display instruction message to user containing text you received in Centili response under handshakeInstructions parameter. Once transaction reaches a final state, next step is Payment Result Notification which will be delivered to URL defined under your Partner Panel service. |
Payment flows
To help you understand these instructions, there are few types of payment flow, depending on the billing technology available in the country of your target:
Updated 11 months ago