API MONETIZATION PLATFORM AIRTEL INDIA 1.

0
OneAPI Payment REST API Guide

Document Version 1.0

This OneAPI Payment REST API Guide has been prepared for Airtel India.
Copyright Intel Corporation 2014; all rights reserved.

Document Revision History

Rev #

Date

Description

1.0

15 April 2014

Initial issue of OneAPI 2.1 Payment API Guide, with customized content for
AMP-ATI v1.0

Doc Version 1.0

Table of Contents
Terminology ................................................................................................................... 4
Overview ............................................................................................................... 5
References ............................................................................................................... 5
Document Structure.................................................................................................. 5
Authentication ....................................................................................................... 6
Methods and URIs .................................................................................................. 6
URIs ........................................................................................................................ 6
Replay Prevention .................................................................................................. 7
Charge a Subscriber ............................................................................................... 8
Request ................................................................................................................... 8
5.1.1

Request Parameters ............................................................................................ 9

5.1.2

Response - Charged.......................................................................................... 11

5.1.3

Response Parameters ........................................................................................ 12

Get Payment Transaction and Status ..................................................................... 15

Request ................................................................................................................. 15
6.1.1

Request URL Parameters ................................................................................... 15

Response ............................................................................................................... 16
Refund a Subscriber ............................................................................................. 17
Request ................................................................................................................. 17
Request Parameters .......................................................................................... 18

7.1.1

Response ............................................................................................................... 20
7.2.1

Response Parameters ........................................................................................ 21

7.2.2

Resource States ................................................................................................ 21

Response Codes & Exceptions ................................................................................ 22

Response Codes ...................................................................................................... 22
Exceptions ............................................................................................................. 22
8.2.1

Service Exceptions ............................................................................................ 22

8.2.2

Policy Exceptions .............................................................................................. 24

OAuth Error Codes .................................................................................................. 25

Doc Version 1.0

Terminology
Term

Description or Terms in an acronym/abbreviation

Aggregator

Aggregators are intermediaries between the mobile carrier and content providers. They
provide connectivity to Airtel for content providers.

AMP

API Monetization Platform

AoC

Advice of Charge

ASE

API Services Enabler

ATI

Airtel India

Charge

Payment transaction

CP

Merchant or Content Provider

EULA

End User License Agreement

One-Off purchase

One time charge purchase (as opposed to a subscription for which the Payments and
Settlement Engine generates user charges on a periodic basis)

Partner

Partner is the generic term for entities that connect to AMP. A partner may be an
aggregator of content providers or a single content provider that directly connects to
AMP.

PCC

Purchase Category Code, the term used in OneAPI to denote Media Type

PME

Partner Management Engine

PSCP

SmartAPI Partner Self-Care Portal

PSE

Payments and Settlement Engine

PSL

Portal Service Layer (API layer of PME)

REST

Representational state transfer (REST or RESTful) is a style of software architecture for

distributed systems such as the World Wide Web.

SSO

Single Sign-On

SOAP

A web services protocol specification for exchanging structured information. It used to

be called Simple Object Protocol but this definition is no longer valid.

SMSC

Short Message Service Centre

TPS

Transactions per second

URI

Uniform resource identifier is a string of characters used to identify a name of a web

resource.

URL

Uniform Resource Locator

WSDL

Web Services Description Language is an XML-based interface description language that

is used for describing the functionality offered by a web service.

Doc Version 1.0

Overview
This document is a user guide for OneAPI v2.1 Payment RESTful API as provided on the SmartAPI
platform via AMP-ATI v1.0.
The Payment interface allows an application to perform payment operations such as one step
charging, refund, reserve and commit charging and status queries. The specification is closely
aligned to the GSMA Payment v2.1 specification found at http://oneapi.gsma.com/oneapi/paymentrestful-netapi, with enhancements.
The API is integrated with AMP-ATI OAuth solution via WEB/WAP channels.
AMP-ATI OneAPI v2.1 Payment API implementation supports JSON and URL encoded formats. The
parameters can be used for requests and responses in either format.

Throughout this document, the examples may be shown WITHOUT URL encoding for readability
purposes.

