API Oneapi2 1 Payment Rest Ati

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 2

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

7.1.1 Request Parameters .......................................................................................... 18

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 3

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 4

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/payment-restful-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 5

http://oneapi.gsma.com/payment-restful-api/





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 6

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.

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

endUserId 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/transactions/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/amount

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 7

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/amount 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 8

http://example/callbackURL

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

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

5.1.1 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


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.

For OAuth authenticated requests, the

value is acr:Authorization.

No

transactionOperationStatus string This indicates the desired resource state.

See Table 23 for details.

No

Doc Version 1.0 9

Charge a Subscriber


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)


chargingInformation chargingInformation Provides the specific payment details. (See

Table 6 for details).

No

chargingMetaData chargingMetaData Provides additional payment details. (See


Yes

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


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


Max 6 characters

and to 2 decimal

points

Examples of valid values: 99, 999999, 9999.5,

999.55

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)


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.

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.)

Yes

channel string Indicates the source of user interaction.

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)

Yes

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/trans123 {"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/3aa82a8d-7ec2-4924-ab76-faafc5a2c492" }}

5.1.3 Response Parameters


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.

For responses to OAuth authenticated

requests, the value in would be

acr:Authorization.

No

Doc Version 1.0 12

Charge a Subscriber




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

Max length: 20

characters

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

serverReferenceCode string 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.

The same value as for transactionId.

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

resourceURL URI This is a self referring URL. No

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




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

is therefore the sum of the amount plus

any such additions.

No (If an

additional

sum is added

to the

amount this

parameter

Doc Version 1.0 13

Charge a Subscriber


becomes

mandatory.)



Yes

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


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

Max 6 characters

and to 2 decimal

points

This is the OneAPI parameter which maps to ATI's

actualPrice, the actual amount being charged. It can

be a whole number or decimal.

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

No

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




service, product or media being purchased.

Yes


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

no value is supplied, it will default to SMS.

Yes

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/abc123 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/abc123 HTTP/1.1 Authorization: Bearer <access token value>

6.1.1 Request URL Parameters


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.

For OAuth authenticated requests, the value is

acr:Authorization.

No

transactionId string The transaction Id used to uniquely identify

the transaction being queried.

The value is the same for

serverReferenceCode found in the response to

Charge.

Yes

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/1234" } }

The parameters in the response are the same as those returned in the charging request, as listed in

section 5.1.1.


transactionOperationStatus string Indicates the resource state. In this case it

confirms that the user has been “Charged”.

See section 7.2.1, Resource States for more

information.

No

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/amount 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


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.

For OAuth authenticated requests, the

value is acr:Authorization.

No

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



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.

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

No

Doc Version 1.0 18

Refund a Subscriber


is provided by the server. The same

value as for transactionId is used.

referenceCode string

Max length: 20

characters

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

notifyURL callbackReference Any URL, which is the TPA callback

URL for asynchronous payments and

refunds.

Yes

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




No



Yes

Table 15 Refund the User Request Parameters (paymentAmount type)


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

Max 6

characters and

to 2 decimal

points

This is the OneAPI parameter which maps to

ATI's actualPrice, the actual amount being

charged. It can be a whole number or decimal.

Examples of valid values: 999999, 9999.5,

999.55

No

Table 16 Refund the User Request Parameters (chargingInformation type)

Doc Version 1.0 19

Refund a Subscriber




service, product or media purchased and now

being refunded.

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.)

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)

Yes

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/abc123 {"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/efg789", "transactionOperationStatus": "Refunded" }}

7.2.1 Response Parameters

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


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

http://www.ietf.org/rfc/rfc2616.txt

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

enforced, and address is not in

Destination White List

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

white list. Check your SLA details.

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


Error Explanation

POL-054: Partner Spend Limit Policy

Enforced

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

limits and currency set in service properties.

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-59267-1376645127692-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


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

Documents

API Oneapi2 1 Payment Rest Ati