Академический Документы
Профессиональный Документы
Культура Документы
0
OneAPI Payment REST API Guide
Date
Description
1.0
15 April 2014
Initial issue of OneAPI 2.1 Payment API Guide, with customized content for
AMP-ATI v1.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
5.1.2
Response - Charged.......................................................................................... 11
5.1.3
Response ............................................................................................................... 16
Refund a Subscriber ............................................................................................. 17
Request ................................................................................................................. 17
Request Parameters .......................................................................................... 18
7.1.1
Response ............................................................................................................... 20
7.2.1
7.2.2
8.2.2
Terminology
Term
Aggregator
Aggregators are intermediaries between the mobile carrier and content providers. They
provide connectivity to Airtel for content providers.
AMP
AoC
Advice of Charge
ASE
ATI
Airtel India
Charge
Payment transaction
CP
EULA
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
PSCP
PSE
PSL
REST
SSO
Single Sign-On
SOAP
SMSC
TPS
URI
URL
WSDL
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
This section; provides general information about the API and the
document.
2. Authentication
4. Replay Prevention
5. Charge a Subscriber
Authentication
Chapter
Description
7. Refund Subscriber
8. Resource States
Lists and describes the available resource states for this API, for
charge, refund and reservation transactions.
Lists and describes the HTTP response codes, service and policy
exceptions applicable to this API.
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.
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
https://{serverRoot}/2_1/payment/{endUserId}/transactions/amount/{transactionId}
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
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
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
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.
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
}
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
Request Parameters
Parameter
Data Type
Description
Optional
amountTransaction
AmountTransaction
No
contentUrl
URL
Yes
Parameter
Data Type
Description
Optional
endUserId
URI
No
string
No
Charge a Subscriber
Parameter
Data Type
Description
Optional
paymentAmount
paymentAmount
No
referenceCode
string
No
clientCorrelator
string
Yes
notifyURL
callbackReference
Yes
Table 4 Charge Amount to End User's Bill - Request Parameters (amountTransaction type)
Parameter
Data Type
Description
Optional
chargingInformation
chargingInformation
No
chargingMetaData
chargingMetaData
Yes
Table 5 Charge Amount to End User's Bill Request Parameters (paymentAmount type)
Parameter
Data Type
Description
Optional
description
string
No
currency
string
No
amount
decimal
No
10
Charge a Subscriber
Parameter
Data Type
Description
Max 6 characters
and to 2 decimal
points
Optional
Table 6 Charge Amount to End User's Bill - Request Parameters (chargingInformation type)
Parameter
Data Type
Description
Optional
purchaseCategoryCode
string
Yes
string
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/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
No
endUserId
URI
No
12
Charge a Subscriber
Parameter
Data Type
Description
Optional
paymentAmount
paymentAmount
No
transactionOperationStatus
string
No
referenceCode
string
No
No
Max length: 20
characters
serverReferenceCode
string
string
Yes
resourceURL
URI
No
Table 8 Charge Amount to End User's Bill - Response Parameters (amountTransaction type)
Parameter
Data Type
Description
Optional
chargingInformation
chargingInformation
No
totalAmountCharged
decimal
No (If an
additional
sum is added
to the
amount this
parameter
13
Charge a Subscriber
Parameter
Data Type
Description
Optional
becomes
mandatory.)
chargingMetaData
chargingMetaData
Yes
Table 9 Charge Amount to End User's Bill - Response Parameters (paymentAmount type)
Parameter
Data Type
Description
Optional
description
string
No
currency
string
No
amount
decimal
No
Max 6 characters
and to 2 decimal
points
Table 10 Charge Amount to End User's Bill - Response Parameters (chargingInformation type)
Parameter
Data Type
Description
Optional
purchaseCategoryCode
string
Yes
channel
string
Yes
Table 11 Charge Amount to End User's Bill - Response Parameters (chargingMetaData type)
14
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>
6.1.1
Data Type
Description
Optional
endUserId
URI
No
string
Yes
15
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
No
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
No
string
Yes
paymentAmount
paymentAmount
No
transactionOperationStatus
string
No
originalServerReferenceCode
string
No
18
Refund a Subscriber
Parameter
Data Type
Description
Optional
string
Max length: 20
characters
notifyURL
callbackReference
No
Yes
Parameter
Data Type
Description
Optional
chargingInformation
chargingInformation
No
chargingMetaData
chargingMetaData
Yes
Parameter
Data Type
Description
Optional
description
string
No
currency
string
No
amount
decimal
No
Max 6
characters and
to 2 decimal
points
19
Refund a Subscriber
Parameter
Data Type
Description
Optional
purchaseCategoryCode
string
Yes
string
Yes
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
No
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
Refunded
Denied
21
response codes, service and policy exceptions returned by the Subscriptions API service
sections 8.1 and 8.2
Response Codes
HTTP response codes are used to indicate:
200 Success!
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
503 Server busy and service unavailable. Please retry the request.
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
22
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]
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]
The requested terminal device address - the endUserId - does not exist.
Use an address that exists.
No valid address[es].
23
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
24
Explanation
Enforced
The error code is followed by text that describes the error, which
may be one of the following:
Reason
N/A
access_denied
invalid_request
server_error
invalid_request
invalid_request
server_error
ATI system could not update consent (either ALLOW or DENY) to AMP authorization
service even after multiple retries
25
Reason
invalid_request
ATI system detects an issue with originating IP address not being in Airtel ranges or
MSISDN inconsistency across HTTP headers.
End of Document
26