References
A Sandbox service for this API is described in API_AMP-ATI_Sandbox-REST
OAuth API is described in API_AMP-ATI_OAuth-REST Common information on API and usage are
captured in API_OneAPI2-0_Common-Information-Guide
The SmartAPI Partner Self-Care Portal features are captured in USG_AMP-ATI-1.0_PME-2.0_PSCP

Document Structure
This document is divided into the following chapters/sections:
Chapter

Description

1. About this Document

This section; provides general information about the API and the
document.

2. Authentication

Provides notes on authentication requirements for using this API.

3. Methods and URIs

Lists the methods, URIs, operations and common variables used

for this API.

4. Replay Prevention

Describes the reply prevention function provided with this API.

5. Charge a Subscriber

Describes the method, with request and response examples and

parameters.

6. Get Payment Transaction and Status

Describes the method, with request and response examples and

parameters.

Doc Version 1.0

Authentication
Chapter

Description

7. Refund Subscriber

Describes the method, with request and response examples and

parameters.

8. Resource States

Lists and describes the available resource states for this API, for
charge, refund and reservation transactions.

9. Response Codes & Exceptions

Lists and describes the HTTP response codes, service and policy
exceptions applicable to this API.

Table 1 Document Structure

Authentication
A server side certificate is required as well as HTTP Basic Authentication, when SMS/USSD/IVR
channels are used. For more information, refer to the ''Developer Access' section in the 'OneAPI v2.0
Common Information Guide'.
If WAP/WEB channel is used for charge or refund operation, OAuth service provided by AMP-ATI is
used. Access the service first to obtain the token, to populate the Authorization header in your
request.

Methods and URIs

Payment is accessible via a REST API. The following methods are available:

Charge a Subscriber - section 5

Get Payment Transaction and Status - section 6

Refund a Subscriber section 7

OneAPI Payments use GET and POST operations as described below. The URIs used in the Payment
API are described below.

URIs

https://{serverRoot}/2_1/payment/{endUserId}/transactions/amount

Charge a user (one step charging) POST operation

Refund a user POST operation

https://{serverRoot}/2_1/payment/{endUserId}/transactions/amount/{transactionId}

Get payment transaction and status GET operation

The following request URL variables are common to all the URIs:

Doc Version 1.0

Replay Prevention
Name

Description

serverRoot

Server base url: hostname (+port+base) path, for example example.com/xyz, which can be
found as the URL on the SAPI Partner Portal by navigating from the Dashboard > Manage

Partner > Manage Project > Endpoints.

Example:
If the URL shown on the page for the Payment service is

https://openapi.airtel.in/serivces2/payment,
the URI to use for a Charge request will be

https://openapi.airtel.in/services2/payment/2_1/payment/{endUserId}/transactions/amount.

!
endUserId

In this guide, example.com is used as the {serverRoot} value.

The account to charge. The value in this field takes two forms, depending on the type of
authentication used.
When using BASIC authentication, this is the 12 digit MSISDN, including country code, which
must be URL encoded.
If the MSISDN is +910123456789, following the example above, a charge request URI will be

https://openapi.airtel.in/services2/payment/2_1/payment/tel%3A%2B910123456789/transact
ions/amount
as URL encoding for : and + are %3A and %2B respectively.
When using OAuth authentication&authorization, this field takes the anonymous value
acr:Authorization, for example:

https://openapi.airtel.in/services2/payment/2_1/payment/acr:Authorization/transactions/am
ount

Table 2 Common Request URL Variables

The Payments API supports application/x-www-form-urlencoded and JSON types for POST
operations. The response content type is application/JSON.

Replay Prevention
If there is a communication failure when attempting to charge a user, OneAPI includes parameters
to ensure that you can try again without charging the user twice. clientCorrelator is a nonce that
you can pass with any POST requests. If the OneAPI server sees the same clientCorrelator twice, it
will recognize it as a duplicate request, and throw an exception without having applied any backend
processing again.

Doc Version 1.0

