This chapter describes the operations in the Payment interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Payment interface to charge an amount to an end-user's account using Diameter, refund amounts to that account, and split charge amounts among multiple end-users. Applications can also reserve amounts, reserve additional amounts, charge against the reservation or release the reservation.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://host:port/rest/payment/index.html
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Charge Amount operation charges an amount directly to an end-user's application using the Diameter protocol.
To charge an amount for a call, provide the SIP-formatted URI of the address of the end-user, a reference code in case there is any dispute regarding the charges, and the billing information to charge for the call.
There is no response body for the Charge Amount operation.
http://host:port/rest/payment/charge-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Charge Amount operation accepts the following parameters:
charging: A JSON object. Optional. This object defines the cost-charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
endUserIdentifier: String. Required. The address of the end-user's application that is to be charged.
referenceCode: String. Required. A unique identifier in case of disputes with respect to the charges.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charge": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"endUserIdentifier": "URI",
"referenceCode": "String"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Refund Amount operation refunds an amount directly to an end-user's application using Diameter.
To refund an amount for a call, provide the SIP-formatted URI of the address of the end-use, a reference code in case there is any dispute regarding the charges, and the billing information to charge for the call. receive the message in the request body.
There is no response body for the Refund Amount operation.
http://host:port/rest/payment/refund-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Refund Amount operation accepts the following parameters:
charging. a JSON object. Optional. This object defines the cost-charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be refunded.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
endUserIdentifier: String. Required. The address of the end-user's application that is to receive the refund.
referenceCode: String. Required. A unique identifier in case of disputes with respect to the refund.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"endUserIdentifier": "URI",
"referenceCode": "String"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Charge Split Amount operation charges an amount directly to multiple end-users concurrently (for example, for charging multiple participants in a conference.
To split the charge an amount for a call, provide the billing information to charge for the call, a reference code in case there is any dispute regarding the charges, the address of the end-user, and the percentage of the charges for which the end-user is liable.
There is no response body for the Charge Split Amount operation.
http://host:port/rest/payment/charge-split-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Charge Split Amount operation accepts the following parameters:
charge. a JSON object. Required. Use this object to define the cost-charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
referenceCode: String. Required. A unique identifier in case of disputes with respect to the charges.
splitInfo. An array of JSON objects. Required. For each entry, the end-user identifier and the method by which the charges must be split.
endUserIdentifier: String. Required. The address of the end-user.
percent. Integer. Required. The percentage this end-user should be charged.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charge": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"referenceCode": "String",
"splitInfo": [{
"endUserIdentifier": "URI",
"percent": "Integer"
}]
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Reserve Amount operation reserves an amount for an account specified by the end-user identifier.
To reserve an amount for a call, provide the address of the end-user and the billing information for the call.
If the Reserve Amount operation is successful, the response body will contain the string identifier for the reservation.
http://host:port/rest/payment/reserve-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Reserve Amount operation accepts the following parameters:
charge. a JSON object. Optional. Use this object to define the cost-charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
endUserIdentifier: String. Required. The address of the end-user against whose account the reservation is made.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charge": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"endUserIdentifier": "URI"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The response body contains the result attribute whose value is a String-formatted identifier for the reservation (used as reservationIdentifier in subsequent related operations).
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
The Reserve Additional Amount operation reserves an additional amount for an account specified by the end-user identifier.
To reserve an additional amount for a call, provide the reservation identifier obtained from the initial request to reserve an amount for the end-user and the billing information for the call.
If the Reserve Additional Amount operation is successful, the response body will contain the string identifier for the reservation.
http://host:port/rest/payment/reserve-additional-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Reserve Additional Amount operation accepts the following parameters:
charge. a JSON object. Optional. Use this object to define the cost-charging properties for the call. A call with no charging parameters can be entered as "charging":null. If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
reservationIdentifier: String. Required. The string identifier result obtained from the initial "Reserve Amount" operation for this account.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charge": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"reservationIdentifier": "String"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Charge Volume operation charges the specified volume to the account specified by the end-user identifier.
http://host:port/rest/payment/charge-volume
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Charge Volume operation accepts the following parameters:
endUserIdentifier: String. Required. Identifies the end-user account to be charged.
volume: Long. Required. Identifies the volume amount to be charged. (This is not a currency amount.)
billingText: String. Required. Textual information to appear on the bill.
referenceCode: String. Required. Code to uniquely identify the request.
parameters: JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"endUserIdentifier": "URI"
"volume": "BigDecimal"
"billingText": "String"
"referenceCode": "String"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Refund Volume operation directly applies a refund volume to the account specified by the end-user identifier.
http://host:port/rest/payment/refund-volume
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Refund Volume operation accepts the following parameters:
endUserIdentifier: String. Required. Identifies the end-user account to be refunded.
volume: Long. Required. Identifies the volume amount to be refunded.
billingText: String. Required. Textual information to appear on the bill.
referenceCode: String. Required. Code to uniquely identify the request.
parameters: JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"endUserIdentifier": "URI"
"volume": "BigDecimal"
"billingText": "String"
"referenceCode": "String"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Charge Split Volume operation applies a split volume charge to multiple end-user accounts.
The portion of the volume charge applied to each account is expressed as a percentage.
http://host:port/rest/payment/charge-split-volume
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Charge Split Volume operation accepts the following parameters:
splitInfo: A JSON object. Required. Use this object to define the end-user accounts and the percentage of the volume for the request to be billed to each account. Percentages must total 100:
endUserIdentifier: String. Required. Identifies an end-user account to be charged.
percent: Number (integer, or decimal). Required. The percentage of the transaction to be charged to the end-user account.
volume: Long. Required. Identifies the volume amount to be refunded. (This is not a currency amount.)
billingText: String. Required. Textual information to appear on the bill.
referenceCode: String. Required. Code to uniquely identify the request.
parameters: JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"splitInfo": {
"endUserIdentifier": "URI"
"percent": "BigDecimal",
},
"volume": "BigDecimal"
"billingText": "String"
"referenceCode": "String"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Get Amount operation converts a volume to a currency amount for the end-user account.
http://host:port/rest/payment/get-amount
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Get Amount operation accepts the following parameters:
endUserIdentifier: String. Required. Identifies the end-user account for the currency calculation.
volume: Long. Required. Identifies the volume to be converted to a currency amount.
parameters: A JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"endUserIdentifier": "URI"
"volume": "BigDecimal"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Charge Reservation operation charges a previously reserved amount against an end-user account.
To charge a previously reserved amount to an end-user account, provide the information for billing, the reservation identifier obtained from the initial request to reserve an amount for the end-user, and the reference code for any possible disputes.
http://host:port/rest/payment/charge-reservation
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Charge Reservation operation accepts the following parameters:
charge: A JSON object. Required. Use this object to define the cost-charging properties for the call. A call with no charging parameters can be entered as "charging":null. If a charge is to be applied, provide values for the following in the charge object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
referenceCode: String. Required. A unique identifier in case of disputes with respect to the charges.
reservationIdentifier: String. Required. The string identifier result obtained from the initial Reserve Amount operation for this account.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"charge": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"referenceCode": "String",
"reservationIdentifier": "String"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Release Reservation operation returns funds left in a reservation to the account against which this reservation was made.
To returns funds left in a reservation to an account, provide the reservation identifier obtained from the initial request to reserve an amount for the end-user.
http://host:port/rest/payment/release-reservation
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Release Reservation operation accepts the following parameter:
reservationIdentifier: String. Required. The string identifier result obtained from the initial Reserve Amount operation for this account.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"reservationIdentifier": "String"}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Reserve Volume operation reserves a volume for the account specified by the end-user identifier.
If the Reserve Volume operation is successful, the response body contains the string identifier for the reservation.
http://host:port/rest/payment/reserve-volume
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Reserve Volume operation accepts the following parameters:
endUserIdentifier: String. Required. Identifies the end-user account for which the reservation should be placed.
volume: Long. Required. Identifies the volume amount to be reserved.
billingText: String. Required. Textual information to appear on the bill.
parameters: A JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"endUserIdentifier": "URI"
"volume": "BigDecimal"
"billingText": "String"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Reserve Additional Volume operation adds or subtracts a volume to or from an existing volume reservation for the account specified by the end-user identifier.
To reserve an additional volume for a call, provide the reservation identifier obtained from the initial request to reserve an amount for the end-user and the billing information for the call.
If the Reserve Additional Volume operation is successful, the response body will contain the string identifier for the reservation.
http://host:port/rest/payment/reserve-additional-volume
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Reserve Additional Volume operation accepts the following parameters:
reservationIdentifier: String. Required. Identifies the reservation to be amended.
volume: Long. Required. Identifies the volume amount to be added to or subtracted from to the existing reservation.
billingText: String. Required. Textual information to appear on the bill.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"reservationIdentifier": "String"
"volume": "BigDecimal"
"billingText": "String"
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The Get Amount Reserve Charging operation converts a reserved volume to a currency amount for the end-user account.
http://host:port/rest/payment/get-amount-reserve-charging
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Get Amount Reserve Charging operation accepts the following parameters:
endUserIdentifier: String. Required. Identifies the end-user account for the currency calculation.
volume: Long. Required. Identifies the volume amount to be converted to a currency amount.
parameters: A JSON object. Optional. Additional name/value pairs to use to perform rating.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"endUserIdentifier": "URI"
"volume": "BigDecimal"
"parameters": {
"name": "String",
"value": "String",
},
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".