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.

URL to which request should be posted:

https://api.centili.com/api/payment/1_4/transaction

POST payment request

POST https://api.centili.com/api/payment/1_4/transaction HTTP/1.1
Host: api.centili.com:443
Content-Type: application/json

{
"apikey":"2ea0e6c989b433d6c591633f91c67e07",
"price":"6.05",
"country":"es",
"msisdn":"34666xxxxxx"
}

All possible initiation parameters:

ParameterDescriptionExampleRequired as
apikeyCentili 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
priceidIdentifier of a specific package under Centili platform.324optional
mnoCode of Mobile Network Operator in Centili’s system which end user belongs to.ES_VODAFONE
(for Vodafone Spain)
mandatory / optional
Look for "Keep in mind" callout box underneath this table.
mccmncMobile country code and mobile network code.23201
(for A1 Telekom Austria)
optional
Look for "Keep in mind" callout box underneath this table.
msisdnCustomer mobile phone number.
NOTE: The number must be in E.164 format, excluding the plus ("+") character.
4477781234567optional
(mandatory for WiFi flow)
Look for "Keep in mind" callout box underneath this table.
clientidUnique identification parameter under your system (pass-through variable).appID1optional
useridIdentification of the customer.usrId1983

NOTE: If the value is not set within payment request, this field will contain MSISDN of the particular customer.
optional
usernameConfigured under Partner Panel service, it is used only if API authentication is activated.usernameoptional
passwordConfigured under Partner Panel service, it is used only if API authentication is activated.passwordoptional
identidID of the identification transaction that preceded the payment request.123456789 optional
(mandatory for 3G flow)
country2 letters country parameter. We are using "ISO 3166-1 alpha-2" standard. Here is full list of 2 letter country codes.esoptional
paramsSpecial 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
returnurlURL to which user is redirected after payment.http://www.example.com 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

{
"status":"ACCEPTED",
"transactionid":"123456789"
"clientid": “xxxxxxxxx”,
"action": “URL_REDIRECT”,
"redirecturl":” http://www.exampleURL.com”,
"sessionStatus": “PENDING”,
"countryCode": “es”,
"apiKey":”123456abcdefg” 
}

Response parameters:

ParameterDescriptionExample
statusIndicates status of the current request.Possible values:
ACCEPTED
CHARGING_FAILED
INVALID_REQUEST
INVALID_SERVICE
UNAUTHORIZED
INACTIVE
INVALID_MSISDN
INVALID_OPERATOR_CODE
INVALID_MCCMNC
INVALID_PRICE
DAILY_LIMIT_EXCEEDED
MONTHLY_LIMIT_EXCEEDED
errorMessageError description in case of failed transaction request.Bad request
transactionIdUnique identifier of transaction in Centili system.123456789
apikeyCentili issued service key, unique for every payment service. Consists of alphanumeric characters and counts up to 32 characters.f31a355df6dad07e49ba474db7ff9b07
clientIdUnique identification parameter under your system (pass-through variable reference; max length: 256 characters).appID1
priceEnd user price for specific transaction.1.45
countryCodeTwo-letter ISO 31661 international standard code.FR
(for France)
operatorCodeCode of Mobile Network Operator in Centili’s system which end user belongs to.ES_VODAFONE
(for Vodafone Spain)
mccMobile country code.232
(example for Austria)
mncMobile network code.01
msisdnCustomer mobile phone number.
NOTE: The number must be in E.164 format, excluding the plus ("+") character.
4477781234567
actionSignifies type of flow for the initiated transaction.Possible values:

URL_REDIRECT
PREMIUM
PIN
HANDSHAKE

NOTE: look for these instructions how to regulate further flow according to data received in our response (underneath this table).
sessionStatusIndicatior of current state of transaction.Possible values:

PENDING
FAILED
* COMPLETED
urlRedirectURL to which user should be redirected in order to continue with payment process (delivered only if action=URL_REDIRECT).
premiumInstructionsInstruction 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.
shortCodeShortcode contained in premium instruction (delivered only if action=PREMIUM).1234
smsBodyKeyword contained in premium instruction (delivered only if action=PREMIUM).GO
handshakeInstructionsText 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 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.
PREMIUMYou 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: