6 OneAPI Payment

This chapter describes the operations in the Payment interface of the OneAPI 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 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. For more information on OMA, see:

http://www.openmobilealliance.org/Technical/release_program/docs/CopyrightClick.aspx?pck=ParlayREST&file=V2_0-20110111-C/OMA-TS-ParlayREST_OneAPIProfile-V2_0-20110111-C.pdf

The information provided in this document is based on the OneAPI specification and provided here for convenience.

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/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.

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 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.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/oneapi/1/payment/endUserId/transactions/amount

Request Header

The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.

Request Body

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.

Response Header

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" for more information.

Response Body

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.

Examples

Example 6-1 shows a sample of a OneAPI Charge Payment request.

Example 6-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 6-2 shows a sample of a OneAPI Charge Payment response.

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

Query Transaction Status

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.

Authorization

Basic or OAuth 2.0

HTTP Method

GET

URI

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.

Request Header

The header contains the Host and Authorization code (if required).

Request Body

There is no request body for this operation.

Response Header

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" for more information.

Response Body

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.

Examples

Example 6-3 shows a sample of a OneAPI Query Transaction Status request.

Example 6-3 OneAPI Query Transaction Status Request

GET http://example.com/1/payment/tel%3A%2B15415550100/transactions/amount/abc123
Host: example.com
Authorization: n0t4fr4id333

Example 6-2 shows a sample of a OneAPI Query Transaction Status response.

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

List Transactions for Application User

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.

Authorization

Basic or OAuth 2.0

HTTP Method

GET

URI

http://host:port/oneapi/1/payment/endUserId/transactions/amount

Request Header

Provide a valid OAuth bearer token to identify both the end user and the application in the Authorization header field.

Request Body

There is no request body for this operation.

Response Header

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" for more information.

Response Body

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.

Examples

Example 6-5 shows a sample of a OneAPI List Transactions for Application User request.

Example 6-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 6-6 shows a sample of a OneAPI List Transactions for Application User response.

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

Refund 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.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/oneapi/1/payment/endUserId/transactions/amount

Request Header

The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.

Request Body

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.

Response Header

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" for more information.

Response Body

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.

Examples

Example 6-7 shows a sample of a OneAPI Refund request.

Example 6-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 6-8 shows a sample of a OneAPI Refund response.

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

Reserve Amount

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

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

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. The endUserId is the address of the subscriber to charge the reservation to (MSISDN).

Request Header

The MIME-type for the Content-Type header field can be either application/x-www-form-urlencoded or application/json.

Request Body

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 user 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 –> referenceSequence=1

reserve additional amount -> referenceSequence=2

charge reservation -> referenceSequence=3

release reservation -> 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.

Response Header

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 will contain the status code and the reason for the failure. See "Errors and Exceptions" for more information.

Response Body

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.

Reserving Additional Amount

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.

Examples

Example 6-9 shows a sample of a OneAPI Reserve Amount request.

Example 6-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 6-10 shows a sample of a OneAPI Reserve Amount response.

Example 6-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 6-11 shows a sample of a OneAPI Reserve Additional Amount request.

Example 6-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 6-12 shows a sample of a OneAPI Reserve Additional Amount response.

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

Charge Reservation

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.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/oneapi/1/payment/endUserId/transactions/amountReservation/transactionID

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.

Response Header

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

Response Body

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.

Examples

Example 6-13 shows a sample of a OneAPI Charge Amount Against Reservation request.

Example 6-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 6-14 shows a sample of a OneAPI Charge Amount Against Reservation response.

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

Release Reservation

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.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

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.The endUserId is the address of the subscriber to charge (MSISDN). The transactionID is the unique value generated by Services Gatekeeper from the original reservation request.

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.

Response Header

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

Response Body

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.

Examples

Example 6-15 shows a sample of a OneAPI Release Reservation request.

Example 6-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 6-16 shows a sample of a OneAPI Release Reservation response.

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

Resource States

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 6-1 and Table 6-2.

Table 6-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 6-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.

Payment Exceptions

For an overview of exceptions in the Services Gatekeeper RESTful interface, see "Errors and Exceptions" for more information. A list of service and policy exceptions specific to the payment interface is provided in Table 6-3.

Table 6-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: The user did not accept the refund The refund request is for an amount greater than the original charge

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:

The user did not accept the refund
The refund request is for an amount greater than the original charge