Initiate Payment

In order to initiate payment with Centili Payment API 3.0, you need to send an HTTP POST request with Content-Type: application/json composed of parameters with associated values.

Before initiating a payment request you will need to obtain a bearer token

URL to which a request should be sent

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 token

{
  "userIdentifier": {
    "country": "rs",
    "imsi": null,
    "msisdn": "381644150105",
    "operator": null,
    "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-payment-2#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-payment-2#client-data)

{
"clientUserId": "usrId1983",
"pageCustomization": { },
"clientReference": "appID1",
"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-payment-2#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 payment 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

Payment transaction initiated

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transactionType": "CHARGE",
  "country": "rs",
  "action":{
    "userInstruction": null,
    "urlRedirect": null,
    "type": "PIN",
    "shortcode": null,
    "keyword": null,
    "urlReturn": "http://www.google.com"
  },
  "clientData":{
    "clientUserId": null,
    "clientReference": null
    },
  "msisdn": "381644150105",
  "transactionId": "17000002453",
  "operator": "RS_MTS"
}

Response parameters:

Parameter

Description

Example

transactionId

Unique identifier of a 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

action

Signifies type of flow for the initiated transaction. See (https://dev.centili.com/docs/initiate-payment-2#action)

{
"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

CHARGE

Action

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, URL_REDIRECT

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 - Payment 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

CANCELED_BY_USER

message

Error response message

Canceled by user

Once a 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: