API Description for Parlay X
Payment
The following sections describe the Payment API used for handling payment based on content for both pre- and post-paid services:
Amount charging API
chargeAmount
Charge an amount directly from an end user account.
Table 8-1 chargeAmount(endUserIdentifier, amount, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be charged.
|
|
amount
|
Decimal
|
The currency amount of the charge
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
refundAmount
Refunds an amount directly from an end user account.
Table 8-2 refundAmount(endUserIdentifier, amount, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be refunded.
|
|
amount
|
Decimal
|
The currency amount of the charge
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
Volume charging API
chargeVolume
Charges a volume directly from an end user account.
Table 8-3 chargeVolume(endUserIdentifier, volume, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be charged.
|
|
volume
|
Long
|
The volume to charge.
|
|
billingText
|
String
|
Textual information to appear on the bill.
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
getAmount
Converts the given volume to a currency amount.
Table 8-4 getAmount(endUserIdentifier, volume)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be charged.
|
|
volume
|
Long
|
The volume to be converted.
|
|
Returns
|
|
|
Decimal
|
Currency amount resulting from the conversion process.
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
refundVolume
Refunds a volume to an account
Table 8-5 refundVolume(endUserIdentifier, volume, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be charged.
|
|
volume
|
Long
|
The volume to be refunded.
|
|
billingText
|
String
|
Textual information to appear on the bill.
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
|
Decimal
|
Currency amount resulting from the conversion process.
|
.
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
Reserved amount charging API
reserveAmount
Reserve an amount directly from an end user account.
Table 8-6 reserveAmount(endUserIdentifier, amount, billingText)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account subject to the reservation.
|
|
amount
|
Decimal
|
The currency amount of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
Returns
|
|
|
String
|
Reservation Identifier. Textual information to uniquely identify the reservation.
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
reserveAdditionalAmount
Add an amount to a previously made reservation.
Table 8-7 reserveAdditionalAmount(reservationIdentifier, amount, billingText)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation to be amended.
|
|
amount
|
Decimal
|
The currency amount of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
chargeReservation
Charge a previously made reservation.
Table 8-8 chargeReservation(reservationIdentifier, amount, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation to be charged.
|
|
amount
|
Decimal
|
The currency amount of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownReservationException
|
|
InvalidArgumentException
|
releaseReservation
Release a previously made reservation. Returns the funds left in the reservation.
Table 8-9 releaseReservation(reservationIdentifier)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
UnknownReservationException
|
|
ServiceException
|
Reserved volume charging API
getAmount
Converts the given volume to a currency amount.
Table 8-10 getAmount(endUserIdentifier, volume)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account to be charged.
|
|
volume
|
Long
|
The volume to be converted.
|
|
Returns
|
|
|
Decimal
|
Currency amount resulting from the conversion process.
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
reserveVolume
Reserve a volume directly from an end user account.
Table 8-11 reserveAmount(endUserIdentifier, amount, billingText)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
endUserIdentifier
|
EndUserIdentifier
|
The end user's account subject to the reservation.
|
|
volume
|
Long
|
The volume of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
Returns
|
|
|
String.
|
Reservation identifier. Textual information to uniquely identify the reservation.
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
reserveAdditionalVolume
Add a volume to a previously made reservation.
Table 8-12 reserveAdditionalVolume(reservationIdentifier, volume, billingText)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation to be amended.
|
|
volume
|
Long
|
The volume of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ServiceException
|
|
UnknownEndUserException
|
|
InvalidArgumentException
|
chargeReservation
Charge a previously made reservation.
Table 8-13 chargeReservation(reservationIdentifier, volume, billingText, referenceCode)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation to be charged.
|
|
volume
|
Long
|
The volume of the reservation.
|
|
billingText
|
String
|
Textual information to appear on the bill
|
|
referenceCode
|
String
|
Textual information to uniquely identify the request.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ChargeFailureException
|
|
UnknownReservationException
|
|
InvalidArgumentException
|
releaseReservation
Release a previously made reservation. Returns the funds left in the reservation.
Table 8-14 releaseReservation(reservationIdentifier)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
reservationIdentifier
|
String
|
ID of the reservation.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
UnknownReservationException
|
|
ServiceException
|
Data Types
Table 8-15 Data types specific for Payment
|
Data type
|
Description
|
|
|
DatedTransaction
|
Structure containing the following parameters:
|
|
|
transactionDate
|
Date the transaction occurred.
Datatype: Date.
|
|
|
transactionDetails
|
The transaction details.
Datatype: String.
|
Exceptions
Table 8-16 Exceptions specific for Payment
|
ID
|
Exception
|
Description
|
|
ACM1000E
|
UnknownVoucherException
|
Indicates that the voucher identification that is passed is unknown.
|
|
ACM1001E
|
InadequateCredentialsException
|
Indicates that one of the credentials was left nil where that was not expected.
|
