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:

ParameterDescriptionExampleRequired as
serviceKeyCentili 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
priceEnd user price for an ongoing
transaction.
1.45 mandatory both for 3G and WiFi flow
userIdentifierEnd 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
clientDataClient 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

ParameterDescriptionExampleRequired as
country2 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
msisdnCustomer mobile phone number.
NOTE: The number must be in E.164 format, excluding the plus ("+") character.
381644150105optional
( mandatory for WiFi flow)
Look for "Keep in mind" callout box underneath this table.
operatorCode 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.
imsiInternational mobile subscriber identity (MCC + MNC + MSIN)313460000000001optional
identIdID of the identification transaction that preceded the payment request.eyJyaSI6IjAxYjUzZjkwLWMzMDAtNoptional
( mandatory for 3G flow)

Client Data

ParameterDescriptionExampleRequired as
clientUserIdIdentification of the customer.usrId1983optional
clientReferenceUnique identification parameter under your system (pass-through variable).appID1optional
returnURLURL to which user is redirected after payment.http://www.example.comoptional
pageCustomizationPage customization parameters. See (https://dev.centili.com/docs/initiate-subscription-1#page-customization){
"itemName": null,
"designId": null,
"language": null
}
optional

Page customization

ParameterDescriptionExampleRequired as
itemNameName of the item the client is sellingitem1optional
designIdAllows adding design_id parameter in request if merchant want customized payment page. Any page customization must be allowed by MNO.design10optional
language2 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.enoptional

🚧

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:

ParameterDescriptionExample
transactionIdUnique identifier of transaction in Centili system.17000002453
clientDataClient related parameters. See (https://dev.centili.com/docs/initiate-payment-2#client-data){
"clientUserId": null,
"clientReference": null
}
countryTwo-letter ISO 31661 international standard code.rs
(for Serbia)
operatorCode of Mobile Network Operator in Centili’s system which end user belongs to.RS_MTS
(for Telekom Serbia)
msisdnCustomer mobile phone number.
NOTE: The number must be in E.164 format, excluding the plus ("+") character.
381644150105
operationSignifies 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"
}
transactionTypeAction that is performed by this transaction. Possible values: CHARGE, SUB_START, SUB_CANCEL, SUB_RENEW, REFUNDSUB_START
requestIdUnique request IDbe987aa6-d6a7-4176-969b-5bc185cf746a

Operation

ParameterDescriptionExample
userInstructionInstruction 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.
urlRedirectEnd user should be redirected to this URL.

If operation code is URL_REDIRECT this will not be NULL.
http://www.google.com
typeFlow 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
shortcodeEnd 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
keywordEnd 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
urlReturnURL 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"
}
ParameterDescriptionExample
codeError response codeCHARGING_FAILED
messagError response messageCharging 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 valueCentili instruction
URL_REDIRECTRedirect 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.
MOYou 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.
PINPlease refer to PIN Payment Flow Update guide for complete reference how to forward PIN after user enters it and track its status.
HANDSHAKEDisplay 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: