Initiate Payment
In order to initiate payment with [CentiliPaymentAPI], you need to send request as HTTPS POST with Content-Type: application/json composed of parameters with associated values.
Before initiating payment you will need to obtain tokenURL
URL to which request should be posted:
https://api.centili.com/payments/v3/transactions/init
POST payment request
https://api.centili.com/payments/v3/transactions/init HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json
Authorization:bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHdl9MM0NFZDBMczZ5aGR1WGNnUmViWUlhek50VVJuaW9VZUxYYzRCczR3In0.eyJqdGkiOiJhNTcyNzk2YS0zYzNkLTQ4NjEtODY2NC1lZWQ1OWE3ODlhMWMiLCJleHAiOjE1OTc2OTc2OTYsIm5iZiI6MCwiaWF0IjoxNTk3Njk3Mzk2LCJpc3MiOiJodHRwczovL3N0YWdlLmNlbnRpbGkuY29tL2F1dGgvcmVhbG1zL2FwaSIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiIyNDhhMmU1Ny1hMTJhLTQ1YjUtODNkMS0zMGI4ZDJjYWY5NGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGktcGF5bWVudHMiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJjNDkyYTYwNS0yYjg0LTRjNzgtYWJkMy1jOWZmNjliMWEyMzEiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHBzOi8vc3RhZ2UuY2VudGlsaS5jb20iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImNlbnRpbGkuYXBpLmdhdGV3YXkuYWRtaW4iLCJjZW50aWxpLmFwaS5hZG1pbiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJjZW50aWxpLmFwaS51c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6ImthaW9zX3Rlc3QiLCJtZXJjaGFudF9pZCI6IjE1Nzc5In0.tS-Z83TaukcDnj0mMz27vCCOTMmM89UgpVUmRMAH5Oytp2AzI7kz30XQivnBPGH_vn9MpBDNR_U6uHyzhzE-p5PPYZzhB3AwfvzGkjBFsy4vTXix3sMm6wqruAjJ6Jht9K7Jn0rkNoNGLu79SmRrjWeaPImVosy7IANEX73SQMt3NL_96jjlXkZUhimEXifadoY9VEsEgE6t0DL8H_1U6VKlHbKCO87Ef_kW-F6MU7frV6VF3yRqdzz9wLnQpTz3voelJEB7mzfIRs-iFYSZLSKFsluTZfJtiIq0VWVwMaRLLRNNVdCe1dprmbJf2YKyvP-4ziGFEUhVmW8FmzAhQg
{
"userIdentifier": {
"country": "RS",
"imsi": "",
"msisdn": "38164xxxxxxx",
"operator": "RS_MTS",
"identId": ""
},
"price": "30.00",
"wap": false,
"serviceKey": "2ea0e6c989b433d6c591633f91c67e07",
"clientData": {
"clientUserId": "",
"pageCustomization": {
"itemName": "",
"designId": "",
"language": ""
},
"clientReference": "",
"returnURL": "http://www.google.com"
}
}
All possible initiation parameters:
Parameter | Description | Example | Required as |
---|---|---|---|
apikey | 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 | 1.45 | mandatory both for 3G and WiFi flow |
priceid | Identifier of a specific package under Centili platform. | 324 | optional |
User | Customer identification ID for specific flows | customer email address | (mandatory when msisdn or identid is missing) |
mno | Code of Mobile Network Operator in Centili’s system which end user belongs to. | ES_VODAFONE | mandatory / optional |
mccmnc | Mobile country code and mobile network code. | 23201 | optional |
msisdn | Customer mobile phone number. | 4477781234567 | optional |
clientid | Unique identification parameter under your system (pass-through variable). | appID1 | optional |
userid | Identification of the customer. | usrId1983 NOTE: If the value is not set within payment request, this field will contain MSISDN of the particular customer. | optional |
username | Configured under Partner Panel service, it is used only if API authentication is activated. | username | optional |
password | Configured under Partner Panel service, it is used only if API authentication is activated. | password | optional |
identid | ID of the identification transaction that preceded the payment request. | 123456789 | optional |
country | 2 letters country parameter. We are using "ISO 3166-1 alpha-2" standard. Here is full list of 2 letter country codes. | es | optional |
params | Special additional parameter. Allows adding design_id parameter in request if merchant want customized payment page. Any page customization must be allowed by MNO. | [{"name":"design_id","value":"1"}] | optional |
returnurl | URL to which user is redirected after payment. | optional (mandatory for url redirect flows) |
Keep in mind:
"mno" 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).
mccmnc parameter can be sent instead of parameter ''mno"
POST payment response
Once request is received, Centili will synchronously respond with POST response containing appropriate HTTP response and a list of parameters and values in JSON format:
HTTP/1.1 200 OK
Content-Type: application/json
{
"transactionType": "CHARGE",
"country": "rs",
"action":{
"simtcha": null,
"userInstruction": null,
"urlRedirect": null,
"type": "PIN",
"shortcode": null,
"keyword": null,
"urlReturn": "http://www.google.com"
},
"clientData":{
"clientUserId": null,
"clientReference": ""
},
"msisdn": "381644150105",
"transactionId": "17000002453",
"operator": "RS_MTS"
}
Response parameters:
Parameter | Description | Example |
---|---|---|
status | Indicates status of the current request. | Possible values:
|
errorMessage | Error description in case of failed transaction request. | Bad request |
transactionId | Unique identifier of transaction in Centili system. | 123456789 |
apikey | Centili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters. | f31a355df6dad07e49ba474db7ff9b07 |
clientId | Unique identification parameter under your system (pass-through variable reference; max length: 256 characters). | appID1 |
price | End user price for specific transaction. | 1.45 |
countryCode | Two-letter ISO 31661 international standard code. | FR |
operatorCode | Code of Mobile Network Operator in Centili’s system which end user belongs to. | ES_VODAFONE |
mcc | Mobile country code. | 232 |
mnc | Mobile network code. | 01 |
msisdn | Customer mobile phone number. | 4477781234567 |
action | Signifies type of flow for the initiated transaction. | Possible values:
NOTE: look for these instructions how to regulate further flow according to data received in our response (underneath this table). |
sessionStatus | Indicatior of current state of transaction. | Possible values:
|
urlRedirect | URL to which user should be redirected in order to continue with payment process (delivered only if action=URL_REDIRECT). | |
premiumInstructions | Instruction containing keyword and shortcode user needs to configure a confirmation MO message before sending (delivered only if action=PREMIUM). | "Please send GO to 1234 in order to confirm purchase." NOTE: instruction is displayed in a local language. Check our country coverage. |
shortCode | Shortcode contained in premium instruction (delivered only if action=PREMIUM). | 1234 |
smsBody | Keyword contained in premium instruction (delivered only if action=PREMIUM). | GO |
handshakeInstructions | Text instructing user to reply to the received MT message in order to confirm payment (delivered only if action=HANDSHAKE). | "Please send YES to 1234 in order to confirm purchase." NOTE: message is sent in a local language. Check our country coverage. |
Once transaction reaches a final state Payment Result Notification will be delivered to your system.
Instructions depending on the "Action" parameter value
Regulate further flow according to data received in our response:
"ACTION" 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. |
PREMIUM | You have two options:
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 12 months ago