This chapter describes the Oracle Communications Services Gatekeeper OneAPI Payment/Diameter communication service in detail.
Applications use the RESTful Payment interface to charge an amount to an end-user's account using Diameter and to refund amounts to that account. Applications can also reserve amounts, reserve additional amounts, charge against the reservation or release the reservation.
The Services Gatekeeper OneAPI Payment interface complies with Open Mobile Alliance (OMA) specifications. See "OneAPI Payment Interface" in Services Gatekeeper Statement of Compliance for a reference to the supported specification and RESTful bindings schema. Note that this interface does not support volume charging.
See "Using the OneAPI RESTful Interfaces" in Services Gatekeeper Application Developer's Guide for general information on creating applications using the OneAPI RESTful interface.
The information provided in this document is based on the OneAPI specification and provided here for convenience.
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/oneapi/1/payment/application.wadl
Where host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
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 telephone address of the end-user (endUserId), a reference code (code) in case there is any dispute regarding the charges, and the billing information to charge for the call.
http://host:port/oneapi/1/payment/endUserId/transactions/amount
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
endUserId is the address of the subscriber to charge (MSISDN).
The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.
The request body for the Charge Amount operation accepts the following parameters:
endUserId: String. The URL-escaped end user ID. For example, a MSISDN including the ’tel:' protocol identifier and the country code preceded by ’+'.For example, tel:+15415550100.
transactionOperationStatus: Enumeration. This indicates the desired resource state, in this case ’charged'. See "Resource States" for more information.
description: String. The human-readable text to appear on the bill provided so the subscriber can easily see what was purchased.
currency: String. The 3-figure currency code defined in ISO4217.
amount: Decimal. The amount to be charged.
code: String. The charging code, from an existing contractual description that references an operator price point.
clientCorrelator: String. Optional. This uniquely identifies the create charge request. If there is a communication failure during the charge request, using the same client correlator when retrying the request allows the operator to avoid applying the same charge twice.
onBehalfOf: String. Optional. Allows aggregators or partners to specify the actual payee.
purchaseCategoryCode: String. Optional. An indication of the content type. Values meaningful to the billing system would be published by a OneAPI implementation.
channel: String. Optional. Can be Wap, Web, MMS, or SMS, depending on the source of user interaction.
taxAmount: Decimal. Optional. Indicates a tax amount already charged by the merchant or application.
serviceID: String. Optional. The ID of the partner or merchant service.
productID: String. Optional. Combines with the serviceID to uniquely identify the product being purchased.
The Location header field contains the URI:
http://host:port/oneapi/1/payment/endUserId/transactions/amount/transactionID
Where transactionID is the string identifier returned in the response body.
The Status-Line header field returned indicates if the charge has been created or accepted. An accepted response indicates that additional processing is required before the transaction is complete. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide for more information.
The response body contains a confirmation amountTransaction JSON data structure consisting of the parameters supplied in the payment request.
{"amountTransaction": { "clientCorrelator": "String", "endUserId": "String", "paymentAmount": { "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountCharged": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the resource state. See, "Resource States" for more information.
Example 20-1 shows a sample of a OneAPI Charge Payment request.
Example 20-1 OneAPI Charge Payment Request
POST http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT endUserId= tel%3A%2B15415550100& transactionOperationStatus=charged& description= Alien%20%20Game& currency=USD& amount=10& code=REF-12345& clientCorrelator=54321& onBehalfOf=Example%20Games%20Inc& purchaseCategoryCode=Game& channel=WAP& taxAmount=0
Example 20-2 shows a sample of a OneAPI Charge Payment response.
Example 20-2 OneAPI Charge Payment Response
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT Location: http://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/abc123 {"amountTransaction": { "clientCorrelator": "54321", "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "10", "currency": "USD", "description": " Alien Game" }, "totalAmountCharged": "10" }, "code": "REF-12345", "resourceURL": " http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount/abc123 "transactionOperationStatus": "Charged" }}
The Query Transaction Status operation retrieves the current status of a payment transaction. This operation is useful in cases where the original charge request returns a status of processing. Applications may require a confirmed charge to a subscriber's account before allowing access to paid resources.
To query for a transaction's status, provide the transactionID of the earlier transaction.
http://host:port/oneapi/1/payment/endUserId/transactions/amount/transactionID
Where host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running. The endUserId is the address of the subscriber originally charged (MSISDN). The transactionID is provided by Services Gatekeeper in the original payment request response.
The header contains the response status, Content-Type, Content-Length and Date.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide for more information.
The response body contains the transaction's amountTransaction JSON data structure consisting of the parameters supplied in the payment request.
{"amountTransaction": { "clientCorrelator": "String", "endUserId": "String", "paymentAmount": { "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountCharged": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the current resource state. See "Resource States" for more information.
Example 20-3 shows a sample of a OneAPI Query Transaction Status request.
Example 20-3 OneAPI Query Transaction Status Request
GET http://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/abc123 Host: example.com Authorization: n0t4fr4id333
Example 20-4 shows a sample of a OneAPI Query Transaction Status response.
Example 20-4 OneAPI Query Transaction Status Response
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT Location: http://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/abc123 {"amountTransaction": { "clientCorrelator": "54321", "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "10", "currency": "USD", "description": " Alien Game" }, "totalAmountCharged": "10" }, "code": "REF-12345", "resourceURL": " http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount/abc123 "transactionOperationStatus": "Charged" }}
The List Transactions for Application User operation lists all the transactions a subscriber has performed within an application.
To list a subscriber's transactions for an application, provide a valid OAuth token provided by Services Gatekeeper to identify the application and subscriber.
The response body contains a list of applicable transactions and their current status.
http://host:port/oneapi/1/payment/endUserId/transactions/amount
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
endUserId is the address of the subscriber to charge (MSISDN).
Provide a valid OAuth bearer token to identify both the end user and the application in the Authorization header field.
The Location header field contains the URI:
http://host:port/oneapi/1/payment/endUserId/transactions/amount/transactionID
where transactionID is the string identifier returned in the response body.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide for more information.
The response body contains a list of amountTransaction JSON data structures consisting of the parameters supplied in the payment requests.
{"amountTransaction": { "clientCorrelator": "String", "endUserId": "String", "paymentAmount": { "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountCharged": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
A resourceURL is included as a reference to the response for each transaction. The transactionOperationStatus provides the resource state. See "Resource States" for more information.
Example 20-5 shows a sample of a OneAPI List Transactions for Application User request.
Example 20-5 OneAPI List Transactions for Application User Request
GET http://example.com/1/payment/tel%3A%2B15415550100/transactions/amount HTTP/1.1 Accept: application/json Authorization: n0t4fr4id333 Date: Thu, 06 Feb 1976 02:51:59 GMT
Example 20-6 shows a sample of a OneAPI List Transactions for Application User response.
Example 20-6 OneAPI List Transactions for Application User Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT {"paymentTransactionList": { "amountTransaction": [ { "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "9", "currency": "USD", "code": "abc123", "description": "Alien%20Invaders" }, }, "code": "REF-ASM600-239238", "resourceURL": "https://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/tx-a3c0e4e006da40a8a5b5-045972478cc3", "transactionOperationStatus": "Charged" }, { "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "9", "currency": "USD", "code": "def456", "description": "Snakes%20Alive" }, }, "code": "REF-ASM600-239568", "resourceURL": "https://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/tx-134sf3e6e6405gfd904e62d8ed84343u", "transactionOperationStatus": "Charged" }, { "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "9", "currency": "USD", "code": "wac-c116480e-316a-44e7-be76-5fde978b2f59", "description": "Monkey%20Tennis." }, }, "code": "REF-ASM600-239211", "resourceURL": "https://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/tx-391sff4e6401gf3f404d82d9fe954545v", "transactionOperationStatus": "Charged" }, ], "resourceURL": "https://example.com/1/payment/tel%3A%2B15415550100/transactions/amount" }}
The Refund Amount operation refunds a currency amount directly to a subscriber's application using the Diameter protocol.
To refund an amount to a subscriber, submit a POST
operation request in the same format as the Charge Amount operation.
http://host:port/oneapi/1/payment/endUserId/transactions/amount
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
endUserId is the address of the subscriber to refund (MSISDN).
The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.
The request body for the Refund Amount operation accepts the following parameters:
endUserId: String. The URL-escaped end user ID. For example, a MSISDN including the ’tel:' protocol identifier and the country code preceded by ’+'. For example, tel:+15415550100.
transactionOperationStatus: Enumeration.This indicates the desired resource state, in this case ’refunded'. See "Resource States" for more information.
description: String. The human-readable text to appear on the bill, so the subscriber can easily see what was refunded.
currency: String. The 3-figure currency code defined in ISO4217.
amount: Decimal. The amount to be refunded.
code: String. The charging code, from an existing contractual description that references an operator price point.
clientCorrelator: String. Uniquely identifies this refund request. If there is a communication failure during the refund request, using the same client correlator when retrying the request allows the operator to avoid applying the same refund twice.
onBehalfOf: String. Optional. Allows aggregators or partners to specify the actual payee.
purchaseCategoryCode: String. Optional. An indication of the content type. Values meaningful to the billing system would be published by a OneAPI implementation.
channel: String. Optional. Can be ”Wap”, ”Web”, ”MMS”, or ”SMS”, depending on the source of user interaction.
taxAmount: Decimal. Optional. Indicates a tax amount already charged by the merchant or application.
serviceID: String. Optional. The ID of the partner or merchant service.
productID: String. Optional. Combines with the serviceID to uniquely identify the product being refunded.
The Location header field contains the URI:
http://host:port/oneapi/1/payment/endUserId/transactions/amount/transactionID
where, transactionID is the string identifier returned in the response body.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See ”Errors and Exceptions” in Using the OneAPI RESTful Interfaces for more information.
The response body contains a confirmation amountTransaction JSON data structure consisting of the parameters supplied in the refund request.
{"amountTransaction": { "clientCorrelator": "String", "endUserId": "String", "paymentAmount": { "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountRefunded": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the resource state. See "Resource States" for more information.
Example 20-7 shows a sample of a OneAPI Refund request.
Example 20-7 OneAPI Refund Request
POST http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT endUserId=tel%3A%2B15415550100& transactionOperationStatus=refunded& description= Alien%20Game& currency=USD& amount=10& code=REF-12345& clientCorrelator=54321& onBehalfOf=Example%20Games%20Inc& purchaseCategoryCode=Game& channel=WAP& taxAmount=0
Example 20-8 shows a sample of a OneAPI Refund response.
Example 20-8 OneAPI Refund Response
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT Location: http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount/efg789 {"amountTransaction": { "clientCorrelator": "54321", "endUserId": "tel:+15415550100", "paymentAmount": { "chargingInformation": { "amount": "10", "currency": "USD", "description": "Alien Invaders" }, "totalAmountRefunded": "10" }, "code": "REF-12345", "resourceURL": "http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amount/efg789", "transactionOperationStatus": "Refunded" }}
The Reserve Amount operation reserves a currency amount for a subscriber account to use as future payment.
To reserve an amount for future payment, provide the address of the enduser and the billing information for the transaction.
If the Reserve Amount operation is successful, the response body contains the string identifier for the reservation.
The default expiration or timeout of reserved amounts in Services Gatekeeper is 86400 seconds. To change the timeout duration to another value:
Locate and unpack the following .jar file:
OCSG_Domain\config\store_schema\com.bea.wlcp.wlng.plugin.payment.px30.diameter.store_5.1.0.0.jar
Open the wlng-cachestore-config-extensions.xml file for editing.
Locate the <expiry expiry_age="86400"/> parameter.
Edit the value by entering the number of seconds before a reservation expires.
Save the file.
Repackage the .jar file in the original location.
Restart the instance of Services Gatekeeper.
Changing the default expiration setting also changes the Parlay X payment reservation timeout in Services Gatekeeper.
http://host:port/oneapi/1/payment/endUserId/transactions/amountReservation
Where host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
endUserId is the address of the subscriber to charge the reservation to (MSISDN).
The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.
The request body for the Reserve Amount operation accepts the following parameters:
endUserId: String. The URL-escaped enduser ID. For example, a MSISDN including the ’tel:' protocol identifier and the country code preceded by ’+'. For example, tel:+15415550100.
transactionOperationStatus: Enumeration. This indicates the desired resource state, in this case ’reserved'. See "Resource States" for more information.
description: String. The human-readable text to appear on the bill, so the users can easily see what they reserved.
currency: String. The 3-figure currency code defined in ISO4217.
amount: Decimal. The amount to be reserved.
code: String. The charging code, from an existing contractual description that references an operator price point.
clientCorrelator: String. Uniquely identifies this create reservation request. If there is a communication failure during the reservation request, using the same client correlator when retrying the request allows the operator to avoid applying the same reservation twice.
referenceSequence: Integer. Allows Services Gatekeeper to distinguish easily between new and repeated requests in the case of a communication failure. For each transaction within a reservation sequence, iterate the referenceSequence by 1. For example:
initial reservation use referenceSequence=1
reserve additional amount use referenceSequence=2
charge reservation use referenceSequence=3
release reservation use referenceSequence=4
If you do not need to reserve an additional amount, then the referenceSequence for charge reservation is 2 and the referenceSequence for release reservation is 3.
onBehalfOf: String. Optional. Allows aggregators or partners to specify the actual payee.
purchaseCategoryCode: String. Optional. An indication of the content type. Values meaningful to the billing system would be published by a OneAPI implementation.
channel: String. Optional. Can be ”Wap”, ”Web”, ”MMS”, or ”SMS”, depending on the source of user interaction.
taxAmount: Decimal. Optional. Indicates a tax amount already charged by the merchant or application.
serviceID: String. Optional. The ID of the partner or merchant service.
productID: String. Optional. Combines with the serviceID to uniquely identify the product being reserved.
The Location header field contains the URI:
http://host:port/oneapi/1/payment/endUserId/transactions/amountReservation/transactionID
Where:
transactionID is the string identifier returned in the response body.
If the request fails, the Status-Line header field contains the status code and the reason for the failure. See ”Errors and Exceptions” in Using the OneAPI RESTful Interfaces for more information.
The response body contains a confirmation amountReservationTransaction JSON data structure consisting of the parameters supplied in the reservation request.
{"amountReservationTransaction": { "clientCorrelator": "String", "endUserId": "String", "paymentAmount": { "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the resource state. See "Resource States" for more information.
The Reserve Amount operation is used to update an existing reservation to request additional funds or resources. See "Charge Amount" for more information. Change the following parameters in the request for additional funds:
transactionOperationStatus=reserved: Indicates that we are not changing the resource state, just the value being reserved. See "Resource States" for more information.
amount: The additional reserved amount for this request (not the total amount reserved so far).
referenceSequence: Each time you reserve an additional amount against an existing reservation, make sure to iterate the referenceSequence each time. This ensures Services Gatekeeper can distinguish between new requests for additional amounts, and those that are being repeated due to a communication failure.
Example 20-9 shows a sample of a OneAPI Reserve Amount request.
Example 20-9 OneAPI Reserve Amount Request
POST http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT endUserId= tel%3A%2B15415550100& transactionOperationStatus=reserved& description= Streaming%20video%20of%20the%Big%20Fight& currency=USD& amount=10& referenceCode=Video-abc123& clientCorrelator=54321& referenceSequence=1& onBehalfOf=Example%20Video%20Inc& purchaseCategoryCode=Video& channel=WAP& taxAmount=0
Example 20-10 shows a sample of a OneAPI Reserve Amount response.
Example 20-10 OneAPI Reserve Amount Response
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT Location: http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 {"amountReservationTransaction": { "clientCorrelator": "54321", "endUserId": "tel:+15415550100", "paymentAmount": {"chargingInformation": { "amount": "10", "currency": "USD", "description": "Streaming video of the Big Fight" }}, "code": "REF-12345", "referenceSequence": "1", "transactionOperationStatus": "Reserved" }}
Example 20-11 shows a sample of a OneAPI Reserve Additional Amount request.
Example 20-11 OneAPI Reserve Additional Amount Request
POST http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT transactionOperationStatus=reserved& amount=5& code=REF-12346& referenceSequence=2&
Example 20-12 shows a sample of a OneAPI Reserve Additional Amount response.
Example 20-12 OneAPI Reserve Additional Amount Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT {"amountReservationTransaction": { "endUserId": "tel:+15415550100", "paymentAmount": { "amountReserved": "15", "chargingInformation": { "amount": "10", "currency": "USD", "description": "Streaming Video of the Big Fight" }, "totalAmountCharged": "0" }, "code": "REF-12346", "referenceSequence": "2", "resourceURL": " http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123", "transactionOperationStatus": "Reserved" }}
The Charge Reservation operation charges a previously reserved amount against a subscriber's account.
To charge a previously reserved amount to a subscriber's account, provide the information for billing, the reservation identifier obtained from the initial request to reserve funds, and the reference code for any possible disputes.
http://host:port/oneapi/1/payment/endUserId/transactions/amountReservation/transactionID
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
endUserId is the address of the subscriber to charge (MSISDN).
transactionID is the unique value generated by Services Gatekeeper from the original reservation request.
Change the following parameters in the reservation request to charge against a reservation:
transactionOperationStatus=charged: Indicates a change in the resource state to charge against the reservation. See "Resource States" for more information.
amount: The total amount to charge against the reservation.
referenceSequence: Iterate the referenceSequence with the charge request. This ensures the OneAPI server can distinguish between new requests for charging against a reservation, and those that are being repeated due to a communication failure.
description: Update the description to reflect the completed transaction.
The clientCorrelator parameter is not used as the resource has already been created.
If the request fails, the Status-Line header field contains the status code and the reason for the failure. See ”Errors and Exceptions” in Using the OneAPI RESTful Interfaces for more information
The response body contains a confirmation amountReservationTransaction JSON data structure consisting of the parameters supplied in the charge request.
{"amountReservationTransaction": "endUserId": "String", "paymentAmount": { "amountReserved":"Decimal", "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountCharged": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }
Once the charge has been applied, the amountReserved parameter should have a value of zero. The totalAmountCharged parameter contains the final amount to charge against the reservation.
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the resource state. See "Resource States" for more information.
Example 20-13 shows a sample of a OneAPI Charge Amount Against Reservation request.
Example 20-13 OneAPI Charge Amount Against Reservation Request
POST http://example.com/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT transactionStatus=charged& description= Three%20rounds%20of%20the%Big%20Fight& amount=15& code=REF-123457& referenceSequence=3&
Example 20-14 shows a sample of a OneAPI Charge Amount Against Reservation response.
Example 20-14 OneAPI Charge Amount Against Reservation Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT {"amountReservationTransaction": { "endUserId": "tel:+15415550100", "paymentAmount": { "amountReserved": "0", "chargingInformation": { "amount": "15", "currency": "USD", "description": " Streaming Video of the Big Fight " }, "totalAmountCharged": "15" }, "code": "REF-123457", "referenceSequence": "3", "resourceURL": " http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 ", "transactionOperationStatus": "Charged" }}
The Release Reservation operation returns funds left in a reservation to the subscriber account against which the reservation was made.
To return funds left in a reservation to an account, provide the transactionID identifier obtained from the initial reservation request.
http://host:port/oneapi/1/payment/endUserId/transactions/amountReservation/transactionID
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running
endUserId is the address of the subscriber to charge (MSISDN).
transactionID is the unique value generated by Services Gatekeeper from the original reservation request.
Change the following parameters in the reservation request to release a reservation:
transactionOperationStatus=released: Indicates a change in the resource state to release the reservation. See "Resource States" for more information.
referenceSequence: Iterate the referenceSequence when releasing a reservation. This ensures the OneAPI server can distinguish between new requests for reservation release, and those that are being repeated due to a communication failure.
If the request fails, the Status-Line header field contains the status code and the reason for the failure. See ”Errors and Exceptions” in Using the OneAPI RESTful Interfaces for more information.
The response body contains a confirmation amountReservationTransaction JSON data structure consisting of the parameters supplied in the release reservation request.
{"amountReservationTransaction": { "endUserId": "String", "paymentAmount": { "amountReserved":"Decimal", "chargingInformation": { "amount": "Decimal", "currency": "String", "description": " String" }, "totalAmountCharged": "Decimal" }, "code": "String", "resourceURL": "URL" "transactionOperationStatus": "String" }}
Once the resource reservation has been released the amountReserved parameter should have a value of zero. The totalAmountCharged parameter contains the final amount to charge against the reservation.
A resourceURL is included as a reference to the response. The transactionOperationStatus provides the resource state. See "Resource States" for more information.
Example 20-15 shows a sample of a OneAPI Release Reservation request.
Example 20-15 OneAPI Charge Release Reservation Request
POST http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 HTTP/1.1 Accept: application/json Host: example.com:80 Content-Type: application/x-www-form-urlencoded Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT transactionOperationStatus=released& referenceSequence=4&
Example 20-16 shows a sample of a OneAPI Release Reservation response.
Example 20-16 OneAPI Release Reservation Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 12345 Date: Thu, 04 Jun 2009 02:51:59 GMT {"amountReservationTransaction": { "endUserId": "tel:+15415550100", "paymentAmount": { "amountReserved": "0", "chargingInformation": { "amount": "10", "currency": "USD", "description": "Streaming Video of the Big Fight" }, "totalAmountCharged": "5" }, "code": "REF-12346", "referenceSequence": "4", "resourceURL": " http://example.com/oneapi/1/payment/tel%3A%2B15415550100/transactions/amountReservation/abc123 ", "transactionOperationStatus": "Released" }}
The client application passes the transactionOperationStatus in the request body so that the resource can be placed into a desired state. Services Gatekeeper either confirms this desired state in the transactionStatus response field, or instead shows a failure state as shown in Table 20-1 and Table 20-2.
Table 20-1 Resource States for Charges and Refunds
Value | Description |
---|---|
Charged |
A successful charge was made. |
Refunded |
A successful refund was made. |
Denied |
The policy exception in the response will explain the reason. For example, insufficient balance, security issue, etc. |
Refused |
The charge or refund was refused, or not explicitly accepted. |
Table 20-2 Resource States for Reservations
Value | Description |
---|---|
Reserved |
A successful reservation was created. |
Denied |
The policy exception in the response will explain the reason. For example, insufficient balance, security issue, etc. |
Refused |
The reservation was refused, or not explicitly accepted. |
Charged |
A reservation has been charged against. |
Released |
The reservation has ended. |
For an overview of exceptions in the Services Gatekeeper RESTful interface, see ”Errors and Exceptions” in Using the OneAPI RESTful Interfaces for more information. A list of service and policy exceptions specific to the payment interface is provided in Table 20-3.
Table 20-3 Service Exceptions for Payment
ID | Exception Text | Variables |
---|---|---|
SVC0270 |
Charging operation failed, the charge was not applied |
None |
SVC0271 |
Refunds not supported |
Guidance from the implementation on what to do instead should be provided |
SVC0273 |
Refund failed |
The reason the refund failed. Valid reasons include:
|