">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification » PC » Payment API (mixi Payment)

Payment API (mixi Payment)

Using the mixi payment for PCs, the item transaction using mixi payments can be incorporated into mixi app for PCs. This page explains how to use and incorporate the Payment API on a mixi app for PCs.

Note that the Payment API is used after passing the mixi payment program application.

 

Restriction

The Payment API for PCs explained on this page is only available for a mixi app developed by SAP, which has mixi permission. In this case, SAP needs the permission to develop each app.

Preparing for using the Payment API

You need to previously prepare for using Payment API.

Procedure

The Payment API for PCs is an API that added the unique payment flow of the mixi platform based on the OpenSocial Virtual Currency API. To protect the content of the payment, you need to call not only the prescribed JavaScript API but also execute the backend side (external server on the SAP side).

Preparation

On the Payment API for PCs, creating and verifying the signature are required to verify the validity of transmitted data. The used signature is strings created by HMAC-SHA1. The used key is the Consumer Secret of the RESTful API displayed on the mixi app edit page. (edit_appli.pl) Be sure to get this Consumer Secret strings on this page.

Basic Execution Flow

The representative payment flow using the Payment API for a mixi app for PCs is as shown below.

pc_payment_flow

  1. Request to create payment information from a mixi app to the backend server.
  2. Return to the mixi app to create payment information in the backend server
  3. Call the API for payment based on the payment information.
  4. Point code is sent from the mixi server to the backend server.
  5. The backend server holds point code and returns it to the mixi server.
  6. After the payment confirmation pop-up window is displayed, the user deletes it.
  7. The payment execution status is sent from the mixi server to the backend server.
  8. After checking the payment information, the backend server returns the result to the mixi server.
  9. After displaying the payment completion pop-up window, the user deletes it.
  10. After the specified callback function is called, the result is given.

Payment status and test payment

There are three types of payment status on an app.
*is_test is one of parameters to edit for payment information. Normally, you set it as false status.

Payment status Description Payment process
(In case of is_test=false)
Payment process
(In case of is_test=true)
Not used Before accepted the mixi payment program application. Payment is not available Payment is not available
Testing payment Accepted the mixi payment program application, not notified test OK. The under development status of the payment function. Test payment Test payment
Using payment Notified test OK
Available for providing payment with your customer
Actual payment Test payment
Payment status
  • Payment is not available: You are not able to use payment process.
  • Test payment: You are able to use payment process. Sales are not applicable.
  • Actual payment: You are able to use the payment process. Sales are applicable.
is_test fragmentation.
  • Please always set is_test fragmentation to “false” in principle
  • If you provide the customer with the payment function set to “true,” it is the testing payment status that is not counted as sales.
  • Use is_test=true if you use the test subscription on the SAP side after providing payment. In this case, please apply is_test=true only in the payment process of the developer account and be sure not to influence the user payment.

Creating payment information

When a user requests item subscription on a mixi app, creating the payment information is requested of the backend server first. At this time, the target item ID for subscription is determined.

On the backend server that received the request for creating payment information, it prepares for the required information based on item ID and creates the signature based on them. It finally returns them to the mixi app as a result.

Here are the required items as the payment information.

Item Description
callback_url The backend server URL called by the mixi server.
inventory_code Optional strings to specify payment on the backend server.
is_test The value is “true” if it is the payment execution test and “false” if it is the actual payment.
item_id Item ID (numbers are only available to edit)
item_price Consumed points of subscribed items, which is the essential attribution for the item price. Be sure to refer the introduction to the mixi payment program to edit maximum and minimum units.

First of all, connecting those items with “&” you need to create a string. The name of the items is considered in alphabetical order at that time. Also, all values of the item need to be executed as URI escape.

callback_url=http%3A%2F%2Fsap.server.host%2Fcreate_order&inventory_code=123&is_test=true&item_id=123&item_price=500

You need to finish the following process for the string. The result is the signature regarding the parameters above.

  1. Execute URI escape for the whole strings above. - (1)
  2. Give “&” at the end of Consumer Secret, which was previously obtained. - (2)
  3. Using the HMAC-SHA1 algorithm, which is 2 as a key, you can obtain the digest value of 1. - (3)
  4. Execute BASE64 encode for 3.

Return the parameters above and the created signatures to the mixi app as a result.

