Open API Project
USCC AMP Payment SOAP API
Developer Guide
Document Version 1.7
Document Revision History
Rev #
Date
Description
1.0
Jun 28 2013
Created based on TSP-USCC-OpenAPI_AMP-v1.0d.docx.
1.1
Aug 23 2013
Corrections: 4.2.1 api:callContext amended to
pay:context; example in 5.5.1 updated to include the
mandatory pcc property of LineItem, which was missing.
1.2
Sep 27 2013
Appendix B, Sandbox section added.
1.3
Nov 1 2013
Appendix B, updated URL to match production platform.
1.4
Jul 11 2014
Updated for CASS project. Added
mandateSetup:context:orderId; Payment Notifications
section with Service Order Notification details; Partner
Payment API Concepts section.
Removed list of error codes and referenced out to a
separate Error Codes Guide.
1.5
Aug 19 2014
Section 4.2.1. Corrected documentation of orderId to be a
tag-and-value pair element in CallContext object.
1.5.1
Dec 18 2014
Section 7. Inserted diagrams to illustrate flows. Reviewed,
and updated descriptions and examples to support
campaign enabled partners.
1.6
Apr 24 2015
Updated for CASS Subscription Enhancement project.
Section 7.3 and chapter 8 extended and restructured.
7.3.1 diagram made more complete; 7.3.2 diagram
added; serviceOrderNotification details extended; sections
8.4, 8.5, 8.6 added for new notifications.
1.7
July 08, 2016
Updates to section 8.3 for the serviceOrderNotification
method to add additional parameters for a mandate
(Quantity and First Charge Date) and to generate a
serviceOrderNotification for a one-off service (includes a
new TransactionId parameter).
Updates to sections 4.2.1, 7.3 and 8.3 to allow
configurable, partner processed one-off changes.
Developer Guide
2
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Table of Contents
1 Payment SOAP Overview
6
2 Authentication
6
3 Payment Methods and URI
6
3.1
URIs
7
4 Common Parameters
7
4.1
Mandatory Parameters for Authorize and Charge
7
4.2
Common Parameter Descriptions
7
4.2.1 pay:context
8
4.2.2 api:LineItem
9
4.2.3 pay:idInfo
11
5 Method Descriptions
12
5.1
authorize
12
5.1.1 authorize Request Example
12
5.1.2 authorize Request Parameters
13
5.1.3 authorize Response Example - Success
16
5.1.4 authorize Response Parameters
17
5.2
confirm
18
5.2.1 confirm Request Example
18
5.2.2 confirm Request Parameters
19
5.2.3 confirm Response Example - Success
20
5.2.4 confirm Response Parameters
20
5.3
cancel
20
5.3.1 cancel Request Example
21
5.3.2 cancel Request Parameters
21
5.3.3 cancel Response Example - Success
22
5.3.4 cancel Response Parameters
22
5.4
charge
22
5.4.1 charge Request Example
23
5.4.2 charge Request Parameters
24
5.4.3 charge Response Example - Success
26
5.4.4 charge Response Parameters
26
5.5
refund
27
5.5.1 refund Request Example
27
5.5.2 refund Request Parameters
28
Developer Guide
3
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
5.5.3 refund Response Example - Success
29
5.5.4 refund Response Parameters
30
5.6
mandate setup
30
5.6.1 mandate setup Request Example
31
5.6.2 mandateSetup Request Parameters
32
5.6.3 mandateSetup Response Examples
37
5.6.4 mandateSetup Response Parameters
38
5.7
mandateTerminate
38
5.7.1 mandateTerminate Request Example
38
5.7.2 mandateTerminate Request Parameters
39
5.7.3 mandateTerminate Response Example
39
5.7.4 mandateTerminate Response Parameters
40
6 Partner Payment API Concepts
41
7 Example Flows
44
7.1
Example Charge Flow
45
7.1.1 Charge Flow Variation with Mandate Setup
45
7.2
Example Authorization Flow
47
7.2.1 Authorization Flow Variation with Mandate Setup
48
7.3
Example CASS Ordering Flows
49
7.3.1 CASS Order Flow with Mandate Setup
49
7.3.2 CASS Order Flow with Subscription
50
7.3.3 CASS Order Flow with One-Off
51
8 Partner Payment Notifications
53
8.1
ctnChangeNotification() Method
54
8.1.1 CTN Change Notification Example and Parameters
54
8.1.2 CTN Notification Response Example
55
8.2
mandateTerminationNotification() Method
56
8.2.1 mandateTerminationNotification Example and Parameters
56
8.2.2 mandateTerminationNotification Response Example
57
8.3
serviceOrderNotification() Method
58
8.3.1 One-off scenario
58
8.3.2 Mandate scenario
59
8.3.3 Subscription scenario
59
8.3.4 Request and response parameters
59
8.3.5 Subscription Service Order Notification Examples
61
8.3.6 Mandate Service Order Notification Examples
64
8.3.7 One-off Service Order Notification Examples
66
Developer Guide
4
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.3.8 Service Order Notification Error Handling by AMP
71
8.4
terminationNotification() Method
71
8.4.1 terminationNotification Example and Parameters
71
8.4.2 terminationNotification Response Examples
73
8.5
chargeSuccessNotification() Method
74
8.5.1 chargeSuccessNotification Example and Parameters
75
8.5.2 chargeSuccessNotification Response Example
76
8.6
chargeFailureNotification() Method
77
8.6.1 chargeFailureNotification Example and Parameters
77
8.6.2 chargeFailureNotification Response Example
78
8.7
pendingAuthorizationNotification() Stub Method
79
9 Response Codes and Exceptions
81
9.1
Exception Example
81
A Refund Reason Codes
83
B Sandbox Service
84
B.1 Sandbox Service Design
84
B.2 Sandbox Scenarios
84
B.2.1 Sandbox Service and Parameter Validation
85
B.2.2 Sandbox Response Values and Structure
85
B.3 Sandbox Methods and URI
85
B.3.1 One-Off Authorize and Charge Canned Responses
86
B.3.2 Mandate Payment Authorize and Charge Canned Responses
88
B.3.3 Confirm Canned Responses
89
B.3.4 Cancel Canned Responses
90
B.3.5 Refund Canned Responses
91
B.3.6 Mandate Set Up Canned Responses
92
B.3.7 Mandate Terminate Canned Responses
93
Developer Guide
5
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
1
Payment SOAP Overview
USCC AMP Partner Payment interface allows a web application to process payments,
grant refunds and manage mandates. Chapters 3 to 7 of this guide describe the
operations, parameters and behaviour of the Payment API, including sample flow
illustrations.
USCC AMP Partner Payment Notification interface supports application callbacks from
AMP in relation to specific events. Partners need to implement the API, to receive
notifications at the pre-configured notifyURL, and in the case of storefront notification,
to respond to it. Chapter 8 describes the notifications.
In this document the words “partner” and “developer” are used interchangeably and
mean the same entity.
2
Authentication
HTTP basic authentication is required. A server side SSL certificate is also required if
HTTPS is used.
3
Payment Methods and URI
The following web-service methods are available:
● authorize - section 5.1
❖ authorize payment (whereupon the funds are reserved)
❖ return authorization code for use in further operations
❖ synchronous model only
● confirm - section 5.2
❖ confirm (capture) a payment, fully or partially
❖ take authorization code
❖ synchronous model only
● cancel - section 5.3
❖ cancel an existing authorization
❖ allow release of any reserved funds
● charge - section 5.4
❖ authorize and confirm a payment in one step
❖ return a charge code for use in further operations
● refund - section 5.5
❖ refund a payment
Developer Guide
6
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
● mandateSetup - section 5.6
❖ set up a mandate instance
● mandateTerminate - section 5.7
❖ cancel an active mandate
3.1
URIs
The URI of the resource is as follows:
!
For all requests to AMP’s Payment API, Content Encoding such as gzip and
deflate are not supported. If Content-encoding or Accept-encoding HTTP
headers are included in the request, their values must be blank.
4
Common Parameters
Most commonly used, and mandatory parameters are described in this section.
4.1
Mandatory Parameters for Authorize and
Charge
The partner must always supply the following parameters in authorize and charge
calls:
● context (CallContext object) - Comprises TagValuePairs that pass respective contextual
information, and traceId element. See section 4.2.1
● onBehalfOf (String) - Passes the name of the content provider or merchant providing the
service. Maps to the MerchantName field in the Billing Feed Transaction Record. See sections
5.1.2 and 5.4.2
● lineItem (LineItem object) - Passes details about the service or product being purchased in
Authorize and Charge payment operations. Mandatory parameters in this object are description,
grossCost, purchaseCategoryCode and quantity. See section 4.2.2
● idInfo (IdInfo object) - passes the subscriber’s CTN as the identification information. See
section 4.2.3
4.2
Common Parameter Descriptions
The Context (pay:context), LineItem (api:LineItem) and idInfo (pay:idInfo) objects
are used in most of the Payment methods, and these are described in detail. You
should be aware of their various fields, etc, before moving on to later sections.
Developer Guide
7
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
4.2.1 pay:context
The context parameter comprises the context object that includes the traceId element
which is always included as a parameter in every Payment API request call.
Table 1: pay:context Object Parameters
Parameter
Length
Description
traceId
36
The unique ID used to track the API call and correlate
with activity in the calling application.
This is a mandatory parameter and must be provided
in all operations. The TPA must provide a unique ID
for each call such as a UUID.
tagsAndValues
array
Tag and value pairs as additional parameters.
Campaign enabled partners must include the
following in mandate setup requests:
● campaignId
● shortcode
● purchaseCategoryCode
Storefront integrated partners must also include, in
addition to the three sets above:
● orderId *(<=20, as received in the Service
Order Notification)
*orderId is used only for a Mandate Setup request
which follows a Service Order Notification sent by
AMP to the partner, to notify that a service order was
made by the storefront for a subscriber. See section
5.6.2.
The value must match the Order ID received in the
notification. It will be ignored otherwise. See Chapter
8 on the details of the Service Order Notification and
the required response.
For one-off authorize call storefront integrated
partners must also include cassOrderId and
cassOrderType Tag and value pairs.
* cassOrderId and cassOrderType is used only for a
one-off authorize call request which follows a Service
Developer Guide
8
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Order Notification sent by AMP to the partner, to
notify that a service order was made by the
storefront for a subscriber.
The cassOrderId must match the Order ID received in
the notification. And cassOrderType should have
value “one-off”. It will be ignored otherwise. See
Chapter 8 on the details of the Service Order
Notification and the required response.
4.2.2 api:LineItem
The LineItem object contains the parameter values of a line item within a payment
operation request, where a line item represents a product or service.
!
Each payment call should contain only one LineItem.
A LineItem parameter is always part of the complex type pay:lineItems. For Payment
service enabler operations, the pay:lineItems object contains only one LineItem
parameter. The parameter values are as follows:
Table 2: LineItem Object Parameters
Parameter
Data
Length
Notes
Type
description
xsd:
255
This is a mandatory parameter and contains the
string
description of the product or service in this line
item. As the payment operation request only has a
single line item, this parameter must match the
payment operation request’s ‘description’
parameter.
AMP validates only that there is content in this
parameter (that it doesn’t contain blanks) but other
than this check, the content is passed as is to the
Charging Service.
This maps to USCC Billing Feed Transaction
Record’s Description field.
Developer Guide
9
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
externalId
xsd:
N/A
Enter the campaignId of the service. The value
string
matches the serviceId as passed to AMP’s
OrderServices API.
This value is mapped to USCC Billing Feed
Transaction Record's Campaign Public ID. For
partners who are not using campaigns, this can be
passed as null.
grossCost
xsd:
36
This is a mandatory parameter, and denotes the
string
gross amount of the purchase or refund cost where
the amount is inclusive of tax. The first three
characters of the string form the currency code and
must be USD. The remaining characters specify the
amount in that currency, including two digits
following the decimal point (e.g, USD3.00), and
must be a positive value or zero.
This maps to USCC Billing Feed Transaction
Record’s Transaction Amount field.
purchaseCategory
xsd:
255
This is a mandatory parameter and is the purchase
Code
string
category code of the line item. The AMP validates
the content of this parameter matches the one
defined in PSE from the Management Console. The
value must match the purchase category code of
the campaign.
This maps to USCC Billing Feed Transaction
Record’s Purchase Category field.
quantity
xsd:
1
Enter 1. This is a mandatory parameter and is the
string
number of units being purchased for this line item.
In the context of USCC service, the value must be
set to 1.
serviceId
xsd:
255
Enter the shortcode of the service.
string
This is used to identify the line item. If provided,
AMP validates the content of this parameter isn’t
empty.
This maps to USCC Billing Feed Transaction
Record’s Short Code field for campaign enabled
Developer Guide
10
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
partners. For partners who do not use campaigns,
this can be passed as null.
tax
xsd:
36
Enter zero value (USD0). This optional field is used
string
to identify the tax payable on the line item.
If provided, the AMP validates the content of this
parameter isn’t empty.
4.2.3 pay:idInfo
The idInfo parameter (TagAndValue pair) is used by AMP to identify the subscriber for
a one-time charge operation. It is mandatory to provide CTN as the idInfo in authorize
and charge payment operations and mandate setup operations.
Table 3: idInfo Object Parameters
Parameter
Length
Description
TagValuePair (key:
15
The phoneNumber address format consists of
“phoneNumber”,
1) the 'tel:' protocol identifier
value:
2) the country code preceded by '+' , e.g. +1
<valueOfTypeString>
)
3) the ten digit CTN (or MDN), e.g. tel:+15087300001
that is properly formatted.
This maps to USCC Billing Feed Transaction Record’s
Description field.
Developer Guide
11
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
5
Method Descriptions
5.1
authorize
This method authorizes a payment from a customer to the partner, resulting in funds
being reserved. The request may include one line item, which describes the item being
purchased.
The request may also include an external ID to link to a transaction in the partner
system; for example, it could be the unique transaction ID of the request. If provided,
the value must be globally unique on the AMP platform.
An authorization can be for a one-off payment, or an authorization against a previously
set up mandate. If the latter, the mandate ID needs to be specified in the call.
5.1.1 authorize Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:authorize>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>4request000001</pay:requestId>
<pay:externalTransactionId xsi:nil="true"
<pay:description>Purchase Description to be agreed with USCC</pay:description>
<pay:lineItems>
<api:LineItem>
<api:description>Purchase Description to be agreed with
USCC</api:description>
<api:externalId>CampaignId</api:externalId>
Developer Guide
12
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<api:grossCost>USD1</api:grossCost>
<api:purchaseCategoryCode>Chat</api:purchaseCategoryCode>
<api:quantity>1</api:quantity>
<api:serviceId>1234</api:serviceId>
<api:tax>USD0</api:tax>
</api:LineItem>
</pay:lineItems>
<pay:mandateId>a5476865-4967-430e-a3c9-22d2bbe199b2</pay:mandateId>
<pay:onBehalfOf>PartnerName</pay:onBehalfOf>
<pay:channel></pay:channel>
<pay:idInfo>
<api:TagValuePair>
<api:tag>phoneNumber</api:tag>
<api:value>tel:+11234567890</api:value>
</api:TagValuePair>
</pay:idInfo>
<pay:continuationTokens xsi:nil="true"
</pay:authorize>
</soapenv:Body>
</soapenv:Envelope>
5.1.2 authorize Request Parameters
Table 4: authorize - Request Parameter
Parameter
Data Type
Description
Optional
context
api:CallContext
Contextual information specific to
No
the API call. Includes mandatory
parameters for an authorize/charge
call such as billing support and
application support information. See
section 4.2.1.
For one-off authorize call storefront
integrated partners must include
Developer Guide
13
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
cassOrderId and cassOrderType Tag
and value pairs.
* cassOrderId and cassOrderType is
used only for a one-off authorize call
request which follows a Service
Order Notification sent by AMP to the
partner, to notify that a service order
was made by the storefront for a
subscriber.
The cassOrderId must match the
Order ID received in the notification.
And cassOrderType should have
value “one-off”. It will be ignored
otherwise. See Chapter 8 on the
details of the Service Order
Notification and the required
response.
apiId
xsd:string
Not used; populate with null.
Yes
apiKey
xsd:string
Not used; populate with null.
Yes
requestId
xsd:string
The ID for the request which must
Yes
be unique.
By providing the requestId
parameter, you will enable the AMP’s
idempotency functionality. This
functionality is intended to stop
partners from processing duplicate
transactions. If for some reason
partners do not receive transaction
response and wish to retry, they
should then re-use the same
requestId. (This is the only scenario
- a request retry - where the unique
requestId should be used again. If
you are sending a new transaction
request (not a retry) then there
should be a new unique requestId.)
When AMP receives a second request
with a requestId that was previously
received, it will first check all other
parameters in the request to ensure
it is truly a retry. If the parameters
Developer Guide
14
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
are not the same, an Idempotency
parameter mismatch error will be
returned.
However, if the request is
determined to be a retry, AMP will
resend the original response to the
partner. In other words, if the first
request failed, AMP will resend the
failure response. If the first request
was successful, AMP will resend the
successful response including the
transactionId.
externalTransact
xsd:string
An optional field that allows partners
Yes
ionId
to specify an external ID for the
transaction, used to associate the
transaction with information in an
external system.
Max character length 255.
If not used, populate with null. If
provided, the AMP validates that the
content of this parameter isn’t
empty before passing it as is to in
USCC Billing Feed. It maps to USCC
Billing Feed Transaction Record’s
External Reference ID field.
description
xsd:string
An optional parameter containing a
Yes
short description of the transaction.
If used in charge operation, the
value must match the same for the
description parameter in the line
item. See section 4.2.2.
Max character length 255.
If provided, the AMP validates that
the content of this parameter isn’t
empty before passing it as is to in
USCC Billing Feed.
lineItems
api:ArrayOfLine
The single line item associated with
No
Item
this transaction. See section 4.2.2.
Developer Guide
15
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
mandateId
xsd:string
For one-off payment authorization,
Yes
populate with null, as in the example
at section 5.1.1.
For mandate payment authorization,
enter the mandateId returned in the
mandateSetup response as noted in
section 5.6.4.
onBehalfOf
xsd:string
A mandatory parameter, denoting
No
the name of the merchant providing
the service and generating the
payment operation. Maps to the
MerchantName field in the Billing
Feed Transaction Record.
channel
xsd: string
Not used; populate with null.
Yes
idInfo
api:ArrayOfTagV
A mandatory parameter containing
No
aluePair
information that AMP uses to identify
the customer to be charged for a
one-time charge operation. This is
an array of tag and value pairs
where “phoneNumber” is the tag and
the customer’s phone number is the
value. See Section 4.2.3.
continuationTok
api:ArrayOfTagV
Not used; populate with null.
Yes
ens
aluePair
5.1.3 authorize Response Example - Success
<soap:Body>
<ns1:authorizeResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
Developer Guide
16
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<referralDestination xsi:nil="true"
<transactionId xmlns="http://payments.api.pplus.valista.com">35a9d24f-a800-
4f6f-afab-0e10ba0c2ed2</transactionId>
<transactionState
xmlns="http://payments.api.pplus.valista.com">AUTHORIZED</transactionState>
</ns1:out>
</ns1:authorizeResponse>
</soap:Body>
</soap:Envelope>
5.1.4 authorize Response Parameters
Table 5: authorize - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralD
Not used; AMP will populate it with null.
Yes
estination
tagValuePairs
api:ArrayOfTa
Not used; AMP will populate it with null.
Yes
gValuePair
transactionId
xsd:string
If the operation is successful, this contains
Yes
the internal transaction ID of the newly
authorized transaction.
transactionState
xsd:string
If the operation is successful, this contains
Yes
the AUTHORIZED state of the newly
authorized transaction.
TransactionState takes one of the following
values:
● AUTHORIZATION_PENDING
● AUTHORIZED
● AUTHORIZATION_FAILED
● AUTHORIZATION_DECLINED
Developer Guide
17
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
5.2
confirm
This operation confirms a previously authorized payment from a customer to the TPA.
This results in funds being captured. The default behavior is to confirm the authorized
amount in full.
The Confirm operation must identify the transaction to confirm, by the transactionId
returned in the authorize response.
5.2.1 confirm Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:confirm>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>4request000001</pay:requestId>
<pay:transactionId>818bbd3e-fe6c-4f9e-a885-
330cd7d3e741</pay:transactionId>
<pay:description>Purchase Description to be agreed with USCC</pay:description>
<pay:lineItems>
<api:LineItem>
<api:description>Purchase Description to be agreed with
USCC</api:description>
<api:externalId>CampaignId</api:externalId>
<api:grossCost>USD1</api:grossCost>
<api:purchaseCategoryCode>Chat</api:purchaseCategoryCode>
<api:quantity>1</api:quantity>
<api:serviceId>1234</api:serviceId>
<api:tax>USD0</api:tax>
</api:LineItem>
Developer Guide
18
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</pay:lineItems>
</pay:confirm>
</soapenv:Body>
</soapenv:Envelope>
5.2.2 confirm Request Parameters
Table 6: confirm - Request Parameters
Parameter
Data Type
Description
Optional
context
pay:CallCo
Contextual information specific to the API
No
ntext
call. See section 4.2.1.
apiId
xsd:string
Not used; populate with null.
Yes
apiKey
xsd:string
Not used; populate with null.
Yes
requestId
xsd:string
The ID for the request which must be unique.
Yes
By providing the requestId parameter, you
will enable AMP’s idempotency functionality.
See Table 4 requestId description for details
transactionId
xsd:string
The ID of the authorized transaction to
No
confirm; this ID would be returned in the
original authorization response.
description
xsd:string
An optional parameter containing a short
Yes
description of the transaction. If used, the
value should match the same for the
description parameter in the line item. See
section 4.2.2.
Max character length 255.
When provided, AMP validates only that
there is content in this parameter, before
passing it as is to the USCC Billing Feed.
lineItems
api:ArrayOf
The line item associated with this
No
LineItem
transaction. The grossCost needs to be equal
to or less than the original amount. See
section 4.2.2.
Developer Guide
19
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Additionally, the Confirm grossCost amount
can only be set to zero if and only if the
Authorize amount was zero.
5.2.3 confirm Response Example - Success
<soap:Body>
<ns1:confirmResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
<referralDestination xsi:nil="true" xmlns="http://payments.api.pplus.valista.com"/>
</ns1:out>
</ns1:confirmResponse>
</soap:Body>
</soap:Envelope>
5.2.4 confirm Response Parameters
Table 7: confirm - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralDes
Not used for payment service; AMP
Yes
tination
will populate it with null.
tagValuePairs
api:arrayOfTag
Not used for payment service; AMP
Yes
ValuePair
will populate it with null.
5.3
cancel
The Cancel operation cancels a previously authorized payment from a customer to the
TPA, releasing any reserved funds.
Developer Guide
20
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
5.3.1 cancel Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:cancel>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>4request000001</pay:requestId>
<pay:transactionId>390baeff-0ea6-4ba9-8060-
7be08b66c677</pay:transactionId>
</pay:cancel>
</soapenv:Body>
</soapenv:Envelope>
5.3.2 cancel Request Parameters
Table 8: cancel - request Parameters
Parameter
Data Type
Description
Optional
context
pay:CallContext
Contextual information specific to the API
No
call. In the cancel method, only traceId
parameter is required. See section 4.2.1.
apiId
xsd:string
Not used; populate with null.
Yes
apiKey
xsd:string
Not used; populate with null.
Yes
requestId
xsd:string
The ID for the request, which must be
Yes
unique.
By providing the requestId parameter,
you will enable AMP’s idempotency
Developer Guide
21
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
functionality. See Table 4 requestId
description for details.
transactionId
xsd:string
The ID of the transaction to be cancelled;
No
this ID would be was returned in the
response to the original authorization
call.
5.3.3 cancel Response Example - Success
<soap:Body>
<ns1:cancelResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
<referralDestination xsi:nil="true" xmlns="http://payments.api.pplus.valista.com"/>
</ns1:out>
</ns1:cancelResponse>
</soap:Body>
</soap:Envelope>
5.3.4 cancel Response Parameters
Table 9: cancel - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralD
Not used for payment service; AMP
Yes
estination
will populate it with null.
tagValuePairs
api:arrayOfTa
Not used for payment service; AMP
Yes
gValuePair
will populate it with null.
5.4
charge
This method authorizes a payment from a customer to the partner, resulting in funds
being reserved, and then confirms the payment in one step. The request can include only
one line item, which describes the item being purchased.
Developer Guide
22
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
A charge can be for a one-off payment, or a charge against a previously set up mandate.
If the latter, the mandate ID needs to be specified in the call.
5.4.1 charge Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:charge>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>4request000001</pay:requestId>
<pay:externalTransactionId xsi:nil="true"
<pay:description> Purchase Description to be agreed with USCC </pay:description>
<pay:lineItems>
<api:LineItem>
<api:description> Purchase Description to be agreed with USCC </api:description>
<api:externalId>CampaignId</api:externalId>
<api:grossCost>USD1</api:grossCost>
<api:purchaseCategoryCode>Chat</api:purchaseCategoryCode>
<api:quantity>1</api:quantity>
<api:serviceId>1234</api:serviceId>
<api:tax>USD0</api:tax>
</api:LineItem>
</pay:lineItems>
<pay:mandateId xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
<pay:onBehalfOf>PartnerName</pay:onBehalfOf>
<pay:channel></pay:channel>
<pay:idInfo>
<api:TagValuePair>
<api:tag>phoneNumber</api:tag>
<api:value>tel:+11111111112</api:value>
Developer Guide
23
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</api:TagValuePair>
</pay:idInfo>
<pay:continuationTokens xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
</pay:charge>
</soapenv:Body>
</soapenv:Envelope>
5.4.2 charge Request Parameters
Table 10: charge - Request Parameters
Parameter
Data
Description
Optional
Type
context
pay:Call
Contextual information specific to the API
No
Context
call. Includes mandatory parameters for a
charge operation. See section 4.2.1.
apiId
xsd:
Not used; populate with null.
Yes
string
apiKey
xsd:
Not used; populate with null.
Yes
string
requestId
xsd:
The ID for the request which must be
Yes
string
unique.
By providing the requestId parameter, you
will enable AMP’s idempotency
functionality. See Table 4 requestId
description for details.
externalTransaction
xsd:
An optional field that allows partners to
Yes
Id
string
specify an external ID for the transaction,
used to associate the transaction with
information in an external system.
Max character length 255.
If not used, populate with null. If provided,
AMP validates only that there is content in
this parameter, before passing it as is to
the USCC Billing Feed. It maps to USCC
Developer Guide
24
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Billing Feed Transaction Record’s External
Reference ID field.
description
xsd:
An optional parameter containing a short
Yes
string
description of the transaction. If used, the
value should match the same for the
description parameter in the line item. See
section 4.2.2.
Max character length 255.
When provided, AMP validates only that
there is content in this parameter, before
passing it as is to the USCC Billing Feed.
lineItems
api:Arra
The line item associated with this
No
yOfLineI
transaction. See section 4.2.2.
tem
Additionally, the Confirm grossCost
amount can only be set to zero if and only
if the Authorize amount was zero.
mandateId
xsd:
For one-off payment authorization,
Yes
string
populate with null as in the example in
section 5.4.1.
For mandate payment authorization, enter
the mandateId returned in the
mandateSetup response as noted in
section 5.6.4.
onBehalfOf
xsd:
A mandatory parameter, denoting the
No
string
name of the merchant providing the
service and generating the payment
operation. Maps to the MerchantName field
in the Billing Feed Transaction Record.
channel
xsd:
Not used; populate with null.
Yes
string
idInfo
api:Arra
A mandatory parameter containing
No
yOfTagV
information that AMP uses to identify the
aluePair
customer to be charged for a one-time
charge operation. This is an array of tag
Developer Guide
25
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
and value pairs where “phoneNumber” is
the tag and the customer’s phone number
is the value. See Section 4.2.3.
continuationTokens
api:Arra
Not used; populate with null.
Yes
yOfTagV
aluePair
5.4.3 charge Response Example - Success
<soap:Body>
<ns1:chargeResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
<referralDestination xsi:nil="true" xmlns="http://payments.api.pplus.valista.com"/>
<transactionId xmlns="http://payments.api.pplus.valista.com">23213f38-4874-42e3-
9e25-bd92ddfa34e2</transactionId>
<transactionState
xmlns="http://payments.api.pplus.valista.com">CONFIRMED</transactionState>
</ns1:out>
</ns1:chargeResponse>
</soap:Body>
</soap:Envelope>
5.4.4 charge Response Parameters
Table 11: charge - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralDes
Not used for payment service; AMP
Yes
tination
will populate it with null.
tagValuePairs
api:arrayOfTag
Not used for payment service; AMP
Yes
ValuePair
will populate it with null.
Developer Guide
26
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
transactionId
xsd:string
If the operation is successful, this
No
will contain the transaction ID of
the newly charged transaction.
transactionState
xsd:string
If the operation is successful, this
No
will contain the state of the
transaction as CONFIRMED.
5.5
refund
This method refunds a confirmed payment from the customer to the TPA. A refund is a
single-stage process. The refund call must identify the original transaction to be
refunded, where the original transaction must be for a charge operation. The refund must
include a valid reason code which matches the refund codes specified by USCC. Reason
codes are listed in Appendix A.
Only full refunds are allowed. The requested refund value must match the value in the
original charge/confirm request.
An external ID to link to a transaction in the partner system may also be included in the
request. For example, this could be the unique transaction ID of the request. If provided,
the value must be globally unique.
5.5.1 refund Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:refund>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>4request000001</pay:requestId>
<pay:transactionId>2d335075-dc4d-49ba-9c04-ebcea7aba7a7</pay:transactionId>
<pay:externalTransactionId xsi:nil="true"
Developer Guide
27
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<pay:refundReasonCode>Unknown</pay:refundReasonCode>
<pay:lineItems>
<api:LineItem>
<api:grossCost>USD0.5</api:grossCost>
<api:purchaseCategoryCode>Chat</api:purchaseCategoryCode>
</api:LineItem>
</pay:lineItems>
</pay:refund>
</soapenv:Body>
</soapenv:Envelope>
5.5.2 refund Request Parameters
Table 12: refund - Request Parameters
Parameter
Data
Description
Optional
Type
context
pay:Call
Contextual information specific to the API
No
Context
call. Only traceId parameter is used. See
section 4.2.1.
apiId
xsd:
Not used; populate with null.
Yes
string
apiKey
xsd:
Not used; populate with null.
Yes
string
requestId
xsd:
The ID for the request which must be
Yes
string
unique.
The ID for a request which must be
unique. By providing the requestId pa-
rameter, you will enable AMP’s idempo-
tency functionality. See Table 4 requestId
description for details.
transactionId
xsd:
The ID of the transaction to be refunded.
No
string
externalTransactio
xsd:
An optional field that allows partners to
No
nId
string
specify an external ID for the transaction,
Developer Guide
28
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
used to associate the transaction with
information in an external system.
Max character length 255.
If not used, populate with null. If
provided, the AMP validates that the
content of this parameter isn’t empty
before passing it as is to in USCC Billing
Feed. It maps to USCC Billing Feed
Transaction Record’s External Reference
ID field.
refundReasonCode
xsd:
A code specifying the reason for the
No
string
refund, selected from a specified list,
managed by USCC. The value maps to
USCC Billing Feed Transaction Record’s
Reason Code field.
Max character length is 255.
lineItems
api:Arra
For a partial refund, the line item
No
yOfLineI
associated with the part being refunded is
tem
provided. Only the value of grossAmount
needs to be specified, which must be less
than the amount in the confirmed
transaction. See section 4.2.2.
For a full refund, this parameter is
provided as an empty tag, with a start
and end tag only.
5.5.3 refund Response Example - Success
<soap:Body>
<ns1:refundResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
<referralDestination xsi:nil="true" xmlns="http://payments.api.pplus.valista.com"/>
<transactionId xmlns="http://payments.api.pplus.valista.com">654e73f5-d5da-45de-
9180-c5e6e93b9b33</transactionId>
Developer Guide
29
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<transactionState
xmlns="http://payments.api.pplus.valista.com">CONFIRMED</transactionState>
</ns1:out>
</ns1:refundResponse>
</soap:Body>
</soap:Envelope>
5.5.4 refund Response Parameters
Table 13: refund - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralDe
Not used; AMP will populate it with
Yes
stination
null.
tagValuePairs
api:arrayOfTag
Not used; AMP will populate it with
Yes
ValuePair
null.
transactionId
xsd:string
If the operation is successful, this
No
will contain the transaction ID of the
newly refunded transaction.
transactionState
xsd:string
If the operation is successful, this
No
will contain the state of the newly
refunded transaction as
CONFIRMED.
5.6
mandate setup
This operation creates a mandate, pre-authorizing the TPA to make multiple charges to
the customer. Within the mandate, each charge must still be authorized and confirmed.
Note that although authorization in a mandated transaction will not require user
interaction, authorization can fail for other valid business reasons. For example, if the
payment account specified for the mandate contains no funds at the time a recurring
charge is attempted.
The mandateSetup() call allows a very wide range of mandate settings and limits to be
applied, which are described below. However for U.S. Cellular mandates, the following
guidelines should be followed:
a. expiryDate is optional
b. No maxTotalExpenditure needs to be provided
Developer Guide
30
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
c. maxSingleCharge should equal the maximum price point of the relevant
campaign
d. maxExpenditurePerPeriod should equal the maximum price point of the relevant
campaign, allowing one charge per month
e. maxChargeCount should be set to '0'
f. merchantPeriod should be '1 MONTH'
g. For aggregators, the onBehalfOf parameter should contain the name of the
content provider
5.6.1 mandate setup Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:mandateSetup>
<pay:context>
<api:tagValuePairs>
<api:TagValuePair>
<api:tag>campaignId</api:tag>
<api:value>SubscriptionCampaignId</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>shortcode</api:tag>
<api:value>1234</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>purchaseCategoryCode</api:tag>
<api:value>Chat</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>orderId</api:tag>
<api:value>12345678909876543210</api:value>
</api:TagValuePair>
</api:tagValuePairs>
<api:traceId></api:traceId>
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
Developer Guide
31
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<pay:requestId>req0000000123456791</pay:requestId>
<pay:description> Purchase Description to be agreed with USCC </pay:description>
<pay:expiryDate xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
<pay:maxTotalExpenditure>USD100000</pay:maxTotalExpenditure>
<pay:minSingleCharge>USD2.99</pay:minSingleCharge>
<pay:maxSingleCharge>USD2.99</pay:maxSingleCharge>
<pay:maxExpenditurePerPeriod>USD2.99</pay:maxExpenditurePerPeriod>
<pay:merchantPeriod>
<api:length>1</api:length>
<api:unit>MONTH</api:unit>
</pay:merchantPeriod>
<pay:maxChargeCount>0</pay:maxChargeCount>
<pay:externalMandateId></pay:externalMandateId>
<pay:onBehalfOf>PartnerName</pay:onBehalfOf>
<pay:channel></pay:channel>
<pay:idInfo>
<api:TagValuePair>
<api:tag>phoneNumber</api:tag>
<api:value>tel:+11111111222</api:value>
</api:TagValuePair>
</pay:idInfo>
<pay:continuationTokens xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
</pay:mandateSetup>
</soapenv:Body>
</soapenv:Envelope>
5.6.2 mandateSetup Request Parameters
Table 14: mandateSetup - Request Parameters
Parameter
Data
Description
Optional
Type
context
pay:CallC
Contextual information specific to the API
No
ontext
call. traceId may be passed in addition to
tagAndValue pairs.
Developer Guide
32
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Campaign enabled partners must include
the following in mandate setup requests:
● campaignId
● shortcode
● purchaseCategoryCode
Storefront integrated partners must also
include in mandate setup requests, in
addition to the three sets above:
● orderId *(<=20, as received in the
Service Order Notification)
*orderId is used only for a Mandate Setup
request which follows a Service Order
Notification sent by AMP to the partner, to
notify that a service order was made by
the storefront for a subscriber.
The value must match the Order ID
received in the notification. It will be
ignored otherwise. See Chapter 8 on the
details of the Service Order Notification
and the required response.
apiId
xsd:string
Not used; populate with null.
Yes
apiKey
xsd:string
Not used; populate with null.
Yes
requestId
xsd:string
The ID for the request which must be
Yes
unique.
By providing the requestId parameter, you
will enable AMP’s idempotency
functionality. See Table 4 requestId
description for details.
description
xsd:string
A description of the mandate. As the
Yes
Charge operation against the mandate will
have the description of the purchase, this
is an optional field.
If used, the value should match the same
for the description parameter in the line
Developer Guide
33
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
item. See section 4.2.2. Max character
length 255.
If not used, populate with an empty tag
with a start and an end tag.
AMP does not validate the content of this
parameter.
expiryDate
xsd:dateTi
The date and time at which the mandate
Yes
me
becomes inactive. If not specified, the
mandate remains valid for an indefinite
period and the field is populated with null.
The date and time must be in the time
zone specified by USCC, which may not
necessarily be your own time zone.
maxTotalExpend
xsd:string
The total amount that may be charged
Yes
iture
against this mandate during its entire
lifetime. The mandate will become inactive
once this amount is exceeded.
The first three characters of the string
must be the currency code USD, and the
remaining characters in decimal format
with two digits following the decimal to
denote the value (e.g. USD3.00). Positive
values and zero are permitted.
maxSingleCharg
xsd:string
The maximum amount permitted for any
Yes
e
single charge against this mandate.
The first three characters of the string
must be the currency code USD, and the
remaining characters in decimal format
with two digits following the decimal to
denote the value (e.g. USD3.00). Positive
values and zero are permitted.
minSingleCharg
xsd:string
The minimum amount permitted for any
Yes
e
single charge against this mandate.
The first three characters of the string
must be the currency code USD, and the
Developer Guide
34
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
remaining characters in decimal format
with two digits following the decimal to
denote the value (e.g. USD3.00). Positive
values and zero are permitted.
maxExpenditure
xsd:string
The maximum amount that can be charged
No
PerPeriod
to this mandate in a specified period. If
this parameter is specified, the
merchantPeriod parameter must also be
specified.
The first three characters of the string
must be the currency code USD, and the
remaining characters in decimal format
with two digits following the decimal to
denote the value (e.g. USD3.00). Positive
values and zero are permitted.
merchantPeriod
api:Period
The period for which the
Dependent
maxExpenditurePerPeriod parameter
on param
applies.
above.
The parameter is a complex type
containing the unit and length, where the
unit is a string containing one of (MINUTE,
HOUR, DAY, WEEK, MONTH, YEAR) and the
length is an integer representing the
number of units. If
maxExpenditurePerPeriod is set, then this
parameter is mandatory.
Note: When 1 MONTH is specified, the
billable date will occur at one calendar
month intervals. However, if a month does
not contain the day of the start date (29 or
30 or 31), the billable date is reset to the
last day of the month, for that month only.
The billable time is always as at the start
time.
For example, a mandate with 1 MONTH
period starting on 31 January 2015 at 8:00
A.M. would be billed on 28 February 2015
Developer Guide
35
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
at 8:00 A.M., then on 31 March at 8:00
A.M., 30 April, 31 May ... etc.
maxChargeCou
xsd:long
The maximum number of charges that may
Yes
nt
be made against the mandate. When this
amount is reached, the mandate ceases to
be active. Specify ‘0’ to allow an unlimited
number of charges against the mandate.
externalMandat
xsd:string
An optional external ID for the mandate.
Yes
eId
The payment service does not require this
ID and if not used, populate with null. It is
used to associate this mandate with
information in an external system.
onBehalfOf
xsd:string
The name of the content provider or the
Yes
merchant providing the service and
generating the payment operation. See
section 5.1.2.
As the Charge operation against the
mandate will have this parameter to be
used for the purchase, this field is optional,
and if not used, will be populated with null.
AMP does not validate the content of this
parameter.
channel
xsd:string
Not used; populate with null.
Yes
idInfo
api:Array
A mandatory parameter containing
No
OfTagValu
information that AMP uses to identify the
ePair
customer to be charged for a one-time
charge operation. This is an array of tag
and value pairs where “phoneNumber” is
the tag and the customer’s phone number
is the value. See Section 4.2.3.
continuationTok
api:Array
Not used; populate with null.
Yes
ens
OfTagValu
ePair
Developer Guide
36
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
5.6.3 mandateSetup Response Examples
Mandate setup Success
<soap:Body>
<ns1:mandateSetupResponse xmlns:ns1="http://payments.api.pplus.valista.com">
<ns1:out>
<mandateId xmlns="http://payments.api.pplus.valista.com">21d2a88a-6c9b-428d-83cc-
bdf2d23defa6</mandateId>
<referralDestination xsi:nil="true" xmlns="http://payments.api.pplus.valista.com"/>
</ns1:out>
</ns1:mandateSetupResponse>
</soap:Body>
</soap:Envelope>
Mandate setup Failure
Merchant Payment Exception is returned, with associated fault fields:
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Amount exceeds SpendLimit [IH] reserved amount!</faultstring>
<detail>
<MerchantPaymentException xmlns="http://payments.api.pplus.valista.com">
<errorCode>AMOUNT_EXCEEDS_SPENDLIMIT_CEILING_AMOUNT</errorCode>
<message>Amount exceeds SpendLimit [IH] reserved amount!</message>
<recoverable>false</recoverable>
<transactionId ns1:nil="true"
</MerchantPaymentException>
</detail>
Developer Guide
37
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</soap:Fault>
</soap:Body>
</soap:Envelope>
5.6.4 mandateSetup Response Parameters
The following table lists mandateSetup specific parameters only.
Table 15: mandateSetup - Response Parameters
Parameter
Data Type
Description
Optional
referralDestination
api:ReferralDe
Not used; AMP will populate it with
Yes
stination
null.
tagValuePairs
api:arrayOfTag
Not used; AMP will populate it with
Yes
ValuePair
null.
mandateId
api:arrayOfTag
If the operation is successful, this
No
ValuePair
will contain the internal mandate ID
of the newly created mandate.
5.7
mandateTerminate
This method explicitly terminate a mandate, making it inactive. All subsequent
authorizations using the mandate will fail. Existing authorizations may be confirmed or
cancelled as normal.
Partners can receive notifications of mandate termination, at their notifyURL. See section
8.2
5.7.1 mandateTerminate Request Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<pay:mandateTerminate>
<pay:context>
<api:tagValuePairs/>
<api:traceId></api:traceId>
Developer Guide
38
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</pay:context>
<pay:apiId></pay:apiId>
<pay:apiKey></pay:apiKey>
<pay:requestId>req0000000123456791</pay:requestId>
<pay:mandateId>44e5ed2a-40b3-45f5-9287-3f2e52daca43</pay:mandateId>
</pay:mandateTerminate>
</soapenv:Body>
</soapenv:Envelope>
5.7.2 mandateTerminate Request Parameters
Table 16: mandateTerminate - Request Parameters
Parameter
Data Type
Description
Optional
context
pay:CallCo
Contextual information specific to the API call.
No
ntext
Only traceId parameter is used in this method.
See section 4.2.1.
apiId
xsd:string
Not used; populate with null.
Yes
apiKey
xsd:string
Not used; populate with null.
Yes
requestId
xsd:string
The ID for the request which must be unique.
Yes
By providing the requestId parameter, you will
enable AMP’s idempotency functionality. See
Table 4 requestId description for details.
mandateId
xsd:string
The ID of the mandate to be terminated. This
No
ID would be returned in the original mandate
setup response.
5.7.3 mandateTerminate Response Example
<soap:Body>
<ns2:mandateTerminateResponse>
<ns2:out>
Developer Guide
39
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<ns3:referralDestination xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
<ns3:tagValuePairs xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"/>
</ns2:out>
</ns2:mandateTerminateResponse>
</soap:Body>
</soap:Envelope>
5.7.4 mandateTerminate Response Parameters
Table 17: mandateTerminate - Response Parameters
Parameter
Type
Description
Optional
referralDestination
api:ReferralDesti
Not used for payment service;
Yes
nation
AMP will populate it with null.
tagValuePairs
api:arrayOfTagVa
Not used for payment service;
Yes
luePair
AMP will populate it with null.
Developer Guide
40
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
6
Partner Payment API Concepts
This section contains descriptions of basic concepts and entities of the Payment API. They
are described in generic terms.
Customers
Customer is the term used in AMP for an end-user signed up to an ISP or service provider
enabled to purchase content. The medium of interaction between the consumer and the
system is implementation-dependent; it could be via WAP on a cell phone or via HTTP
using a web browser.
Partners
Partner is the term used for a party involved in selling content who has a financial
relationship with an operator implementing AMP. A partner may either be a content
provider or an aggregator.
● A content provider is an entity who produces content (digital or otherwise) which they want to
sell to the operator's consumers. Sometimes referred to as a merchant. A content provider may
have a direct partner relationship with the operator hosting AMP, or they may have an indirect
relationship via an aggregator.
● An aggregator is an entity which has a relationship with multiple content partners and
operators and acts as an intermediary between them. Aggregators enable content providers to sell
their goods through multiple operators without the overhead of an individual relationship with each.
Account Holders
An account holder is any user, such as a consumer or a partner, who may be involved in
transactions. As well as storing personal details such as their contact details and external
ID (such as a CTN or email address), the account holder is linked to one or more
payment accounts. Account holders have the following state model:
Figure 1: Account Holder State Model
Developer Guide
41
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
The state of an account holder, combined with the state of their particular payment
account, determines which transaction operations (such as authorizations and
confirmations) the payment account can be involved in.
Payment Accounts
A payment account is a representation of a real world financial instrument. Each account
has a reference to the defining account type together with the instance data that
uniquely identifies that account. Credit cards, stored value, prepay billing are all
examples of payment account types that would enable consumers to have instances of
those types and exchange money. An account holder (such as a consumer or a contents
provider) can have multiple payment accounts and use them to sell and purchase access
to services or products, for example, using a separate accounts for purchase, refund,
commission, tax, etc. Whenever a payment account is used in a transaction, AMP
contacts an external system (via a payment gateway) and delegates the call to that
system. This is an essential integration point within the overall system. Payment
gateways provide access to external payment networks and systems enabling the user's
payment account data to be validated and processed.
As in the real world, transactions have a number of constraints:
● Access to the account must be protected to prevent fraudulent use
● Access to the account must be authorized to enable non-repudiation
● Accounts must have sufficient funds available for any given transaction
Payment accounts have the following state model:
Figure 2: Payment Account State Model
Line Items
A line item describes a single product or service purchased from a partner, as part of a
transaction. A transaction can consist of 1 or more line items; all line items in a
transaction must use the same currency. When multiples of the same product or service
are purchased, a single line item instance can be used, with the quantity field set to the
total number purchased. The line item may also be associated with a purchase category
code.
Developer Guide
42
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Refunds
Both operators and partners can perform refunds of customer transactions. Partners can
perform refunds through either the web-based Partner Self-Care Application, or via the
Partner Payment API.
Mandates
For regular payments from a consumer to a partner, the customer would normally be
required to authorize each individual payment. However, mandates provide the ability for
a customer to allow a partner to request multiple payments, without requiring the
customer's explicit authorization for each payment.
For example, consider a customer who wants to buy ringtones regularly (say, once a
week) from a particular partner. They could pay the $5 for each ringtone individually, but
in order to avoid this inconvenience, they could allow a mandate to be created which
enabled the partner to levy up to $20 per month from the customer.
A mandate may have one or more optional restrictions associated with it:
Table 18: Mandate Restrictions
Restrictions
Description
Expiry Date
The date on which the mandate becomes
inactive; if absent, the mandate has no upper
time period.
Total Spending Limit
The total amount which may be charged to the
mandate; if absent, the mandate has no upper
charge limit.
Maximum Transaction Amount
The maximum amount that can be spent in a
single transaction using the mandate; if absent,
the mandate has no charge limit.
Minimum Transaction Amount
The minimum amount that can be spent in a
single transaction using the mandate; if absent,
the mandate has no minimum limit.
Maximum Charge Count
The maximum number charges that can be made
using the mandate before it ceases to be
operable. A value of 0 implies that there is no
limit to the number of charges.
Developer Guide
43
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Per Period Spending Limit
The maximum amount that may be charged to
the mandate in a given period. If specified, then
the period must also be specified.
Note:
This total refers to gross expenditure, inclusive of
any applicable taxes.
Purchase Categories
Purchase categories are codes used to categorize line items purchased as part of a
payment transaction. For example, a line item could be categorized as a game, a video
download or a ringtone.
AMP can be configured by the operator to perform purchase category filtering; only
transactions whose line items all have an associated valid purchase category code will be
processed. If a transaction has a null or invalid purchase category code for one or more
of its line items, then an exception is generated.
Valid purchase category codes should be obtained from the operator.
Subscriptions
A subscription is a payment model for the purchase of a service or product, agreed
between the subscriber and the payment processor. It is set up with the first charge date
with subsequent recurring charges taking place at regular intervals. Currently CASS
provides a subscription service for AMP campaign purchases, using Purchase Category
Code, Bill Description. It is effective for both Postpaid and Prepaid subscribers. For yearly
subscriptions, AMP reserves funds monthly for 1/12 of the amount, and charges annually.
A subscription is transferred seamlessly when the subscriber’s MDN changes, unless the
Partner has elected not to do so.
7
Example Flows
This section contains selected example payment flows that demonstrate how the partner
and the Payment SOAP interface interact.
Note: The flows are simplified for the purpose of developer integrators, and described in
generic terms. Internal communications between server-side components are deliberately
excluded.
The following flows are provided:
● charge flow - below
❖ charge flow variation with mandate setup - section 7.1.1
Developer Guide
44
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
● authorization and confirm flow - section 7.2
❖ authorization and confirm flow variation with mandate setup - section 7.2.1
● USCC Storefront order flows
❖ - with mandate setup - section 7.3.1
❖ - with subscription setup - section 7.3.2
7.1
Example Charge Flow
The following describes a simple charge() call.
A charge can be used instead of a two-step authorize() and confirmation() transaction
(see below) when the developer, for example, is not delivering any content or when the
delivery of content is not based on the confirmation of payment.
1 The customer selects the developer's service or product.
2 The developer site makes charge() call to the operator.
3 A success response is returned to the developer site.
4 The developer site informs the customer that the purchase was successful.
7.1.1 Charge Flow Variation with Mandate Setup
The following diagram describes a charge() call preceded by a mandate setup:
Developer Guide
45
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
1 The customer selects the developer's service or product.
2 The developer agrees to set up a mandate for the customer.
3 The developer site makes a mandateSetup() call to the operator.
4 A success response is returned to the developer site, with the ID for the newly
created mandate.
5 The developer site makes a charge() call to the operator, using the mandate ID.
6 A success response is returned to the developer site.
7 The developer site informs the customer that the purchase was successful.
The developer site can now make further monthly recurring charges to operator without
the need for the subscriber to initiate the request.
Developer Guide
46
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
7.2
Example Authorization Flow
The following describes a customer purchase using authorize() and confirm() calls.
A developer would normally use the two-step authorize()/confirm() transaction, rather
than a charge() transaction, when they are delivering content to the customer and want
to ensure that the content is delivered before the payment is confirmed.
1 The customer selects the developer's service or product.
2 The developer site makes an authorize() request and submits it to the operator.
3 The operator returns an authorization response to the developer site.
4 The developer sends a confirm() request to the operator.
Note: At this point, the developer could alternatively send a cancel request if required.
5 The operator returns a success confirmation response to the developer site.
6 The developer site can inform the customer that the purchase was successful.
Developer Guide
47
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
7.2.1 Authorization Flow Variation with Mandate Setup
The following diagram describes an authorize and confirm flow preceded by a mandate
setup:
1 The customer selects the developer's service or product.
2 The developer agrees to set up a mandate for the customer.
3 The developer site makes a mandateSetup() call to the operator.
4 A success response is returned to the developer site, with the ID for the newly
created mandate.
5 The developer site makes an authorize() request to the operator, using the mandate
ID.
6 The operator returns an authorization response to the developer site.
7 The developer sends a confirm() request to the operator.
Note: At this point, the developer could alternatively send a cancel request if required.
8 The operator returns a success confirmation response to the developer site.
The developer site can inform the customer that the purchase was successful.
Developer Guide
48
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
The developer site can now make further monthly recurring charges to operator without the need
for the subscriber to initiate the request.
7.3
Example CASS Ordering Flows
The following diagrams outline the order flows that involves CASS, the USCC Storefront,
in a successful scenario for
 a service order involving a mandate setup - below
 a service order with a subscription - section 7.3.2
 a service order with a one-off - section 7.3.3