Charge a Subscriber
This section describes how to charge a subscriber for a service provided by your application.
By default the charge payment request is synchronous in other words, the charge will be applied
immediately and a suitable response returned to the initial request. However, when Advice of Charge
is used, the initial response returned will be of status Processing; when the AoC flow is completed
and the charge is applied, a notification with the status Charged will be sent to the application.

Request
Example JSON request (with notifyURL) with Basic authentication
POST
http://example.com/2_1/payment/tel%3A%2B913097000011/transactions/amoun
t
HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic <base64 encoded application credentials>
{amountTransaction": {
"clientCorrelator": "54321",
"endUserId": "tel:+913097000011",
"paymentAmount": {
"chargingInformation": {
"amount": 10,
"currency": "INR",
"description": ["Alien Invaders Game"]
},
"chargingMetaData" : {
"purchaseCategoryCode" : "Game",
"channel" : "SMS",
}
},
"referenceCode": "REF-12345",
"transactionOperationStatus": "Charged",
callbackReference:{
notifyURL: http://example/callbackURL
}
},
contentUrl: https://content.download.com
}

Example Form Encoded request (without notifyURL) with OAuth authentication

Doc Version 1.0

Charge a Subscriber
POST
http://example.com/2_1/payment/acr:Authorization/transactions/amount
HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <access token value, for example,
MDYzODdmYjU1NDMyNGYwYWQzN2VhO>
clientCorrelator=54321&
endUserId=acr:Authorization
amount=10&
currency=INR&
description=Alien%20Invaders%20Game&
purchaseCategoryCode=Game&
channel=WEB&
referenceCode=REF-12345&
transactionOperationStatus=Charged&
contentUrl=https%3A%2F%2Fcontentldownload.com

!
5.1.1

In the URI, '/2_1/' represents the API version.

Request Parameters
Parameter

Data Type

Description

Optional

amountTransaction

AmountTransaction

Provides the specific payment details. (See

table below for details).

No

contentUrl

URL

Custom parameter for content download

link.

Yes

Table 3 Charge Amount to End User's Bill - Request Parameters

Parameter

Data Type

Description

Optional

endUserId

URI

For requests with basic authentication,

this is the URL-escaped end user ID. In
this case the MSISDN including the 'tel:'
protocol identifier and the country code
preceded by '+', e.g. tel:+913097000011.

No

For OAuth authenticated requests, the

value is acr:Authorization.
transactionOperationStatus

Doc Version 1.0

string

This indicates the desired resource state.

See Table 23 for details.

No

Charge a Subscriber
Parameter

Data Type

Description

Optional

paymentAmount

paymentAmount

Provides a breakdown of the payment

information. (See Table 5 for details).

No

referenceCode

string

This is unique per charge event. It is

your reference for reconciliation
purposes. The operator should include it
in reports so that you can match their
view of what has been sold with yours.

No

clientCorrelator

string

This uniquely identifies the create

charge request. If there is a
communication failure during the
charge request, using the same
clientCorrelator when retrying the
request allows the operator to avoid
applying the same charge twice.

Yes

notifyURL

callbackReference

Any URL, which is the TPA callback URL

for asynchronous payments and
refunds.

Yes

Table 4 Charge Amount to End User's Bill - Request Parameters (amountTransaction type)

Parameter

Data Type

Description

Optional

chargingInformation

chargingInformation

Provides the specific payment details. (See

Table 6 for details).

No

chargingMetaData

chargingMetaData

Provides additional payment details. (See

Table 7 for details).

Yes

Table 5 Charge Amount to End User's Bill Request Parameters (paymentAmount type)

Parameter

Data Type

Description

Optional

description

string

This is the text to appear on the user's bill to

allow them to easily identify what they have
bought.

No

currency

string

INR, the 3 figure code as per ISO 4217.

No

amount

decimal

This is the OneAPI parameter which maps to

ATI's actualPrice, the actual amount being
charged.

No

Doc Version 1.0

10

Charge a Subscriber
Parameter

Data Type

Description

Max 6 characters
and to 2 decimal
points

Examples of valid values: 99, 999999, 9999.5,

999.55

Optional

For values under INR 1, the decimal point

must be preceded by 0. For example, to
denote 50 cents, enter 0.5, not .5.

