Billing Items With Moba Coin

Overview

Billing items in Mobage is done with a virtual currency called “Moba Coin”. Moba Coins can be used on both PC and mobile devices, and users can make purchases with their mobile carrier account, Web Money, credit card, etc.

Users can be billed for items by using the Mobage settlement API.

The Mobage settlement API was designed based on OpenSocial Virtual Currency API rev. 4.

Process

1. Call opensocial.requestPayment() from the browser and create settlement information.
2. A settlement information confirmation request is sent from Mobage to the game server’s endpoint URL.
3. The game server verifies the validity of the request and returns a response. If Mobage receives a normal response, the user is prompted to settle the payment.
4. If the user approves the settlement, a payment settlement request is sent from Mobage to the endpoint URL.
5. The game server verifies the validity of the request, performs the process for granting such things as item, and returns a response. If Mobage receives a normal response, the payment is settled.
6. The callback that was specified for the initially called opensocial.requestPayment() argument is called, and the process is completed.
7. There is an option to use commands such as gadgets.io.makeRequest() from the browser and make a request to prompt confirmation of the validity of a settlement to the game server.
8. The game server uses the RESTful API and sends a request to confirm the status of a settlement.
9. The status of the settlement specified with the API server is returned as a response.
10. Processing is then performed, depending on the results.

Advance preparation

The opensocial-payment Feature must be required with Gadget XML in order to use the settlement API.

The Payment handler URL of the application must be registered in order to use the settlement API. This must also be specified with Gadget XML.

The use of settlement API can be enabled by registering this information on the Developer’s Site with Gadget XML.

A Consumer Secret is required for such things as response signatures, so this must be prepared beforehand. Consumer Secrets can be referenced on the application management screen on the Developer’s Site.

Creating settlement information

Settlement information is created from Gadget using the following code.

  • Use opensocial.newBillingItem() to generate the item to be ordered. All specified values are required.
    • SKU_ID specifies a unique ID for each item in the application, using numbers.
    • PRICE specifies the unit price, using numbers.
    • COUNT specifies the number purchased, using numbers.
    • The name of the item is specified in NAME.
    • The image of the item is specified in IMAGE_URL. Please keep in mind that it will be displayed at a size of 180×180.
  • Settlement is generated with opensocial.newPayment().
    • The generated BillingItem is specified in an array in ITEMS. Currently, only 1 item can be specified.
    • The total settlement is specified in AMOUNT. This amount must match the PRICE X COUNT of the BillingItem. It must also be a number.
  • Settlement is initiated with opensocial.requestPayment().

Confirmation of settlement information

Once a settlement is initiated, a settlement confirmation request is sent from the container to the application server as an HTTP request. The destination URL is the Payment Handler URL specified with Gadget XML.

The request is made with the POST method, and the request body contains the Payment object serialized in JSON format.

PAYMENT_TYPE: Payment fixed. ORDERED_TIME: Since it is a value acquired by the browser, please use as a reference.

A signature is contained in the request in order to verify its validity. The signature must also be verified by the application server that received the request for safety purposes.

Once the validity of the request is verified, the application server saves the settlement information on the application server, issues an ORDER_ID, which is a unique settlement ID in the application, paired with the PAYMENT_ID, which is a unique settlement ID in the entire Mobage contained in the request, and returns a response. The response is serialized in JSON format.

This response must be signed.

At this time, the response is considered normal if and only if the signature is correct, the HTTP response code is 200, and the response_code is OK.

If the response is normal, a pop-up window showing information on the purchased item appears on the user’s screen.

Payment settlement

If a user has a sufficient amount of Coins to make a purchase, a request for payment settlement is sent to the Payment Handler URL as an HTTP request.

The request is made with the GET method, and the ORDER_ID is contained in the query parameters.

Similarly to the settlement confirmation request, this request is also signed, so the signature must be verified.

If the signature verification is successful, the ORDER_ID contained in the request is used to acquire the settlement information saved on the application server. If there are no problems with the settlement information, a response confirming payment settlement and granting the item to the user is returned.

The ORDER_ID, RESPONSE_CODE, and AMOUNT, which is the final settlement amount, are contained in the response. The response is serialized in JSON format. This response must also be signed.