7.3.1 CASS Order Flow with Mandate Setup
1. Order is placed on USCC Storefront by the USCC Rep on behalf of the customer.
2. USCC Storefront sends an OrderServices request to AMP.
3. AMP sends a ServiceOrderNotification to the developer site. The notification
contains its Order ID. The Partner checks that the details are correct.
4. The developer site makes a mandateSetup() call to the operator, quoting the
Order ID included in the notification received.
5. A success response is returned to the developer site, with the ID for the newly
created mandate.
6. The Partner sends a ServiceOrderNotification response to AMP including the
Service ID (campaign ID), Status, and Mandate ID (if mandate setup is
successful).
Developer Guide
49
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
7. AMP responds to USCC Storefront including the Order Status, and Mandate ID for
a successful order, or an error message for a failed order.
8. If configured for the particular service, AMP sends confirmation of the service
order by email/SMS to the customer, with a link to sign up to the USCC Portal.
9. The developer makes a charge() call to the operator, using the mandate ID.
10. A success response is returned to the developer site.
11. The customer is able to consume the product from the developer site.
7.3.2 CASS Order Flow with Subscription
1. Order is placed on USCC Storefront by the USCC Rep on behalf of the customer.
2. USCC Storefront sends an OrderServices request to AMP, including the request to
create a subscription for a subscriber for a particular service.
3. AMP creates the subscription internally.
4. AMP sends a ServiceOrderNotification to the Partner site. The notification contains
its Order ID. The Partner checks that the details are correct and proceeds to
activate the desired service for the specified subscriber.
5. The Partner sends a ServiceOrderNotification response to AMP before its timeout
interval, indicating that the service addition was SUCCESS or FAILURE.
6. AMP sends the OrderServices response to USCC Storefront.
7. If configured for the particular service, AMP sends confirmation of the service
order by email/SMS to the customer, with a link to sign up to the USCC Portal.
(Note: depending on the service configuration, step 8 (charge processing) may
come before this step.)
8. AMP internally processes the charge.
9. AMP sends chargeSuccessNotification or chargeFailureNotification to the Partner.
Developer Guide
50
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
10. The customer is able to consume the product from the developer site.
11. AMP repeats steps 8 and 9 each month.
7.3.3 CASS Order Flow with One-Off
7.3.3.1
CASS order flow with AMP processed One-off
1. Order is placed on USCC Storefront by the USCC Rep on behalf of the customer.
2. USCC Storefront sends an OrderServices request to AMP, including the request to
create a one-off for a subscriber for a particular service.
3. AMP creates the one-off internally (AMP Processed one-off set to true in partner
configuration).
4. AMP sends a ServiceOrderNotification to the Partner site. The notification contains
its Order ID, Service ID and Transaction ID. The Partner checks that the details
are correct and proceeds to activate the desired service for the specified
subscriber.
5. The Partner sends a ServiceOrderNotification response to AMP before its timeout
interval, indicating that the service addition was SUCCESS or FAILURE.
6. AMP sends the OrderServices response to USCC Storefront.
7. If configured for the particular service, AMP sends confirmation of the service
order by email/SMS to the customer, with a link to sign up to the USCC Portal.
8. The customer is able to consume the product from the developer site.
Developer Guide
51
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
7.3.3.2
CASS order flow with Partner processed One-off
1. Order is placed on USCC Storefront by the USCC Rep on behalf of the customer.
2. USCC Storefront sends an OrderServices request to AMP, including the request to
create a one-off for a subscriber for a particular service.
3. AMP sends a ServiceOrderNotification to the Partner site. The notification contains
its Order ID, Service ID.
4. The Partner sends a authorize call to AMP.
5. AMP sends authorize success response.
6. The Partner sends a ServiceOrderNotification response to AMP before its timeout
interval, indicating that the service addition was SUCCESS or FAILURE.
7. If ServiceOrderNotification is success AMP sends OrderServices success response.
8. If configured for the particular service, AMP sends confirmation of the service
order by email/SMS to the customer, with a link to sign up to the USCC Portal.
9. The Partner sends a confirm call to AMP. (This should send after successful
ServiceOrderNotification)
10. AMP sends confirm success response.
11. The customer is able to consume the product from the developer site.
Developer Guide
52
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8
Partner Payment Notifications
This API must be implemented and deployed by the partner, using one of the two wsdl’s
provided. This API is used by the USCC to notify its partners for specific events, as
summarized below.
Table 19: Partner Payment Notifications
usage\wsdl
PartnerNotificationListener.
SubscriptionNotificatio
section
wsdl
nListener.wsdl
CTN change
ctnChangeNotification
8.1
mandate
mandateTerminationNotification
8.2
CASS service
serviceOrderNotification
8.3
order
subscription
terminationNotification
8.4
subscription
chargeSuccessNotification
8.5
subscription
chargeFailureNotification
8.6
- (not used)
pendingAuthorizationNotification
8.7
To receive notifications, partners must:
1 Implement and deploy the web services defined in the wsdl’s as shown in the table
above. The same endpoints may be used for both wsdl’s.
Ignore the pendingAuthorizationNotification() method in the
PartnerNotificationListener.wsdl and keep the implementation of this method
empty. This notification is not applicable to U.S. Cellular partners.
2 Inform USCC of the Partner Notification SOAP service URL.
!
Important: it is the responsibility of the partner to:
●
validate the input parameters
●
handle the notification
●
if necessary, send back the appropriate error code so that AMP can decide
how to proceed
Developer Guide
53
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.1
ctnChangeNotification() Method
The ctnChangeNotification method is used by USCC to notify its partners that a particular
subscriber has changed their phone number, if that subscriber has active mandates with
the partner, with or without subscriptions. A partner may elect not to transfer any
existing mandates or subscriptions to the new CTN. CTN change notifications are
received from USCC by AMP and are sent periodically to the relevant partners.
8.1.1 CTN Change Notification Example and Parameters
<soap:Body>
<ns1:ctnChangeNotification
<ns1:traceId>1387295986628</ns1:traceId>
<ns1:tagsAndValues>
<ns1:string>externalMandateId</ns1:string>
<ns1:string>1234567890987654323</ns1:string>
</ns1:tagsAndValues>
<ns1:ctn>1111111111</ns1:ctn>
<ns1:newCtn>1111111113</ns1:newCtn>
</ns1:ctnChangeNotification>
</soap:Body>
</soap:Envelope>
Table 20: CTN Change Notification Parameters
Parameter
Description
traceID
Used for testing purposes; partners can ignore this value.
tagsAndValues
An array of the externalMandateId of active mandates belonging
to the content providers of an aggregator.
ctn
The current CTN of the subscriber.
Developer Guide
54
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
newCtn
The new CTN which should be used to replace the current CTN.
AMP maintains a queue of notifications to send to partners. Batches of notifications are
sent to partners on a defined schedule.
8.1.2 CTN Notification Response Example
When the partner successfully processes a notification, they should respond with the
following.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:ctnChangeNotificationResponse/>
</soapenv:Body>
</soapenv:Envelope>
PartnerNotificationException Error Codes
The partner should return a PartnerNotificationException if the notification cannot be
processed successfully. The following table lists the error codes that a partner may
embed in the PartnerNotificationException and how AMP will handle the error.
Table 21: CTN Change Notification Error Codes
Error Code
AMP Behavior
TRANSIENT_ERROR
The notification will be resent after a configured back-
off delay, a configured number of times.
UNKNOWN_ERROR
The notification will not be re-sent in this batch but
will remain in the queue to be re-sent in a later batch.
Note that new notifications have a higher priority than
previously sent notifications.
UNEXPECTED_NOTIFICATION
The notification will be deleted from the queue and
will not be retried.
No exception will signify success and AMP will delete the notification.
Developer Guide
55
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.2
mandateTerminationNotification() Method
The mandateTerminationNotification() method is called to notify the partner when a
mandate has been terminated.
8.2.1 mandateTerminationNotification Example and
Parameters
<soap:Body>
<ns1:mandateTerminationNotification
<ns1:in0>c967474c-db3f-4e1f-abf5-6a4f57c6e5f5</ns1:in0>
<ns1:in1>mandate termination notification</ns1:in1>
<ns1:in2>
<ns2:TagValuePair
<tag xmlns="http://api.pplus.valista.com">externalMandateId</tag>
<value xmlns="http://api.pplus.valista.com">1234567890987654323</value>
</ns2:TagValuePair>
</ns1:in2>
</ns1:mandateTerminationNotification>
</soap:Body>
</soap:Envelope>
The method takes the following parameters:
Table 22: Mandate Termination Notification Parameters
Parameters
Description
mandateId
The ID of the terminated mandate.
description
An optional description for the notification.
tagValues
The externalMandateID passed by the Aggregator in the Mandate
setup call.
Developer Guide
56
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.2.2 mandateTerminationNotification Response Example
When the partner successfully processes a notification, they should respond with the
following:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:mandateTerminationNotificationResponse/>
</soapenv:Body>
</soapenv:Envelope>
8.2.2.1
PartnerNotificationException Error Codes
The partner should return a PartnerNotificationException if the notification cannot be
processed successfully. The following table lists the error codes that a partner may
embed in the PartnerNotificationException and how AMP will handle the error. A Message
parameter containing the description of the error must also be returned.
Table 23: Mandate Termination Notification Error Codes
Error Code
AMP Behavior
TRANSIENT_ERROR
The connector will retry sending the notification for a
configurable number of times, before allowing the
agent to retry in the manner described for
UNKNOWN_ERROR below.
UNKNOWN_MANDATE_ID
Indicates that the listener did not recognize the
mandate ID in the notification and therefore cannot
process the notification. AMP regards this as a
permanent failure; the notification is dequeued and
discarded.
UNEXPECTED_NOTIFICATION
Indicates that the listener did not recognize the
notification and therefore cannot process the
notification. AMP regards this as a permanent failure;
the notification is dequeued and discarded.
UNKNOWN_ERROR
The notification will be kept and the agent will retry
sending it for a configurable number of times. The
Developer Guide
57
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
priority of the notification will decrease with each retry,
so that newer notifications will have higher priority.
No exception will signify success and AMP will delete the notification.
8.3
serviceOrderNotification() Method
The serviceOrderNotification() method is called to notify the partner when a service has
been ordered by the storefront for a subscriber, with a one-off, mandate or subscription.
If there are multiple services in a service order, a separate notification is sent for each
service.
Example notifications are provided in sub-sections.
!
The partner is required to respond to this notification. Receiving the
notification is mandatory for services with mandates; optional for services
with one-offs and subscriptions.
8.3.1 One-off scenario
There are two scenarios for one-off CASS orders. AMP process charge and partner
process charge.
For AMP process charge scenario one-off charge process will not be impacted based on
this notification success or failure. Partners can neglect this notification if they want.
For partner process one-off, when partners receive this notification in relation to a one-
off service type, they must:
1. Setup one-off by making authorize call, using order id. partners must also include
following tag and value pairs cassOrderId = order id given with SON and
cassOrderType=”one-off”.
2. On receiving a authorize response, partner should respond to the SON as follows:
a. If the authorize is successful, include the Service Id, Status and transaction
ID received in the successful response.
b. If the setup is a failure, include the Service Id and Status and the message
received in the failure response.
3. After sending SON response successfully partner should send confirmation
request. It is recommended to wait 3 seconds before sending confirm request
following the successful SON response.
Developer Guide
58
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.3.2 Mandate scenario
When partners receive this notification in relation to a mandate service type, they must:
1 Setup a mandate by making the mandateSetup call, using the Order ID received in
the notification.
2 On receiving a mandate setup, respond to the notification:
❖ If the setup is successful, include the Service Id, Status and Mandate Id received in the
successful response, within the timeout period, and before the first charge is made against
the mandate. The default timeout is 1 second.
❖ If the setup is a failure, include the Service Id and Status and the message received in the
failure response.
3
“First Charge Date” indicates when will be the first charge created.
8.3.3 Subscription scenario
When partners receive this notification in relation to a subscription service type, they
must respond to the notification with the statusInfo as Success or Failure, depending on
whether they allow such a service for the subscriber.
8.3.4 Request and response parameters
The method takes the following parameters:
Table 24: Service Order Notification Parameters
Parameters
Description
MDN
The subscriber’s phone number. 10 digits.
Order ID
The unique ID of the service order made by the storefront.
String <= 20 characters.
Service ID
The campaignId, for campaign enabled partners.
Subscription ID /
[an Extensible Parameter] Required for one-offs and
Transaction ID
subscriptions, and mandatory. The Transaction ID is for
one-offs and the Subscription ID for subscriptions. String.
First Charge Date
[an Extensible Parameter] Required only for mandates and
subscriptions, and mandatory. The date passed in the order
request. If none, set to today’s date + number of First
Charge Delay days as set in the campaign. This should be
Developer Guide
59
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
the date on which the first charge of the ordered mandate
is initiated. Date (MM/DD/YYYY HH:mm:ss)
Quantity
[an Extensible Parameter] Required only for mandates and
subscriptions, and mandatory. The quantity ordered. If
none, set to the Quantity set in the campaign; if Quantity is
empty in the campaign, it will be empty.
Extensible Parameters
[Option] List of additional data parameters associated with
the service in Tag-Value pairs, if provided by the storefront
as part of the Service Order sent to AMP.
For one-offs, the following are mandatory: Transaction ID,
and Quantity.
For mandates, the following are mandatory: First Charge
Date and Quantity.
For subscriptions, the following are mandatory: Subscription
ID, First Charge Date and Quantity.
In the response to a ServiceOrderNotification for a mandate, the partner must add the ID
of the mandate created, and its status.
Table 25: Service Order Notification - Response Parameters
Parameters
Description
Service ID
The service ID. String, as received in the Notification
Mandate ID
[Required only for mandates, and optional] The mandate ID
received in a mandate setup response. String.
For a mandate service order, mandatory for successful mandate
setups; if no value is present, the response will indicate that the
setup was a failure. The Status parameter must then be set as
Failure.
Transaction ID
[Required only for partner processed one-off and optional] The
Transaction ID received in a authorize response. String.
For a partner processed one-off service order, mandatory for
successful authorization; if no value is present, the response will
indicate that the setup was a failure. The Status parameter must
then be set as Failure.
Developer Guide
60
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
StatusInfo
The parameter is used to indicate whether the partner successfully
processed the ServiceOrderNotification or not.
For Subscriptions:
● Status:[mandatory, string] SUCCESS or FAILURE
● Message: [required for FAILURE only, max length 255
characters] Provide the reason for the failure. AMP will terminate
the subscription and respond to the storefront that the order
failed.
For Mandates:
● Status: [mandatory, string] SUCCESS or FAILURE
● Message: [required for FAILURE only, max length 255
characters] Provide meaningful information about the failure, for
example, by taking the <message> string received in the
mandate setup failure response. This information will be relayed
to the storefront.
The following table shows the error codes available for partners to embed in their
exceptions and the corresponding behavior when the code is received by AMP.
Table 26: Service Order Notification Error Codes
Error Code
AMP Behavior
TRANSIENT_ERROR
The connector will retry sending the notification for a
configurable number of times, before allowing the agent to
retry in the manner described for UNKNOWN_ERROR below.
UNKNOWN_ERROR
The notification will be kept and the agent will retry sending
it for a configurable number of times. The priority of the
notification will decrease with each retry, so that newer
notifications will have higher priority.
8.3.5 Subscription Service Order Notification Examples
8.3.5.1
ServiceOrderNotification from AMP to Partner, for a subscription
campaign service.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
Developer Guide
61
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<soapenv:Header/>
<soapenv:Body>
<not:serviceOrderNotification>
<not:phoneNumber>1111111278</not:phoneNumber>
<not:orderId>order_1234</not:orderId>
<not:serviceId>campaign123</not:serviceId>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>subscriptionId</api:tag>
<api:value>0dc2a826-5e1d-4ab6-b544-853da1389476</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>quantity</api:tag>
<api:value>2</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>firstChargeDate</api:tag>
<api:value>03/09/2015</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:serviceOrderNotification>
</soapenv:Body>
</soapenv:Envelope>
8.3.5.2
ServiceOrderNotification Response - Subscription SUCCESS
scenario
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 15:09:20 CST
<soap:Body>
Developer Guide
62
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<ns1:serviceOrderNotificationResponse
<ns1:out>
<serviceId
</serviceId>
<statusInfo
<message xsi:nil="true"/>
<status>SUCCESS</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.5.3
ServiceOrderNotification Response - Subscription FAILURE
scenario
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 07:37:39 CST
Connection: close
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<serviceId
campaign123</serviceId>
<statusInfo
<message>Subscription not supported for this service</message>
<status>FAILURE</status>
Developer Guide
63
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.6 Mandate Service Order Notification Examples
8.3.6.1
ServiceOrderNotification from AMP to Partner for a Mandate
service
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:serviceOrderNotification>
<not:phoneNumber>1122334425</not:phoneNumber>
<not:orderId>dt6rrdd55d8gg77g7rf0dff02sdsdsefe34</not:orderId>
<not:serviceId>dilinip_camp_4</not:serviceId>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>quantity</api:tag>
<api:value>2</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>firstChargeDate</api:tag>
<api:value>05/12/2016</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:serviceOrderNotification>
</soapenv:Body>
</soapenv:Envelope>
Developer Guide
64
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.3.6.2
ServiceOrderNotification Response - Mandate SUCCESS scenario
The example below shows a ServiceOrderNotification response from the Partner to AMP
following a successful mandate setup, with the mandateId received in the mandate setup
response. Note the Status field value SUCCESS:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 25 Jun 2014 15:09:20 CST
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<mandateId
2a37-4813-946a-0fc83ecd6954</mandateId>
<serviceId
4</serviceId>
<statusInfo
<message xsi:nil="true"/>
<status>SUCCESS</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.6.3
ServiceOrderNotification Response - Mandate FAILURE scenario
The example below shows a ServiceOrderNotification response from the Partner to AMP
following a failed mandate setup, showing FAILURE status and with the <message>
string received in the mandate setup failure response:
Developer Guide
65
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 04 Jul 2014 07:37:39 CST
Connection: close
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<mandateId xsi:nil=”true”
<serviceId
4</serviceId>
<statusInfo
<message>Amount exceeds SpendLimit [IH] reserved amount!</message>
<status>FAILURE</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.7 One-off Service Order Notification Examples
8.3.7.1
For AMP Processed one-off scenario
8.3.7.1.1 ServiceOrderNotification from AMP to Partner, for an AMP Processed One-off
campaign service.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
Developer Guide
66
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<soapenv:Header/>
<soapenv:Body>
<not:serviceOrderNotification>
<not:phoneNumber>1111111278</not:phoneNumber>
<not:orderId>order_1234</not:orderId>
<not:serviceId>campaign123</not:serviceId>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>transactionId</api:tag>
<api:value>0dc2a826-5e1d-4ab6-b544-853da1522480</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>quantity</api:tag>
<api:value>2</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:serviceOrderNotification>
</soapenv:Body>
</soapenv:Envelope>
8.3.7.1.2 ServiceOrderNotification Response - an AMP Processed One-off SUCCESS scenario
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 15:09:20 CST
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<serviceId
</serviceId>
<statusInfo
Developer Guide
67
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<message xsi:nil="true"/>
<status>SUCCESS</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.7.1.3 ServiceOrderNotification Response - an AMP Processed One-off FAILURE scenario
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 07:37:39 CST
Connection: close
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<serviceId
campaign123</serviceId>
<statusInfo
<message>One-off not supported for this service</message>
<status>FAILURE</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
Developer Guide
68
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.3.7.2
For partner processed one-off scenario
8.3.7.2.1 ServiceOrderNotification from AMP to Partner, for a partner processed One-off
campaign service.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:serviceOrderNotification>
<not:phoneNumber>1111111278</not:phoneNumber>
<not:orderId>order_1234</not:orderId>
<not:serviceId>campaign123</not:serviceId>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>quantity</api:tag>
<api:value>2</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:serviceOrderNotification>
</soapenv:Body>
</soapenv:Envelope>
8.3.7.2.2 ServiceOrderNotification Response - partner processed One-off SUCCESS scenario
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 15:09:20 CST
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<transactionId
2335-40f4-aaf6-d29d2657caa0</transactionId>
Developer Guide
69
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<serviceId
</serviceId>
<statusInfo
<message xsi:nil="true"/>
<status>SUCCESS</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
</soap:Envelope>
8.3.7.2.3 ServiceOrderNotification Response - partner processed One-off FAILURE scenario
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 22 Apr 2015 07:37:39 CST
Connection: close
<soap:Body>
<ns1:serviceOrderNotificationResponse
<ns1:out>
<serviceId
campaign123</serviceId>
<statusInfo
<message>One-off not supported for this service</message>
<status>FAILURE</status>
</statusInfo>
</ns1:out>
</ns1:serviceOrderNotificationResponse>
</soap:Body>
Developer Guide
70
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</soap:Envelope>
8.3.8 Service Order Notification Error Handling by AMP
Error case handling by AMP, following a Service Order Notification being sent out to a
partner, are summarized below:
Table 27: AMP Error Handing after Service Order Notification
Error Case
AMP Handling
The partner fails to respond to the
AMP reports a timeout failure to the
notification within the timeout period
storefront. Any mandate or subscription
that has been created is automatically
cancelled. A Mandate Termination
Notification or Termination Notification is
sent, as applicable, if configured.
The partner responds to the notification
AMP reports a failure to the storefront,
with a status: FAILURE and
together with the message. If the failure is
informational message
in relation to a Subscription
ServiceOrderNotification, the subscription
will be cancelled by AMP.
The partner sends a mandate setup
AMP sends an error response to the
request after the notification timeout
partner.
period
The partner sends a authorize request
AMP sends an error response to the
after the notification timeout period
partner.
8.4
terminationNotification() Method
This method is applicable to subscription services only.
The terminationNotification() method is called to notify the partner when a subscription
has been terminated. It is an implementation of subscriptionNotification SOAP API.
8.4.1 terminationNotification Example and Parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
Developer Guide
71
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<soapenv:Header/>
<soapenv:Body>
<not:terminationNotification>
<not:subscriptionId>0dc2a826-5e1d-4ab6-b544-853da1389476</not:subscriptionId>
<not:description>Subscription Terminated</not:description>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>date</api:tag>
<api:value>Mon Mar 09 13:48:51 CST 2015</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>cause</api:tag>
<api:value>Service Order Notification returned FAILURE</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:terminationNotification>
</soapenv:Body>
</soapenv:Envelope>
The method takes the following parameters:
Table 28: Termination Notification Parameters
Parameters
Description
subscriptionId
The ID of the terminated subscription.
description
The description of the notification.
tagValues
[Option] An array of tag (string) and value pairs, to provide
general information:
Date: Date/Time of termination
Cause: reason for the termination:
● Subscription is cancelled
● Charge failed - after a preconfigured number of attempts
● No successful response to Service Order Notification
Developer Guide
72
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
● Subscriber is terminated
● CTN change - applicable only if CTN change notification not enabled
for the partner
8.4.2 terminationNotification Response Examples
When the partner successfully processes a notification, they should respond with the
following:
<soap:Body>
<ns1:terminationNotificationResponse
</soap:Body>
</soap:Envelope>
The example below shows a case when the notification cannot be processed successfully.
See the list of error codes in the table below:
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>subscription not found</faultstring>
<detail>
<NotificationListenerException
<errorCode
xmlns="http://notification.api.pplus.valista.com">UNKNOWN_SUBSCRIPTION_ID</error
Code>
<message xmlns="http://notification.api.pplus.valista.com">subscription not
found</message>
</NotificationListenerException>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Developer Guide
73
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.4.2.1
PartnerNotificationException Error Codes
The partner should return a PartnerNotificationException if the notification cannot be
processed successfully. The following table lists the error codes that a partner may
embed in the PartnerNotificationException and how AMP will handle the error. A Message
parameter containing the description of the error may also be returned.
Table 29: Notification Listener Exception Error Codes
Error Code
AMP Behavior
TRANSIENT_ERROR
The connector will retry sending the notification for
a configurable number of times, before allowing the
agent to retry in the manner described for
UNKNOWN_ERROR below.
UNKNOWN_SUBSCRIPTION_ID
Indicates that the listener did not recognize the
subscription ID in the notification and therefore
cannot process the notification. AMP regards this as
a permanent failure; the notification is dequeued
and discarded.
UNEXPECTED_NOTIFICATION
Indicates that the listener did not recognize the
notification and therefore cannot process the
notification. AMP regards this as a permanent
failure; the notification is dequeued and discarded.
UNKNOWN_ERROR
The notification will be kept and the agent will retry
sending it for a configurable number of times. The
priority of the notification will decrease with each
retry, so that newer notifications will have higher
priority.
No exception being returned will signify success and AMP will delete the notification.
8.5
chargeSuccessNotification() Method
This method is applicable to subscription services only.
The chargeSuccessNotification() method is called to notify the partner when a charge has
been raised as part of a subscription and successfully processed. It is an implementation
of subscriptionNotification SOAP API.
Developer Guide
74
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
8.5.1 chargeSuccessNotification Example and Parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:chargeSuccessNotification>
<not:subscriptionId>0dc2a826-5e1d-4ab6-b544-853da1389476</not:subscriptionId>
<not:description>Subscriber is charged for the subscription</not:description>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>date</api:tag>
<api:value>Mon Mar 09 13:48:51 CST 2015</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>amount</api:tag>
<api:value>$2.00</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:chargeSuccessNotification>
</soapenv:Body>
</soapenv:Envelope>
The method takes the following parameters:
Table 30: Charge Success Notification Parameters
Parameters
Description
subscriptionId
The ID of the relevant subscription.
description
The description of the notification.
tagsAndValues
[Option] An array of TagValuePair (string), to provide general
information:
date: Date/Time of charge
Developer Guide
75
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
amount: preceded by the Dollar sign, to 2 decimal places, for
example, $9.99
8.5.2 chargeSuccessNotification Response Example
When the partner successfully processes a notification, they should respond with the
following:
<soap:Body>
<ns1:chargeSuccessNotificationResponse
</soap:Body>
</soap:Envelope>
8.5.2.1
PartnerNotificationException Error Codes
The partner should return a PartnerNotificationException if the notification cannot be
processed successfully. See Table 29 which lists the error codes that a partner may
embed in the PartnerNotificationException and how AMP will handle the error. A Message
parameter containing the description of the error may also be returned, as in the
example below.
No exception will signify success and AMP will delete the notification.
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>subscription not found</faultstring>
<detail>
<NotificationListenerException
<errorCode
xmlns="http://notification.api.pplus.valista.com">UNKNOWN_SUBSCRIPTION_ID</error
Code>
Developer Guide
76
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
<message xmlns="http://notification.api.pplus.valista.com">subscription not
found</message>
</NotificationListenerException>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
8.6
chargeFailureNotification() Method
This method is applicable to subscription services only.
The chargeFailureNotification() method is called to notify the partner when a charge has
been raised as part of a subscription and failed. It is an implementation of
subscriptionNotification SOAP API.
The subscription will be cancelled when the charge has failed after a pre-configured
number of attempts.
8.6.1 chargeFailureNotification Example and Parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Header/>
<soapenv:Body>
<not:chargeFailureNotification>
<not:subscriptionId>0dc2a826-5e1d-4ab6-b544-
853da1389476</not:subscriptionId>
<not:description>Attempt to charge the subscriber failed</not:description>
<not:tagsAndValues>
<api:TagValuePair>
<api:tag>date</api:tag>
<api:value>Mon Mar 09 13:48:51 CST 2015</api:value>
</api:TagValuePair>
<api:TagValuePair>
<api:tag>amount</api:tag>
<api:value>$2.00</api:value>
Developer Guide
77
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</api:TagValuePair>
<api:TagValuePair>
<api:tag>cause</api:tag>
<api:value>Subscription Terminated</api:value>
</api:TagValuePair>
</not:tagsAndValues>
</not:chargeFailureNotification>
</soapenv:Body>
</soapenv:Envelope>
The method takes the following parameters:
Table 31: Charge Failure Notification Parameters
Parameters
Description
subscriptionId
The ID of the relevant subscription.
description
The description of the notification.
tagValues
[Option] An array of tag (string) and value pairs, to provide
general information:
Date: Date/Time of charge
Charge Amount: preceded by the Dollar sign, to 2 decimal places,
for example, $9.99
Failure Cause: the cause as received in the charge request
response.
8.6.2 chargeFailureNotification Response Example
When the partner successfully processes a notification, they should respond with the
following:
<soap:Body>
<ns1:chargeFailureNotificationResponse
</soap:Body>
Developer Guide
78
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
</soap:Envelope>
8.6.2.1
PartnerNotificationException Error Codes
The partner should return a PartnerNotificationException if the notification cannot be
processed successfully. See Table 29 which lists the error codes that a partner may
embed in the PartnerNotificationException and how AMP will handle the error. A Message
parameter containing the description of the error may also be returned, as in the
example below.
No exception will signify success and AMP will delete the notification.
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>subscription not found</faultstring>
<detail>
<NotificationListenerException
<errorCode
xmlns="http://notification.api.pplus.valista.com">UNKNOWN_SUBSCRIPTION_ID</error
Code>
<message xmlns="http://notification.api.pplus.valista.com">subscription not
found</message>
</NotificationListenerException>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
8.7
pendingAuthorizationNotification() Stub Method
!
This method should not be implemented by U.S. Cellular partners. It
should be left empty.
Developer Guide
79
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
!
The description below is here for completeness, as the method will be
noticed during API implementation, as described at the beginning of this
chapter on page 53.
The pendingAuthorizationNotification method is a standard part of AMP used to notify
partners when an asynchronous transaction previously in the AUTHORIZE_PENDING state
has changed state to one of the following:
AUTHORIZED
AUTHORIZED_DECLINED
EXPIRED
Developer Guide
80
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
9
Response Codes and Exceptions
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 to create an
SMS instead of a POST.
500 - Internal Error 500; the server encountered an unexpected condition which
prevented it from fulfilling the request.
503 - Server busy and service unavailable. Please retry the request.
More details on these at http://www.ietf.org/rfc/rfc2616.txt.
9.1
Exception Example
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Partner payment responder failed to confirm transaction [43261f9d-
6cf6-4d0c-83c7-22b7f9767e74]. Nested exception [Transaction [43261f9d-6cf6-4d0c-
83c7-22b7f9767e74]. State [CONFIRMED]. Operation not permitted in current
transaction state.].</faultstring>
<detail>
<MerchantPaymentException xmlns="http://payment.api.ops.valista.com">
<errorCode
xmlns="http://payments.api.pplus.valista.com">INAPPROPRIATE_TRANSACTION_STATE
</errorCode>
<message xmlns="http://payments.api.pplus.valista.com">Partner payment
responder failed to confirm transaction [43261f9d-6cf6-4d0c-83c7-22b7f9767e74].
Developer Guide
81
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
Nested exception [Transaction [43261f9d-6cf6-4d0c-83c7-22b7f9767e74]. State
[CONFIRMED]. Operation not permitted in current transaction state.].</message>
<recoverable
xmlns="http://payments.api.pplus.valista.com">false</recoverable>
<transactionId xmlns="http://payments.api.pplus.valista.com">43261f9d-
6cf6-4d0c-83c7-22b7f9767e74</transactionId>
</MerchantPaymentException>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
A MerchantPaymentException (tns:MerchantPaymentException) is returned via SOAP if a
call to the Payment interface results in an exception, containing:
● a Merchant Error Code which categorizes the exception
● message string giving particular details about the reason for the exception, for
example, 'The above error occurred because the call tried to confirm a transaction
which was already confirmed.'
The rest of this section suggests solutions, where possible, if a call to the payment API
results in an exception. Solutions are not provided if:
● A solution is beyond the scope of the developer. In this case, support should be
contacted.
● An expected exception occurs. For example, an unauthorized developer using a
mandate or confirm() call is made to a cancelled transaction.
The following document lists the available error codes, the possible reasons why the
exception may occur and offers possible solutions, as well as expected behavior of the
partner platform:
● USCC_API-Integration-Error_Codes.pdf.
Developer Guide
82
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
A Refund Reason Codes
The following refund reason codes are available, in text format.
Reason Codes
Service - Did not receive purchase / service
Service - Unhappy with purchase/service
Service - Goods were not what was ordered
Service - Goods were not ordered by customer
Service - Operational Error (e.g. mass refund needed)
Service - Goods were not what was advertised
Service - Content Never Worked
Service - Unable to use product/service
Service - Poor Customer Service
Billing - Duplicate charges
Billing - Charge not what was advertised/agreed
Unknown
Mass Refund - Content Provider - Did not receive purchase / service
Mass Refund - Content Provider - Goods were not what was ordered
Mass Refund - Content Provider - Goods were not what was advertised
Mass Refund - Aggregator - Charge is not what was advertised/agreed
Mass Refund - Aggregator - Duplicate charge
Developer Guide
83
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
B Sandbox Service
The sandbox service replicates real U.S. Cellular Open API User Payment SOAP web
service and returns various response objects, or 'canned responses', mapped to a pre-
configured key parameter value. The parameter may be subscriber CTN, TransactionId or
MandateId depending on the scenario. As the service does not connect to any external
interface, developers can use the service to test different scenarios of their application
without connecting to the real subscriber profile service.
HTTP basic authentication is required.
PSE settlement and reporting is not supported.
B.1 Sandbox Service Design
The Sandbox service flow is described in outline:
1 Normal Payment service is invoked up to the point where the external call is made to
the USCC ESB Remote Endpoint.
2 At this point the Sandbox route will be invoked instead of the real USCC ESB
Endpoint.
This flow ensures that all the validation logic defined in the normal service is executed
inside the original service itself.
3 Once the sandbox route is being executed, it will generate the relevant response
object based on the configured values against the CTN/TransactionId/MandateId
provided in the request.
The key parameters drive the sandbox responses, as described below.
B.2 Sandbox Scenarios
Sandbox responses are driven by the key parameters sent in a valid request.
● If the request is valid, then the sandbox service will return a 'canned response'
based on the results mapped against the pre-configured parameter values. These
scenarios are listed in section B.3.
● If the request is invalid, then the normal service flow will reject the request and
return the relevant response according to normal service specification.
The key parameter values are configurable by the administrator as sandbox service
properties. Default values are quoted in this document. Using any other valid key
parameter value not pre-configured for the canned response should return a successful
response, provided the request is valid.
Developer Guide
84
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
B.2.1 Sandbox Service and Parameter Validation
Sandbox requests are generally validated against the mandatory parameters for the
request call, as described in the Method Description sections in this document. However,
as there are exceptions to the rule, mandatory parameters are listed for each sandbox
method.
Note that for the sandbox scenario, only the key parameter is tested, regardless of the
scenario. For example, in the authorize sandbox service, providing the CTN value
'tel:+12000000112' will return a MISSING_OR_INVALID_PURCHASE_CATEGORY_CODE
regardless of the actual PCC value in the request.
B.2.2 Sandbox Response Values and Structure
Default parameter values are returned in the responses. For example, wherever USERID
is quoted in the response, the value 52492b74-8ff5-46da-b6db-f2d543313329 is used.
The error code provided for each failure scenario is returned as the value for the
<errorCode> tag, shown in bold below, in the following response structure:
<soap:Envelope> ...
<soap:Body> ...
<soap:Fault> ...
<faultcode> ...
<faultstring>ERRORMESSAGE</faultstring>
<detail> ...
<MerchantPaymentException>
<errorCode>ERRORCODE</errorCode>
<message>ERRORMESSAGE</message>
<recoverable>...
<transactionId>...
</MerchantPaymentException>
</detail> etc. Other closing tags omitted ...
Detailed descriptions of the structure, and an example of an actual failed Confirm request
for an inappropriate transaction state, are in section 9.1.
B.3 Sandbox Methods and URI
All the methods described in this document are supported. The scenarios are described in
the following sub-sections:
● One-Off Authorize and One-Off Charge Payment Sandboxes - section B.3.1
● Mandate Authorize and Mandate Charge Payment Sandboxes - section B.3.2
Developer Guide
85
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
● Confirm Payment Sandbox - section B.3.3
● Cancel Payment Sandbox - section B.3.4
● Refund Payment Sandbox - section B.3.5
● Mandate Setup Sandbox - section B.3.6
● Mandate Terminate Sandbox - section B.3.7
The service is accessible via a SOAP API, by a GET or POST operation with the following
where {serverRoot} is the placeholder for the hostname (and port where applicable) with
any base path (optional), and any base of the server you are accessing, for example:
http://example.com:8080/pseproxysandbox
For U.S. Cellular, the URL should be:
B.3.1 One-Off Authorize and Charge Canned Responses
The table below lists the CTN values configured in the Sandbox to return the expected
results, which apply to both authorize and charge calls for one-off payments, except for
the Authorization failure scenario.
The number should be used in the request call, as in the examples at 5.1.1 and 5.4.1, as
the value for the phoneNumber tag/value pair.
The mandatory parameters for the authorize/charge request call are:
● context/traceId (any value; see section 4.2.1)
● lineItems/grossCost (any value; see section 4.2.3)
● onBehalfOf (see section 5.1.2)
● idInfo/phoneNumber (as defined below)
Table 32: One-Off Authorize/Charge Pre-Defined Values and Results
Parameter
Value
Expected Result/Error Code
phoneNumber
tel:+12000000100 and
Success - Authorize/Charge.
any other valid CTN value
Successful responses returned as in
(tel:+1 followed by 10
5.1.3 Authorize and 5.4.3 Charge with
digits) not configured for
default Sandbox values.
a canned response
elsewhere
Developer Guide
86
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
phoneNumber
tel:+12000000101
Failed -
ACCOUNTHOLDER_SUSPENDED
phoneNumber
tel:+12000000102
Failed -
AMOUNT_EXCEEDS_SPENDLIMIT_CEIL
ING_AMOUNT
phoneNumber
tel:+12000000103
Failed -
AMOUNT_EXCEEDS_SPENDLIMIT_MAX
_PER_TRANSACTION
phoneNumber
tel:+12000000104
Failed -
AMOUNT_EXCEEDS_SPENDLIMIT_MIN_
PER_TRANSACTION
phoneNumber
tel:+12000000105
Failed - CONSUMER_GATEWAY_ERROR
phoneNumber
tel:+12000000106
Failed - ILLEGAL_ARGUMENT
phoneNumber
tel:+12000000107
Failed -
MERCHANT_PAYMENT_INTERNAL_ERR
OR
phoneNumber
tel:+12000000108
Failed -
MISSING_OR_EMPTY_DESCRIPTION
phoneNumber
tel:+12000000109
Failed - NO_LINE_ITEMS_SUPPLIED
phoneNumber
tel:+12000000110
Failed -
SERVICE_TEMPORARILY_UNAVAILABLE
phoneNumber
tel:+12000000111
Failed - UNKNOWN
phoneNumber
tel:+12000000112
Failed -
MISSING_OR_INVALID_PURCHASE_CA
TEGORY_CODE
phoneNumber
tel:+12000000113
Failed - AUTHORIZATION_DECLINED
Developer Guide
87
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
B.3.2 Mandate Payment Authorize and Charge Canned
Responses
The table below lists the CTN values configured in the Sandbox to return the expected
results, which apply to both authorize and charge calls for mandate payments that
include the ID of the mandate set up earlier.
The number should be used in the request call, as in the examples at 5.1.1 and 5.4.1, as
the value for the phoneNumber tag/value pair.
The mandatory parameters for the mandate authorize/charge request call are:
● context/traceId (any value; see section 4.2.1)
● lineItems/grossCost (any value; see section 4.2.3)
● onBehalfOf (see section 5.1.2)
● idInfo/phoneNumber (as defined below)
!
Any value (up to 9 characters in length) may be used for the mandateId in the
following sandbox scenarios.
Table 33: Mandate Authorize and Charge - Pre-defined Values and Results
Parameter
Value
Expected Result/Error Code
phoneNumber
tel:+12000000200
Success - Authorize/Charge. Successful
and any other valid
responses returned as in 5.1.3 Authorize
CTN value (tel:+1
and 5.4.3 Charge with default Sandbox
followed by 10
values.
digits) not
configured for a
canned response
elsewhere
phoneNumber
tel:+12000000201
Failed -
AMOUNT_EXCEEDS_MANDATE_MAX_PER_T
RANSACTION
phoneNumber
tel:+12000000202
Failed -
AMOUNT_EXCEEDS_MANDATE_PERIOD_LIM
IT
Developer Guide
88
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
phoneNumber
tel:+12000000203
Failed -
AMOUNT_EXCEEDS_TOTAL_MANDATE_LIMI
T
phoneNumber
tel:+12000000204
Failed -
AMOUNT_LESS_THAN_MANDATE_MIN_PER_
TRANSACTION
phoneNumber
tel:+12000000205
Failed - MANDATE_HAS_EXPIRED
phoneNumber
tel:+12000000206
Failed -
MANDATE_MAX_CHARGE_COUNT_REACHED
phoneNumber
tel:+12000000207
Failed - MANDATE_NOT_ACTIVE
phoneNumber
tel:+12000000208
Failed - MANDATE_NOT_FOUND
B.3.3 Confirm Canned Responses
The table below lists the transaction Id values configured in the Sandbox to return the
expected results, which apply to confirm payment calls.
The value should be used in the request call, as in the example at 5.2.1.
The mandatory parameters for the confirm request call are:
● context/traceId (any value; see section 4.2.1)
● lineItems/grossCost (any value; see section 4.2.3)
● transactionId (as defined below)
Table 34: Confirm - Pre-defined Values and Results
Parameter
Value
Expected Result/Error Code
transactionId
aabbcc300 and any other
Success - Confirm Successful
value (up to 9 character
response returned as in the
length) not configured for a
example in section 5.2.3, with
canned response elsewhere
default Sandbox values.
Developer Guide
89
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
transactionId
aabbcc301
Failed -
INAPPROPRIATE_TRANSACTION_S
TATE
transactionId
null (pass the following nil
Failed -
value in the <transactionId>
NO_TRANSACTION_ID_SUPPLIED
field:
<ns1:transactionId
xsi:nil="true"
xmlns:xsi="http://www.w3.or
g/2001/XMLSchema-
instance"/>)
transactionId
aabbcc303
Failed -
PAYMENT_AUTHORIZATION_EXPIR
ED
B.3.4 Cancel Canned Responses
The table below lists the transaction Id values configured in the Sandbox to return the
expected results, which apply to cancel payment calls.
The value should be used in the request call, as in the example at 5.3.1.
The mandatory parameters for the cancel request call are:
● context/traceId (any value; see section 4.2.1)
● transactionId (as defined below)
Table 35: Cancel - Pre-defined Values and Results
Parameter
Value
Expected Result/Error Code
transactionId
aabbcc400 and any other
Success - Cancel Successful
value (up to 9 character
response as in the example in
length) not configured for a
section 5.3.3 with default Sandbox
canned response elsewhere
values.
transactionId
aabbcc401
Failed -
INAPPROPRIATE_TRANSACTION_STA
TE
Developer Guide
90
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
transactionId
null (pass the following nil
Failed -
value in the
NO_TRANSACTION_ID_SUPPLIED
<transactionId> field:
<ns1:transactionId
xsi:nil="true"
xmlns:xsi="http://www.w3
.org/2001/XMLSchema-
instance"/>)
B.3.5 Refund Canned Responses
The table below lists the CTN values configured in the Sandbox to return the expected
results, which apply to refund payment calls.
The number should be used in the request call, as in the example at 5.5.1, as the value
for the phoneNumber tag/value pair.
The mandatory parameters for the refund request call are:
● context/traceId (any value; see section 4.2.1)
● lineItems/grossCost (any value; see section 4.2.3)
● refundReasonCode (any value; see section 5.5.2)
● transactionId (as defined below)
Table 36: Refund - Pre-defined Values and Results
Parameter
Value
Expected Result/Error Code
transactionId
aabbcc500 and any other
Success - Refund Successful
value (up to 9 character
response returned as in the example
length) not configured for
in section 5.5.3 with default Sandbox
a canned response
values.
elsewhere
transactionId
aabbcc501
Failed -
MISSING_OR_INVALID_REFUND_REA
SON_CODE
Developer Guide
91
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
transactionId
null (pass the following nil
Failed -
value in the
NO_TRANSACTION_ID_SUPPLIED
<transactionId> field:
<ns1:transactionId
xsi:nil="true"
xmlns:xsi="http://www.w
3.org/2001/XMLSchema-
instance"/>)
transactionId
aabbcc503
Failed -
TRANSACTION_ALREADY_REFUNDED
B.3.6 Mandate Set Up Canned Responses
The table below lists the CTN values configured in the Sandbox to return the expected
results, which apply to mandateSetup calls.
The number should be used in the request call, as in the example at5.6.1, as the value
for the phoneNumber tag/value pair.
The mandatory parameters for the mandate setup request call are:
● context/traceId (any value; see section 4.2.1)
● lineItems/grossCost (any value; see section 4.2.3)
● maxExpenditurePerPeriod (any value; see 5.6.2)
● idInfo/phoneNumber (as defined below)
Table 37: Mandate Set Up - Pre-defined Values and Results
Parameter
CTN value
Expected Result/Error Code
phoneNumber
tel:+12000000600
Success - Mandate set up Successful as in
and any other valid
the example in section 5.6.3.
CTN value (tel:+1
followed by 10
digits) not
configured for a
canned response
elsewhere
phoneNumber
tel:+12000000601
Failed - ACCOUTHOLDER_SUSPENDED
Developer Guide
92
© 2016 Aepona Limited. All rights reserved.
USCC AMP Payment SOAP API
Document Version 1.7
phoneNumber
tel:+12000000602
Failed - CONSUMER_GATEWAY_ERROR
phoneNumber
tel:+12000000603
Failed - ILLEGAL_ARGUMENT
phoneNumber
tel:+12000000604
Failed - CONSUMER_GATEWAY_ERROR
phoneNumber
tel:+12000000605
Failed - MISSING_
OR_INVALID_PURCHASE_CATEGORY_CODE
B.3.7 Mandate Terminate Canned Responses
The table below lists the CTN values configured in the Sandbox to return the expected
results, which apply to mandateTerminate calls.
The number should be used in the request call, as in the example at 5.7.1, as the value
for the phoneNumber tag/value pair.
The mandatory parameters for the mandate terminate request call are:
● context/traceId (any value; see 4.2.1)
● mandateId (as defined below)
Table 38: Mandate Terminate - Pre-defined Values and Results
Parameter
Value
Expected Result/Error Code
mandateId
aabbcc700 and any other valid
Success - Mandate terminate
value (up to 9 character length)
Successful response returned
not configured for a canned
as in example in section 5.7.3
response elsewhere
with default Sandbox values.
mandateId
null (pass the following nil value
Failed -
in the <mandateId> field:
NO_MANDATE_ID_SUPPLIED
<ns1:mandateId xsi:nil="true"
End of Document
Developer Guide
93
© 2016 Aepona Limited. All rights reserved.