Table 6 Charge Amount to End User's Bill - Request Parameters (chargingInformation type)

Parameter

Data Type

Description

Optional

purchaseCategoryCode

string

The OneAPI parameter which maps to ATI's

mediaType, a category defining the type of
service, product or media being purchased. This is
used to enforce a permitted amount range for the
product.

Yes

If no value is supplied, it will default to the

mediaType value set for the application.
If a value is passed, it will be validated. Currently
valid values are music, book and game. Entering
an invalid value will result in a service error being
returned. (See section 8.2.1.)
channel

string

Indicates the source of user interaction.

Yes

Valid values are SMS, WAP, WEB and USSD. If no

value is supplied, it will default to SMS.

If SMS/USSD/IVR is set for the service, basic

authentication is used and the request is sent
directly.

If WAP/WEB is set for the service, OAuth is

used, in which case an OAuth token is
validated, and a call is made to the Product
InfoService which will enrich the request
with additional fields (productName,
productDescription, productPrice,
productActive, validityPeriod and cpId)

Table 7 Charge Amount to End User's Bill - Request Parameters (chargingMetaData type)

5.1.2

Response - Charged
If the transaction is immediately confirmed, the response is displayed as follows:
Example response to a request made with Basic authentication
HTTP/1.1 201 Created
Doc Version 1.0

11

Charge a Subscriber
Content-Type: application/json
Location:
http://example.com/2_1/payment/tel:+913097000021/transactions/amount/tr
ans123
{"amountTransaction": {
"endUserId": "tel:+913097000021",
"paymentAmount": {
"chargingInformation": {
"description": ["Alien Invaders Game"],
"currency": "INR",
"amount": 10,
},
"totalAmountCharged": 10,
"chargingMetaData" : {
"purchaseCategoryCode" : "Game",
"channel" : "SMS",
}
},
"transactionOperationStatus": "Charged"
"referenceCode": "REF-23167",
"serverReferenceCode": "trans123",
"clientCorrelator": "741268",
"resourceURL":
"http://example.com/2_1/payment/tel:+913097000021/transactions/amount/3
aa82a8d-7ec2-4924-ab76-faafc5a2c492"
}}

5.1.3

Response Parameters
Parameter

Data Type

Description

Optional

transactionId

string

This is the new transaction ID which

uniquely identifies this charge transaction.
In the sample code above, it can be found
in the Location URL in the header, i.e.
'trans123'.

No

endUserId

URI

This is the URL-escaped end user ID. In this

case the MSISDN including the 'tel:'
protocol identifier and the country code
preceded by '+', e.g. tel:+913097000021.

No

For responses to OAuth authenticated

requests, the value in would be
acr:Authorization.

Doc Version 1.0

12

Charge a Subscriber
Parameter

Data Type

Description

Optional

paymentAmount

paymentAmount

Provides a breakdown of the payment

information. (See Table 5 for details).

No

transactionOperationStatus

string

Indicates the resource state. In this case it

has been successfully Charged. See Table
23 Charge/Refund Transaction States for
details.

No

referenceCode

string

This is unique per charge event. It is your

reference for reconciliation purposes. The
operator should include it in reports so
that you can match their view of what has
been sold with yours.

No

This is a reference to the charge or refund

transaction, which is provided by the
server. It is used for reconciliation
purposes. If it has been provided, it will
need to be referred to in any subsequent
refund for this charge.

No

Max length: 20
characters

serverReferenceCode

string

The same value as for transactionId.

clientCorrelator

string

This uniquely identifies the create charge

request. If there is a communication failure
during the charge request, using the same
clientCorrelator when retrying the request
allows the operator to avoid applying the
same charge twice.

Yes

resourceURL

URI

This is a self referring URL.

No

Table 8 Charge Amount to End User's Bill - Response Parameters (amountTransaction type)

Parameter

Data Type

Description

Optional

chargingInformation

chargingInformation

Provides the specific payment details. (See

Table 6 for details).

No

totalAmountCharged

decimal

This is provided if the end user was

charged any additional amount (such as
taxes, transaction fees etc.) on their bill. It