At this time, the response is considered normal if and only if the signature is correct, the HTTP response code is 200, and the response_code is OK.

If a normal response is returned, the Moba Coin is automatically debited and the payment is settled and completed.

Confirmation of settlement results

Finally, a confirmation is done to ensure that the settlement was completed normally. For this confirmation, the gadgets.io.makeRequest() is used and a query is sent to the application server, including the ORDER_ID.

The application server that received the request acquires the PAYMENT_ID of the saved settlement information from the ORDER_ID and confirms the state of the settlement with the RESTful API.

If the settlement is completed normally, a response is sent as-is and the process is complete. However, if by any chance a settlement failure status is returned regardless of the fact that the settlement should have been finalized on the application server, a response must be returned indicating that the settlement is being cancelled, along with the granting of the item.

Requests from the Mobage open platform

Query parameters

Field name

Description

opensocial_app_id

The ID of the application

opensocial_app_url

The URL of the application

opensocial_viewer_id

The IDs of the users using the application

opensocial_owner_id

The IDs of the users who installed the application

Since token and token_secret are not in the PC version, it is not necessary to include them in the signature.

OAuth Signature verification

The OAuth Signature contained in the Authorization header is information used to verify that the request to the partner server was not falsified. Please be sure to verify the OAuth Signature to ensure that you have not received a request from a malicious third party and that no unexpected actions will be performed.

Follow the procedure below in order to verify the OAuth Signature.

Generating a Base String

Generate a base string following the procedure below.

1. Obtain the HTTP request method (example: GET).
2. Prepare the URL, excluding the query parameters (example: http://example.com/123456789)
3. Obtain the protocol parameters, excluding the realm and oauth_signature from the authorization header.

Parameters obtained from the authorization header

Field name

Description

oauth_body_hash

The SHA1 hash value of the body contents (They are only included at the time of a POST request)

oauth_consumer_key

The value issued at the time of application registration

oauth_nonce

The unique value of each request

oauth_signature_method

The signature method (HMAC-SHA1 ? fixed)

oauth_timestamp

The UNIX timestamp value

oauth_version

The OAuth version (1.0 ? fixed)

4. Obtain all of the query parameters sent from the Gadget server.
5. Combine the parameters obtained in 3 and 4 in accordance with the specifications. All characters other than alphanumerical characters, "-", ".", "_", and "~" are percent-encoded and connected with "=". Connected key and value pairs are sorted alphabetically and connected with "&".

Creating and comparing signatures

Signatures are generated by signing a Base String with a key string.

The key string is a value in which the oauth_token_secret of the authorization header and Consumer Secret issued during application registration are percent-encoded and connected with "&". The algorithm (currently HMAC-SHA1 fixed) specified with the oauth_signature_method of the authorization header is utilized for the generation of the digest value. This value is further encoded in BASE64 and becomes the signature (please remove anything like linefeed strings which are added when the digest value was generated).

The request can be verified by comparing this value against the oauth_signature of the authorization header.

Sample

Perl: Please use Lite module version 1.24 or later.

PHP: The OAuth library is available here.

Method for signing responses to the Mobage open platform

Body Hash calculation

A base64 digest value is generated from the body of the response. SHA1 is used for the algorithm. If a "=" is on the end, it will be removed.

Generating a Base String

In addition to the generated Body Hash, the following values are used.

body_hash

Body Hash

nonce

The unique value of each request

timestamp

The UNIX timestamp value

consumer_key

The value issued at the time of application registration

All characters other than alphanumerical characters, "-", ".", "_", and "~" are percent-encoded and connected with "=". The connected key and value pairs are sorted alphabetically and connected with "&".

Generating a Signature

The generated Base String is used to generate a base64 digest value with HMAC-SHA1, using the Consumer Secret as a key. If a "=" is on the end, it will be removed.

Generating a Header

Using the URI-escaped generated Signature as a value and "signature" as a key, these are connected with "=" and then connected with the Base String with "&".

This value is included in the X-MBGA-PAYMENT-SIGNATURE header, and the response is sent.

Sample

Perl:

PHP:

Revision History

  • 12/18/2012
    • Changing Sequence figure.
  • 12/2010
    • Initial Release.

PREVIOUS

Inputting and Displaying Free Text

NEXT

RESTful API Reference