9 Payment

This chapter describes the operations in the Payment interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About the Payment Interface

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.

REST Service Descriptions Available at Run-time

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 machine on which Services Gatekeeper is installed.

Charge Amount

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/charge-amount

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.

Refund Amount

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/refund-amount

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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:

{
  "charge": {
    "description": "String",
    "amount": "BigDecimal",
    "code": "String",
    "currency": "String"
  },
  "endUserIdentifier": "URI",
  "referenceCode": "String"
}

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.

Charge Split Amount

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/charge-split-amount

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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"
  }]
}

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.

Reserve Amount

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 successful, the response body will contain the string identifier for the reservation.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/reserve-amount

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

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

Reserve Additional Amount

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/reserve-additional-amount

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.

Charge Reservation

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/charge-reservation

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Charge Reservation 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 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"
}

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.

Release Reservation

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.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/payment/release-reservation

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.