No (If an
additional
sum is added
to the

is therefore the sum of the amount plus

any such additions.

amount this
parameter

Doc Version 1.0

13

Charge a Subscriber
Parameter

Data Type

Description

Optional
becomes
mandatory.)

chargingMetaData

chargingMetaData

Provides additional payment details. (See

Table 7 for details).

Yes

Table 9 Charge Amount to End User's Bill - Response Parameters (paymentAmount type)

Parameter

Data Type

Description

Optional

description

string

This is the text to appear on the user's bill to allow

them to easily identify what they have bought.

No

currency

string

This is the 3 figure code as per ISO 4217.

No

amount

decimal

This is the OneAPI parameter which maps to ATI's

actualPrice, the actual amount being charged. It can
be a whole number or decimal.

No

Max 6 characters
and to 2 decimal
points

Examples of valid values: 99, 999999, 9999.5, 999.55

Table 10 Charge Amount to End User's Bill - Response Parameters (chargingInformation type)

Parameter

Data Type

Description

Optional

purchaseCategoryCode

string

The OneAPI parameter which maps to ATI's

mediaType, a category defining the type of
service, product or media being purchased.

Yes

channel

string

Indicates the source of user interaction.

Yes

Valid values are SMS, WAP, WEB and USSD. If

no value is supplied, it will default to SMS.

Table 11 Charge Amount to End User's Bill - Response Parameters (chargingMetaData type)

Doc Version 1.0

14

Get Payment Transaction and Status

The status of a transaction can be checked at any time by the getPaymentTransaction method. You
can use the resourceURL returned in the response to set your GET request.

Request
Example request with Basic authentication
GET
http://example.com/2_1/payment/tel:+913097000011/transactions/amount/ab
c123
HTTP/1.1
Authorization: Basic <base64 encoded application credentials>

Example request with OAuth authentication

GET
http://example.com/2_1/payment/acr:Authorization/transactions/amount/ab
c123
HTTP/1.1
Authorization: Bearer <access token value>

6.1.1

Request URL Parameters

Parameter

Data Type

Description

Optional

endUserId

URI

For requests using basic authentication, this is

the URL-escaped end user ID. In this case the
MSISDN including the 'tel:' protocol identifier
and the country code preceded by '+', e.g.
tel:+913097000011.

No

For OAuth authenticated requests, the value is

acr:Authorization.
transactionId

string

The transaction Id used to uniquely identify

the transaction being queried.

Yes

The value is the same for

serverReferenceCode found in the response to
Charge.

Table 12 Query the Status of a Transaction Request Parameters

Doc Version 1.0

15

Get Payment Transaction and Status

Response
Example response to a request made with Basic authentication
HTTP/1.1 200 OK
Content-Type: application/json
{
"amountTransaction" : {
"endUserId" : "tel:\+919811098110",
"paymentAmount" : {
"chargingInformation" : {
"description" : \[ "Alien Invaders Game" \],
"currency" : "INR",
"amount" : 10.00
},
"totalAmountCharged" : 10.00,
"chargingMetaData" : {
"purchaseCategoryCode" : "Games",
"channel" : "SMS",
"taxAmount" : 0.00
}
},
"transactionOperationStatus" : "Charged",
"referenceCode" : "REF-9999",
"serverReferenceCode" : "1234",
"resourceURL" :
"http://example.com/2_1/payment/tel:+919811098110/transactions/amount/1
234"
}
}
The parameters in the response are the same as those returned in the charging request, as listed in
section 5.1.1.
Parameter

Data Type

Description

Optional

transactionOperationStatus

string

Indicates the resource state. In this case it

confirms that the user has been Charged.

No

See section 7.2.1, Resource States for more

information.

Table 13 Query the Status of a Transaction Response Parameters

Doc Version 1.0

16

Refund a Subscriber
This section describes how to refund a subscriber for a service, product or media which was
purchased. Only full refunds are permitted.

