Payments (V2,V3,V3.1,V4)
Content
Overview
The Dialog Payment API allows you to charge mobile subscribers for the use of your application or content. It also allows you to charge a user directly based on their consent. Payment services are accessible via RESTful web services.
Method
The following REST method is available:
- Charging a subscriber
Requirements
Authorization API calls All API call request to ideabiz.lk required Authorization headers. Please refer the Token Management (http://docs.ideabiz.lk/Getting_Started/Token_Manegment) document for Authorization.
Request Header
Content-Type: application/json
Authorization: Bearer [access token]
Accept: application/json
Sample Request Header
Content-Type: application/json
Authorization: Bearer a92ba8hjgjhgjh3fa1609cabcd79
Accept: application/json
Encrypted MSISDN
Please refer the Secure Header (http://docs.ideabiz.lk/APIs/Header_Enrichment) document for encrypted MSISDNs.
Charging a subscriber
This allows you to charge a subscriber for a service provided by your application. All charges are Taxable, and Standard Taxes will be charged from the subscriber on top of the charging amount. *If you are a charity service or if different tax schemes are applicable for your service, please discuss with support team.
Request
Given below is a sample request of the send service.
URL
https://ideabiz.lk/apicall/payment/{version}/{msisdn}/transactions/amount
Sample URL for V4
https://ideabiz.lk/apicall/payment/v4/tel:+94766691500/transactions/amount
OR
https://ideabiz.lk/apicall/payment/v4/94766691500/transactions/amount
Method
POST
Body
{
"amountTransaction": {
"clientCorrelator": "54321",
"endUserId": "tel:+94766691500",
"paymentAmount": {
"chargingInformation": {
"amount": 1,
"currency": "LKR",
"description": "Test Charge"
},
"chargingMetaData": {
"onBehalfOf": "IdeaBiz Test",
"purchaseCategoryCode": "Service",
"channel": "WAP",
"taxAmount": "0",
"serviceID": "null"
}
},
"referenceCode": "REF-12345",
"transactionOperationStatus": "Charged"
}
}
NOTE: Please do not use the "serviceID" parameter if you're using Payment v3.
Given below are the Request parameters of the Payment service.
Parameter Name |
Description |
Type |
Mandatory/Optional |
clientCorrelator |
This uniquely identifies the Charging request. If there is a communication failure during the charging request, using the same clientCorrelator, when retrying the request, the operator can avoid applying the same charge twice. |
string |
Optional |
endUserId |
In this case the endUserId is the user's MSISDN including the 'tel:' protocol identifier and the country code preceded by '+'.Eg: tel:+94766691500. |
string |
Mandatory |
chargingInformation |
description -This is the text to include, to easily identify what the user has been charged for. This description should be limited to 190 characters. currency - This is the 3 figure code as per ISO 4217. amount - This is the actual amount being charged. It can be a whole number or a decimal. |
string string decimal |
Mandatory |
referenceCode |
You can append a reference code for each transaction, to identify or cross check the transactions initiated by your application. |
string |
Optional |
chargingMetaData type |
onBehalfOf - Allows aggregators/partners to specify the actual payee. purchaseCategoryCode - A category defining the type of service, product or media being purchased.(Optional - if you don't have a Category code, please keep this empty or remove this property) channel - Indicates the source of user interaction.(Optional - to identify in case several channels are available e.g. Web/ Mobile App/ SMS) taxAmount - Specify as '0' as Tax is already preconfigured in the platform serviceID - Charging reason code. This will override the default application reason code. (Optional - if you don't have a separate Reason code that prints your service name in the end users bill remove this property) |
string string string decimal |
Optional |
Response
Status code : 201
{
"amountTransaction": {
"clientCorrelator": "54321",
"endUserId": "tel:+94766691500",
"paymentAmount": {
"chargingInformation": {
"amount": "1",
"currency": "LKR",
"description": "Test Charge"
},
"totalAmountCharged": "1.0",
"chargingMetaData": {
"onBehalfOf": "IdeaBiz Test",
"purchaseCategoryCode": "Service",
"channel": "WAP",
"taxAmount": "0"
}
},
"referenceCode": "REF-12345",
"transactionOperationStatus": "Charged",
"serverReferenceCode": "DLG212005-1500564823863",
"resourceURL": "https://ideabiz.lk/apicall/payment/v2/94766691500/transactions/amount/DLG212005-1500564823863"
}
}
Check Balance
Please use the balance check API for this purpose. (http://docs.ideabiz.lk/APIs/Balance_Check)
Retry Payment
When the application needs to retry the same payment, send the same charging request with the same cleintCorrelator
. The System will then return the last charging status.
Eg : When your application receives an error, you can send the same request. The status of the previous request will be returned.
Support
SPECIAL CHARGING METHOD (NONETAX)
DEBIT REQUEST
Validation
The following will be validated.
endUserId
ClientCorrelator
Method
Amount
Success Response
Success Response same as API success response.
Status code : 201
Error Retry Response
{
"requestError": {
"serviceException": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": "Charging operation failed, ClientCorrelator exist and charging data not matched"
}
}
}
Enable Charging Retry
Please contact support@ideabiz.lk
to enable the Charging Retry feature.
Response Codes
201 – Success!
400 – Bad request; check the error message for details
401 – Authentication failure, check your authentication details
403 – Forbidden; please provide authentication credentials
404 – Not found: mistake in the host or path of the service URI
405 – Method not supported: for example you mistakenly used a HTTP GET instead of a POST
500 – The server encountered an unexpected condition. This could be wrong authentication details or limited user permission
503 – Server busy and service unavailable. Please retry the request.
Exceptions
Types
Policy Exception
Message Id start withPL
Server Exception
Message Id start with SV
Exception Body
{
"requestError": {
"serviceException": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": " clientCorrelator Value 12345"
}
}
}
User has insufficient credits for the transaction
Exception Body
{
"requestError":{
"policyException":{
"messageId": "POL1000",
"variables":"User has insufficient credit for transaction"
}
}
}
Number is inactive
Exception Body
{
"requestError":{
"serviceException":{
"messageId":"SVC0270",
"variables":"Charging operation failed, the charge was not applied"
}
}
}
Faults
HTTP Respose code 503
Fault Response Body
{
"fault": {
"code": "900800",
"message": "Message Throttled Out",
"description": "You have exceeded your quota"
}
}