# Feature Page of Payment

The feature page of payment helps a plug-in with payment and is functionally equivalent to wx.requestPayment.

Note: To enable the payment feature for a plug-in, you need to additionally apply for the permission in Mini Program Plug-In > Basic Settings > Payment Capability on the Admin Console. In addition, personal Mini Programs are not allowed to use the payment feature in a plug-in, regardless of whether the payment permission application is approved.

# Call Parameters

When functional-page-navigator is used for redirection to the feature page of payment, the corresponding parameter name should be set to the fixed value requestPayment. Other parameters are set as follows:

Parameters of args:

Parameter Name Type Required Description
fee Number Yes Amount to be displayed on the payment feature page, in fen
paymentArgs Object No Any data, which is passed to the response function on the payment feature page
currencyType String No Code of the currency symbol to be displayed on the payment feature page. It is CNY by default.

Valid values of currencyType:

Value Description Minimum Version
CNY Currency symbol ¥
USD Currency symbol US$
JPY Currency symbol J¥
EUR Currency symbol €
HKD Currency symbol HK$
GBP Currency symbol £
AUD Currency symbol A$
MOP Currency symbol MOP$
KRW Currency symbol ₩

Callback result:

Callback Type errMsg Description
success requestPayment:ok Payment calling succeeds
fail requestPayment:fail cancel The user cancels payment.
fail requestPayment:fail (detail message) Payment calling fails. The detail message is the detailed failure reason returned by the backend.

Code example:

<!-- plugin/components/pay.wxml -->
<!-- Before release, set version to "release", and ensure that the plug-in owner Mini Program has been released. -->
<functional-page-navigator
  version="develop"
  name="requestPayment"
  args="{{ args }}"
  bind:success="paymentSuccess"
  bind:fail="paymentFailed"
>
  <button class="payment-button">Paid  0.01  CNY</button>
</functional-page-navigator>
// plugin/components/pay.js
Component({
  data: {
    args: {
      fee: 1,             // Payment amount, in fen
      paymentArgs: 'A', // Custom parameter to be passed to a feature page function
      currencyType: 'USD' // Currency symbol. The abbreviation of the currency symbol, for example, US$, is displayed on the page. 
    }
  },
  methods: {
    // Callback API for successful payment
    paymentSuccess: function (e) {
      console.log(e);
    },
    // Callback API for failed payment
    paymentFailed: function (e) {
      console.log(e);
    }
  }
})

When a user clicks navigator, the following payment feature page will be displayed:

Feature Page of Payment

# Configuring Feature Page Functions

A plugin developer must provide a function in a plugin owner Mini Program for the payment feature page to respond to payment calling in a plugin. To be specific, when the plug-in is redirected to the feature page of payment, this function will be called at the right time to help complete payment. If this feature page function is not provided, calling of the feature page will fail and the fail event is returned.

The payment feature page function should be named beforeRequestPayment and provided as an export function in the functional-pages/request-payment.js file under the root directory of the plug-in owner Mini Program.

Parameter Name Type Description
paymentArgs Object Custom data passed to the feature page via the paymentArgs field in the arg parameter of functional-page-navigator
callback Function Callback function. After calling the function, a Mini Program will initiate payment (similar to wx.requestPayment).

Parameters of the callback function:

Parameter Name Type Description
error Object Failure information. If no failure occurs, null should be returned.
requestPaymentArgs Object Payment parameters used to call wx.requestPayment. Included parameters are as follows.

Parameters of requestPaymentArgs:

These parameters are used to initiate payment and are the same as those of wx.requestPayment, except that callback functions (success, fail, and complete) are not included.

Parameter Type Required Description
timeStamp String Yes Timestamp in seconds, from January 1st 1970 at 00:00:00 to the present time
nonceStr String Yes A random string of less than 32 characters
package String Yes Value of the prepay_id parameter returned by the unified order placement API, which should be submitted in the following format: prepay_id=***
signType String Yes Signature algorithm. Only MD5 is supported currently.
paySign String Yes Signature. For specific signature schemes, see Mini Program Payment API Documentation;

For more information, see WeChat Payment API Documentation.

Sample code of the feature page function:

// functional-pages/request-payment.js
exports.beforeRequestPayment = function (paymentArgs, callback) {
  // Note:
  // The feature page function (this function) should not require other files outside the functional-pages directory.
  // Other files outside the functional-pages directory should not require files in this directory.
  // Such a require call will not be supported in the future.
  //
  // Files in the functional-pages directory can be required.
  var getOpenIdURL = require('./URL').getOpenIdURL;
  var paymentURL = require('./URL').paymentURL;

  // Custom parameter. The value should be 'A' passed from a plug-in.
  var customArgument = paymentArgs.customArgument;

  // Step 1: Obtain code by calling the wx.login method, and exchange the openId of the order placer with the code by calling the Weixin API on the server.
  // For specific documentation, visit https://mp.weixin.qq.com/debug/wxadoc/dev/api/api-login.html?t=20161230#wxloginobject.
  wx.login({
    success: function (data) {
      wx.request({
        url: getOpenIdURL,
        data: { code: data.code },
        success: function (res) {
          // The openid of the user is obtained.
          // Step 2: Call the unified order placement API on the server for payment. Payment parameters are returned. Development of this is the same as that of the common wx.requestPayment.
          // For specific documentation, visit https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=7_4&index=3.
          wx.request({
            url: paymentURL,
            data: { openid: res.data.openid },
            method: 'POST',
            success: function (res) {
              console.log('unified order success, response is:', res);
              var payargs = res.data.payargs;
              // Step 3: Call the callback function callback to complete payment.
              // The callback function must return two parameters: err and requestPaymentArgs.
              // The err parameter should be set to null (or some failure information).
              // The requestPaymentArgs parameter is used to call wx.requestPayment. The success, fail, and complete functions are not supported.
              // Other included parameters should be the same as those of wx.requestPayment.
              var error = null;
              var requestPaymentArgs = {
                timeStamp: payargs.timeStamp,
                nonceStr: payargs.nonceStr,
                package: payargs.package,
                signType: payargs.signType,
                paySign: payargs.paySign,
              };
              callback(error, requestPaymentArgs);
            }
          });
        },
        fail: function (res) {
          console.log(' Failed to obtain the openid of the user, so services such as open APIs are unavailable.', res);
          // The first parameter of the callback function is error information. Error information is returned.
          callback(res);
        }
      });
    },
    fail: function (err) {
      console.log('wx.login  Failed to call the API, so services such as open interfaces are unavailable.', err)
      // The first parameter of the callback function is error information. Error information is returned.
      callback(err);
    }
  });
}

** Note: Feature page functions should not require other files outside the functional-pages directory, and files outside the functional-pages directory should not require files in this directory. Such a require call will not be supported in the future.**

This directory and its files should be included in the code of a plug-in owner Mini Program (not the plug-in code) as part of the plug-in owner Mini Program (not a part of the plug-in). To add or modify this part of code, you need to release the plug-in owner Mini Program to take it into effect in the official version, or re-preview the plug-in owner Mini Program to take it into effect in the developer version.