*Execute URI escape based on this rule (http://oauth.net/core/1.0a#encoding_parameters

Calling the payment API

Based on the payment information obtained by the backend server, you need to call the API for payment. Use the opensocial.requestPayment() function as this API.

var paymentHandlerUrl = "http://sap.server.host/create_order";

var params = {};
params[opensocial.Payment.Field.AMOUNT] = 250;
params[mixi.Payment.Field.ITEM_NAME] = "エクスカリバー";
params[mixi.Payment.Field.SIGNATURE] = "TmihyproUc02HOh17W0uz++WdYM=";
params[mixi.Payment.Field.ITEM_ID] = 123;
params[mixi.Payment.Field.IS_TEST] = 'true';
params[mixi.Payment.Field.INVENTORY_CODE] = 123;
params[opensocial.Payment.Field.PAYMENT_TYPE] = opensocial.Payment.PaymentType.PAYMENT;

var payment = opensocial.newPayment(params);

opensocial.requestPayment(payment, paymentHandlerUrl, function(response) {
    // do something
});

First of all create the payment object with the opensocial.newPayment() function. The required items are as below.

定数 説明
opensocial.Payment.Field.AMOUNT Amount of points for item
mixi.Payment.Field.ITEM_NAME Name of item
mixi.Payment.Field.SIGNATURE Signed strings of payment information
mixi.Payment.Field.ITEM_ID Item ID
mixi.Payment.Field.IS_TEST The value is “true” if it is the payment execution test and “false” if it is the actual payment.
mixi.Payment.Field.INVENTORY_CODE Optional strings to specify the payment on the SAP side.
opensocial.Payment.Field.PAYMENT_TYPE Payment type (opensocial.Payment.PaymentType.PAYMENT)

The actual payment execution is called by opensocial.requestPayment() function. This function receives following arguments.

  1. Payment object
  2. Backend server URL called by mixi server
  3. Callback function

After calling the requestPayment() function, the payment start request is sent from the mixi app to the mixi server.

In case of a lack of a balance point

Regarding the amount of points included in the payment information, the pop-up window is displayed that tells the user about the lack of a balance point if the target user does not have the required points. Charging points and clicking continue on the pop-up window, the payment is executed again.

Sending point code

After the requestPayment() function is called by a mixi app, the mixi server sends point code to the backend server URL specified by the paymentHandlerUrl argument. The actual sent parameter is as shown below.

パラメータ 説明
opensocial_app_id mixi app ID
opensocial_owner_id mixi app user ID
inventory_code Optional strings numbered on the backend server
point_code Point code to specify this payment
item_id Item ID
item_price Number of item price
item_name Item name
signature Signed strings created on the backend server
is_test The value is “true” if it is the payment execution test and “false” if it is the actual payment.

This request is given the 2-legged OAuth signature. The signature is listed on the Authentication header. To protect an unauthorized subscription, you must verify the signature. The verification method is the same specification as the mixi app mobile. However, as the base strings in verification, you need to include the parameters above.

Returning the result

After the signature verification, the payment detail, such as the point code, is held on the backend server. After that, the succeeded response is returned.

Status: 200
Content-Type: text/plain

OK

This response needs to be executed within 10 seconds. If there is no response within 10 seconds, the transaction is not executed.

Payment confirmation by the user

After the mixi server received the result, the pop-up window is displayed for the user to confirm the payment. The user can decide whether to make the payment. Requesting the payment, the execution is operated on the mixi server.

Sending the payment execution status

After operating the payment execution on the mixi server, the request to reconfirm the payment to the backend server is sent. The request is the specified URL on paymentHandlerUrl given when calling the requestPayment() function. The parameter included in the request is as shown below.

Parameter Description
opensocial_app_id mixi app ID
opensocial_owner_id mixi app user ID
point_code The point code to specify this payment
status Status 10=subscription successful
updated The date of subscription completed(UTC)

This request is given the two-legged OAuth signature. The signature is listed on the Authentication header. To protect an unauthorized subscription, you must verify the signature. The verification method is the same specification as the mixi app mobile. However, as the base strings in verification, you need to include the parameters above.

Returning the result

After the signature verification, the payment detail, such as the point code, is held on the backend server. After that, the succeeded response is returned.

Status: 200
Content-Type: text/plain

OK

This response needs to be executed within 10 seconds. If there is no response within 10 seconds, payment confirmation is not executed.

Displaying the transaction completed to user

For the mixi server that received the result from the backend server, the pop-up window is displayed, which tells the user about payment completion. The user may close the window.

Calling the callback function

Last, the callback function specified requestPayment() function as the argument is called. In this case, the opensocial.ResponseItem object is given to the argument.

To see if the payment is successful on the mixi app, use the haderror() function of ResponseItem object. In this case, be sure to obtain an error code with the getErrorCode() function and properly execute the error.

opensocial.requestPayment(payment, paymentHandlerUrl, function(response) {
    if (response.hadError()) {
        var code = response.getErrorCode();
        if (code == opensocial.Payment.ResponseCode.USER_CANCELLED) {
            // ユーザが決済をキャンセルしたときの処理
        } else {
            // その他のエラーに対する処理
        }
    } else {
        var data = response.getData(); // opensocial.Paymentオブジェクト
        // 決済完了時の処理
    }
});

You can obtain the opensocial.Payment object which the payment transaction is completed with ResponseItem object.

Each value can be obtained by giving the constant which you want to obtain on the getField()function of Payment object.

Note that opensocial.Payment.ResponseCode.INVALID_TOKEN is returned on the getErrorCode() function if the user permission of mixi_apps2 scope is not obtained.

Payment confirmation

You can see the payment status with the RESTful API.
Confirming the payment status, you can examine the returned result from the backend server to the mixi server.

Using Payment Confirmation API

Using the mixi app mobile and Payment API (mixi point payment) confirmation API for the payment information, you can obtain the payment status.

Be sure to refer to the mixi app mobile and Payment API (mixi point payment) to see the information details obtained for payment confirmation. In order to use RESTful API, be sure to refer to the API access because the specification for the RESTful API for PC two-legged OAuth is applied. 

Restriction when using the payment confirmation API

The details of restrictions about the RESTful API specification are applied to the confirmation API for the payment information as well.

TOP OF THIS PAGE