Request
Example JSON request, with basic authentication
POST
http://example.com/2_1/payment/tel%3A%2B913097000011/transactions/amoun
t
HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic<base64 encoded application credentials>
{"amountTransaction": {
"clientCorrelator": "54321",
"endUserId": "tel:+913097000011",
"paymentAmount": {
"chargingInformation": {
"amount": 10,
"currency": "INR",
"description": ["Alien Invaders Game"]
},
"chargingMetaData": {
"purchaseCategoryCode": "Game",
"channel": "SMS",
}
},
"referenceCode": "REF-12345",
"originalServerReferenceCode": "abc123",
"transactionOperationStatus": "Refunded"
}}
Example Form Encoded request, with OAuth authentication
POST
http://example.com/2_1/payment/acr:Authorization/transactions/amount
HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <access token value, for example,
MDYzODdmYjU1NDMyNGYwYWQzN2VhO>
clientCorrelator=54321&
endUserId=acr:Authorization
amount=10&
Doc Version 1.0

17

Refund a Subscriber
currency=INR&
description=Alien%20Invaders%20Game&
purchaseCategoryCode=Game&
channel=WEB&
referenceCode=REF-12345&
originalServerReferenceCode=abc123&
transactionOperationStatus=Refunded

Use POST because you are creating a refund to an end user's account.

7.1.1

Request Parameters
Parameter

Data Type

Description

Optional

endUserId

URI

For requests with basic authentication,

this is the URL-escaped end user ID. In
this case the MSISDN including the 'tel:'
protocol identifier and the country
code preceded by '+', e.g.
tel:+913097000011.

No

For OAuth authenticated requests, the

value is acr:Authorization.
clientCorrelator

string

This uniquely identifies the refund

request. If there is a communication
failure during the refund request, using
the same clientCorrelator when
retrying the request allows the
operator to avoid applying the same
refund twice.

Yes

paymentAmount

paymentAmount

Provides a breakdown of the payment

information. (See Table 13 for details).

No

transactionOperationStatus

string

Indicates the resource state. In this

case 'Refunded' is used to refund the
user's account. See section 7.2.1 for
details.

No

originalServerReferenceCode

string

This is used to reconcile a refund

request with the original charge which
is being refunded.

No

To do this, the serverReferenceCode

returned in the original charge request
response must be entered here.
ServerReferenceCode is a reference to
the charge or refund transaction, which

Doc Version 1.0

18

Refund a Subscriber
Parameter

Data Type

Description

Optional

is provided by the server. The same

value as for transactionId is used.
referenceCode

string
Max length: 20
characters

notifyURL

callbackReference

This is unique per refund event. It is

your reference for reconciliation
purposes. The operator should include
it in reports so that you can match
their view of what has been refunded
with yours.

No

Any URL, which is the TPA callback

URL for asynchronous payments and
refunds.

Yes

Table 14 Refund the User - Request Parameters (amountTransaction type)

Parameter

Data Type

Description

Optional

chargingInformation

chargingInformation

Provides the specific payment details. (See

Table 6 for details).

No

chargingMetaData

chargingMetaData

Provides additional payment details. (See

Table 7 for details).

Yes

Table 15 Refund the User Request Parameters (paymentAmount type)

Parameter

Data Type

Description

Optional

description

string

This is the text to appear on the user's bill to

allow them to easily identify the item for which
they are being refunded.

No

currency

string

This is the 3-character currency code as per ISO

4217. This is mandatory if an amount is
specified.

No

amount

decimal

This is the OneAPI parameter which maps to

ATI's actualPrice, the actual amount being
charged. It can be a whole number or decimal.

No

Max 6
characters and
to 2 decimal
points

Examples of valid values: 999999, 9999.5,

999.55

Table 16 Refund the User Request Parameters (chargingInformation type)

Doc Version 1.0

19

Refund a Subscriber

Parameter

Data Type

Description

Optional

purchaseCategoryCode

string

The OneAPI parameter which maps to ATI's

mediaType, a category defining the type of
service, product or media purchased and now
being refunded.

Yes

Entering no value will default to the mediaType

value set for the application.
If a value is entered, it is validated. Currently
valid values are music, book and game. Entering
an invalid value will result in a service error
being returned. (See section 8.2.1.)
channel

string

Indicates the source of user interaction.

Yes

Valid values are SMS, WAP, WEB and USSD. If no

value is supplied, it will default to SMS.

