Gcash Mini Program Development PlatformGcash Mini Program Development PlatformDOCS

Use OrderStr to pay

Users can use the wallet app to pay for the order placed in the mini program if the wallet app provides the payment service. This document introduces the payment by calling the my.tradePay API with orderStr. The following two payment types are supported:

General online payment

Users can complete a general online payment in the mini program.

User experience

To complete a payment in the mini program, users usually follow the steps below:

  1. The user chooses goods in the mini program and creates an order, then presses the Pay button in the mini program.
  2. The mini program redirects the user to the wallet app and the wallet app displays the payment page.
  3. The user confirms the order information, such as the payee and amount, then clicks the Pay button to make the payment.
  4. After confirming the payment, the wallet app displays the payment result and redirects the user back to the payment result page in the mini program.

Procedures

To use the my.tradePay API to initiate a payment in the mini program, mini program developers must complete the following steps:

  1. Confirm that the payment service provided by the wallet app supports the payment by orderStr and obtain the integration guide from the wallet app.
  2. Integrate the payment service at the mini program server side.
  3. Create a mini program in the wallet workspace on the Mini Program Platform, or make sure that the mini program can be published in the wallet app.
  4. Provide goods and payment services in the mini program.
  5. Publish the mini program.

Payment process

The following figure illustrates the payment process:

image

Figure 1. Process flow of the general payment

The payment process contains the following steps:

  1. The user places an order in the mini program (Step 1).
  2. The mini program client sends a request to create the order to the mini program server by calling the my.request API (Step 1.1).
  3. The mini program server creates the order and returns orderStr to the mini program client (Step 1.1.1 & 1.1.2).
  4. The mini program client initiates the payment request by calling the my.tradePay API with orderStr to the wallet app (Step 1.1.2.1).
  5. The wallet processes the payment request internally and the wallet app renders the cashier page (Step 1.1.2.1.1 - 1.1.2.1.3).
  6. The user confirms the payment and the wallet app displays the payment result (Step 2 - 2.2).
  7. The wallet app returns the payment result to the mini program client. At the same time, the wallet server returns the payment result to the mini program server (Step 2.3).
  8. The mini program client displays the payment result (Step 2.3.1).

Note:

The payment flow is for reference and may vary depending on the API implementation of the wallet.

Pre-authorization payment

Pre-authorization payment is a common practice in rental and hotel industries where the user can pre-authorize a payment in advance. Unlike goods with confirmed prices, the price of some services can only be determined when the user has finished using the service. As such, service merchants can use pre-authorization payments to ensure that the order can be paid before providing the service.

 

Merchants can call the my.tradePay API with orderStr to initiate a pre-authorization payment request via the mini program. After the user has granted pre-authorization, the funds are captured by the merchant automatically after the service amount is settled.

User experience

To complete a pre-authorization payment, users usually follow the steps below:

  1. The user confirms to use the service provided by the mini program.
  2. The mini program redirects the user to the pre-authorization page in the wallet app.
  3. The user confirms the authorization, then the wallet app redirects the user back to the mini program. The user starts to use the service.
  4. After the user has finished using the service and the service fee is confirmed, the funds are deducted by the merchant automatically and the user receives a notification in the wallet app.

Procedures

To use the my.tradePay API to complete the pre-authorization in the mini program, mini program developers must complete the following steps:

  1. Confirm that the wallet app supports the pre-authorization capability and obtain the integration guide from the wallet.
  2. Integrate the payment service at the mini program server side.
  3. Create a mini program in the wallet workspace on the Mini Program Platform, or make sure that the mini program can be published in the wallet app.
  4. Provide the service that requires pre-authorization in the mini program.
  5. Publish the mini program.

Payment process

The following figure illustrates the pre-authorization payment process:

image

Figure 2. Process flow of the pre-authorization payment

The payment process contains the following steps:

  1. The user starts to use the service in the mini program (Step 1).
  2. The mini program client sends a request to create the order to the mini program server by calling the my.request API (Step 2).
  3. The mini program server creates the order and returns orderStr to the mini program client (Step 3 & 4).
  4. The mini program client initiates the pre-authorization request by calling the my.tradePay API with orderStr to the wallet app (Step 1.1.2.1).
  5. The wallet processes the pre-authorization request internally and the wallet app renders the pre-authorization page (Step 6 - 8).
  6. The user completes the pre-authorization and the wallet app returns the pre-authorization result to the mini program client (Step 10 - 12).
  7. The user starts to use the service provided by the mini program. When the user has finished using the service, the mini program client sends the payment request to the mini program server by calling the my.request API (Step 13 - 15).
  8. The mini program server sends the payment request by calling the server API provided by the wallet and the wallet server returns the payment result (Step 16 & 17).

Note:

The payment flow is for reference and may vary depending on the API implementation of the wallet.

Sample code

Sample code for the my.tradePay API calling is as follows:

copy
my.tradePay({
    orderStr: 'app_id=2018112803019836&biz_content=%7B%22amount%22%3A%220.02%22%2C%22extra_param%22%3A%22%7B%5C%22category%5C%22%3A%5C%22CHARGE_PILE_CAR%5C%22%7D%22%2C%22order_title%22%3A%22%D6%A7%B8%B6%B1%A6%D4%A4%CA%DA%C8%A8%22%2C%22out_order_no%22%3A%22ZMOutOrderNoAppFreeze2018052915543415090975%22%2C%22out_request_no%22%3A%22ZMOutReqNoAppFreeze20180529155434581875858%22%2C%22pay_timeout%22%3A%222d%22%2C%22payee_user_id%22%3A%222088202224929664%22%2C%22product_code%22%3A%22PRE_AUTH_ONLINE%22%7D&charset=GBK&format=json&sign=L4wk%2FNKcbJOo3n6Q5qbPzn0jUsvZlK4jr7iXnghudR0zeWJMmeNC71qIBSQfIz45n%2B5iTd0NQ5IK581xI2xCShTCiKAywnQcDmA%2Bjf%2BrRdKCDQCMLfCz%2BZ37C%2B6zxAX3e81%2F8Hr29lw4VPFfHkp9FmMwKw%2FGkNfV5ZlWoh7UtN8%3D&sign_type=RSA&timestamp=2018-05-29+15%3A54%3A35&version=1.0',  
    success: function(res) {            
        my.alert({
            content: JSON.stringify(res),
        });
    },
    fail: function(res) {  
        my.alert({
            content: JSON.stringify(res),
        });
    },
});