If SMS/USSD is set for the service, basic

authentication is used and the request is
sent directly

If WAP/WEB is set for the service, OAuth is

used, in which case an OAuth token is
validated, and a call is made to the Product
InfoService which will enrich the request
with additional fields (productName,
productDescription, productPrice,
productActive, validityPeriod and cpId)

Table 17 Refund the User - Request Parameters (chargingMetaData type)

Response
Example response to a request made with OAuth authentication
HTTP/1.1 201 Created
Content-Type: application/json
Location:
http://example.com/2_1/payment/acr:Authorization/transactions/amount/ab
c123
{"amountTransaction": {
"clientCorrelator": "54321",
"endUserId": "acr:Authorization",
"paymentAmount": {
"chargingInformation": {
"amount": 10,
Doc Version 1.0

20

Refund a Subscriber
"currency": "INR",
"description": ["Alien Invaders"]
},
"chargingMetaData": {
"purchaseCategoryCode": "Game",
"channel": "SMS",
},
"totalAmountRefunded": 10
},
"referenceCode": "REF-12345",
"originalServerReferenceCode":"abc123",
"resourceURL":
"http://example.com/2_1/payment/acr:Authorization/transactions/amount/e
fg789",
"transactionOperationStatus": "Refunded"
}}

7.2.1

Response Parameters
The parameters in the request are returned in the response along with the following:
Parameter

Data Type

Description

Optional

totalAmountRefunded

decimal

This is the total amount which has now been

refunded to the user.

No

Table 18 Refund the User - Response Parameters (paymentAmount type)

7.2.2

Resource States
The client passes the transactionOperationStatus in the request body so that the resource can be
placed into a desired state. The server either confirms this desired state in the
transactionOperationStatus response field, or shows a different state as listed in the Resource
States table below.
The resource http://{serverRoot}/2_1/payment/{endUserId}/transactions/amount which represents a
basic charge or refund against an account may return the following transaction states:
State

Description

Charged

A successful charge was made.

Refunded

A successful refund was made.

Denied

An asynchronous charge/refund was denied. The policy exception in the response

explains the reason, e.g. insufficient balance, security issue etc.

Table 19 Charge/Refund Transaction States

Doc Version 1.0

21

Response Codes & Exceptions

This section provides information on the following:

response codes, service and policy exceptions returned by the Subscriptions API service
sections 8.1 and 8.2

OAuth error codes section

Response Codes
HTTP response codes are used to indicate:

200 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 incorrect

authentication details or limited user permission

503 Server busy and service unavailable. Please retry the request.

For more details on these, refer to http://www.ietf.org/rfc/rfc2616.txt.

Exceptions
This section lists the available error codes, the possible reasons why the exception may occur, and
possible solutions.

8.2.1

Service Exceptions
The following service exceptions may be thrown:
Error

Explanation

SVC0001: An internal service

error occurred

An internal error has occurred as a result of a client invocation on the

service. This category can be used for implementation specific errors.
Contact the support team.
For example, it may indicate an error due to unexpected condition or bad
request. INTERNAL_ERROR (Error code 500) indicates an error during AMP
processing; Error code 400.

Doc Version 1.0

22

Response Codes & Exceptions

Error

Explanation
For example, if the client correlator is not idempotent for the operation
(applicable when idempotency is enforced), the following text will be
returned:
Idempotent operation already exists for correlator: [client correlator] and
operation: [sendSms]

SVC0002: Invalid input value

An input parameter value is not of the expected type. Check the parameter
types and re-submit your request.
Invalid input value [<value>] for parameter [<parameter>]
These apply to mandatory values if they are null/blank, and to certain
values specific to the call, for example an inappropriate
transactionOperationStatus. For example,
INVALID_INTERVAL: if the specified interval has a start time after the end
time or is in the future
INVALID_TRANSACTIONID: if the specified transactionId is not recognized
INVALID_TRANSACTIONS_STATE: if a refund request is made for a
transaction in state other than CONFIRMED
TRANSACTION_HAS_BEEN_ALREADY_REFUNDED: if the refund request is
for a transaction already refunded
SUSPENDED_USER: propagated from downstream system errors
if the amount <value> cannot be found:
Invalid input value [null] for parameter [amount]

if the transactionOperationStatus in a charge/refund operation is

other than Charged or Refunded:

Invalid input value [Reserved] for parameter [transactionOperationStatus]

if there is a mismatch between the endUserIds entered in the URI

and in the body of the request:

Invalid value [<endUserId1>,<endUserId2>] for parameter [endUserId]

SVC0004: No valid address(es)

The requested terminal device address - the endUserId - does not exist.
Use an address that exists.
No valid address[es].

SVC0270: Charging operation

failure

Charging operation failed and the charge was not applied.

Table 20 Service Exception Error Codes

Service Exception Response Example

The example below shows the response where the parameter code is missing.

Doc Version 1.0

23

Response Codes & Exceptions

Response-Code: 400
Content-Type: application/json
Headers: {Content-Type=[application/json], Date=[Wed, 08 May 2013
15:57:08 GMT]}
Payload: {
"requestError" : {
"serviceException" : {
"messageId" : "SVC0002",
"text" : "Invalid value [null] for parameter [code]"
}
}
}

8.2.2

Policy Exceptions
A policy exception means that the request syntax is valid, but an operator policy has been broken.
POL0001 - Policy error occurred
The above exception may be thrown to indicate a fault relating to a policy associated with the
service. This category can be used for implementation-specific errors such as:
Error

Explanation

Authorization

Applicable if Privacy service is enabled. Consent has not been

obtained by the application for the subscriber.

POL-006: TPA exceeded its maximum

allowed rate of transactions

The maximum rate of transactions is exceeded. Ensure that the rate

of your requests is within the limits set up in your SLA, e.g. 10 TPS
(Transactions Per Second).

POL-008: TPA is invalid

The Third Party Application authentication details are incorrect.

Check your basic authentication username and password are
correct and re-submit your request.

POL-014: Destination White List is

A destination white list is enforced and the number is not in the

white list. Check your SLA details.

enforced, and address is not in

Destination White List
POL-016: Max Requests is enforced, and
max requests has been exceeded

The maximum number of requests for this service is exceeded.

Contact the support team.

POL-017: Operation is not allowed

The method/operation is not supported in your current SLA. Check

your SLA and use a method that is supported.

POL-028: Destination Black List is

enforced, and address is in Destination
Black List

A destination black list is enforced and the number is in the black

list. Check your SLA details.

Doc Version 1.0

24

Response Codes & Exceptions

Error

Explanation

POL-054: Partner Spend Limit Policy

This is a service specific policy, and relates to the partner spend

limits and currency set in service properties.

Enforced

The error code is followed by text that describes the error, which
may be one of the following:

Maximum spend limit per transaction exceeded

Minimum spend limit per transaction is not reached

Mismatch between request and spendlimit currencies

Table 21 Policy Error Codes

Policy Exception Response Example

{
"requestError" : {
"policyException" : {
"messageId" : "POL0001",
"text" : "A policy error occurred. Error code is POL-054: Partner Spend
Limit Policy Enforced: Maximum spend limit per transaction is
exceeded.",
"variables" : [ "POL-054", "Partner Spend Limit Policy Enforced:
Maximum spend limit per transaction is exceeded.", "ID-salmon-592671376645127692-8-38" ]
}
}
}

OAuth Error Codes

The CP may receive the following OAuth errors:
OAuth Error

Reason

N/A

User clicks on YES button on consent page

access_denied

User clicks on NO button on consent page

invalid_request

Validation Failure on portal

server_error

Exception occurred in portal while processing the request

invalid_request

MSISDN sent in the request is not authentic

invalid_request

Network passes the MSISDN in the header parameters

server_error

ATI system could not update consent (either ALLOW or DENY) to AMP authorization
service even after multiple retries

Doc Version 1.0

25

Response Codes & Exceptions

OAuth Error

Reason

invalid_request

ATI system detects an issue with originating IP address not being in Airtel ranges or
MSISDN inconsistency across HTTP headers.

Table 22 OAuth Error Codes

End of Document

Doc Version 1.0

26