Make a payment

Alipay+ provides a set of APIs for Mobile Payment Providers (MPPs) to implement the capability of making a payment in the scenario where a user uses an MPP app to present a payment code to the merchant.

To make a payment, the MPP needs to take the following steps:

Step 1: Obtain the payment code from Alipay+
Step 2: Render and present the payment code
Step 3: Process the payment request
Step 4: Return the payment result

Workflow

The following figure illustrates the workflow of making a payment in the User-presented Mode Payment scenario.

Figure 1: Payment workflow

The payment process consists of the following steps:

The user opens the payment code page of the MPP app to request a payment code. (step 1)
The MPP app request the payment code from the MPP server. The MPP server then calls the getPaymentCode API to request the payment code from Alipay+. (step 2-3)
Alipay+ returns the payment code to the MPP server, which then sends the payment code to the MPP app. (step 4-5)
The MPP app displays the payment code on the payment code page. (step 6)
The merchant scans the payment code and initiates a payment by sending the payment code and the payment information to Alipay+ via the ACQP. (step 7-9)
Alipay+ decodes the payment code to obtain the MPP user ID and calls the pay API to send the payment request to the MPP server. (step 10-11)
The MPP server processes the payment and returns the payment result to Alipay+. (step 12-13)
Alipay+ returns the payment result to the ACQP. The ACQP then returns the payment result to the merchant. (step 14-15)
The MPP server informs the MPP app of the payment result. The MPP app then renders and displays the payment result page to the user. (step 16-17)

Step 1: Obtain the payment code

After the MPP app requests the payment code, the MPP server calls the getPaymentCode API to obtain the payment code from Alipay+.

Processing logic

When using the getPaymentCode API, take the following things into consideration:

Ensure the following parameters are configured properly in the request:

customerId: indicates the MPP user ID, which is required by Alipay+ for the payment code generation.
codeQuantity: the number of payment codes to be sent to the MPP. The default value of this parameter is 1. The MPP can specify this parameter to obtain multiple payment codes at a time. The MPP can cache the additional payment codes, and display a new payment code in case a previous one is expired, as the default validity period of a payment code is only 1 minute.
env.deviceTokenId: indicates the token ID of the user's device. This parameter is required and used by Alipay+ for risk control.

Handle the response properly, especially the following parameters:

paymentCodeInfoList: a list of payment codes. The quantity of the payment codes is determined by the value of the codeQuantity parameter in the request.
result: the result of the payment code application. The MPP might receive different results from Alipay+. Follow the instructions below to handle the result.

result.resultStatus	result.resultCode	Request status	Actions
`S`	`SUCCESS`	Successful	Display the payment code.
`F`	Multiple possible values exist, such as `ACCESS_DENIED`, `INVALID_CLIENT`, etc.	Failed	Take actions according to the result code (specified on the result.resultCode parameter). For more information, see the Result codes section below.
`U`	Multiple possible values exist, such as `REQUEST_TRAFFIC_EXCEED_LIMIT`, `UNKNOWN_EXCEPTION`, etc.	Unknown.	Retry the same request.
No result received		Unknown	Retry the same request.

Sample

The following samples show the request and response when the MPP calls the Alipay+ getPaymentCode API in the User-presented Mode Payment scenario.

Request from the MPP to Alipay+

copy
{
  "region": "PH",
  "customerId": "21281****",
  "codeQuantity": "3",
  "env": {
    "deviceTokenId": "21212****"
  }
}

Response from Alipay+ to the MPP

copy
{
  "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
  "paymentCodeInfoList": [{
    "paymentCode": "2892889331822611998",
    "codeValidityStartTime": "2022-01-01T12:00:01+08:00",
    "codeExpiryTime": "2022-01-01T12:01:00+08:00"
  }, {
    "paymentCode": "2892889221822611928",
    "codeValidityStartTime": "2022-01-02T12:01:01+08:00",
    "codeExpiryTime": "2022-01-01T12:02:00+08:00"
  }, {
    "paymentCode": "2892889441822611221",
    "codeValidityStartTime": "2022-01-02T12:02:01+08:00",
    "codeExpiryTime": "2022-01-01T12:03:00+08:00"
  }]
}

For more information about how to use the API (such as the parameter description), see getPaymentCode.

Step 2: Render and display the payment code

After receiving the payment code in the response from Alipay+ getPaymentCode API, the MPP app renders and presents the payment code on the payment code page. The merchant can then scan the payment code to initiate a payment request.

Step 3: Process the payment

After the merchant scans the payment code, Alipay+ sends the payment request to the MPP by using the pay interface. The MPP then processes the payment request.

Processing logic

When using the pay API, take the following things into consideration:

Handle the request properly, especially the following parameters:

payToAmount: the amount that Mobile Payment Provider settles to Alipay+ in Mobile Payment Provider's currency. By default, the amount that the user actually pays is specified by this parameter.
currency: the MPP must be able to handle the requests made with currencies in ISO 4217.
paymentMethod: indicates the payment method that is used to collect the payment. The following rules apply:

paymentMethod.paymentMethodType: indicates the payment method. The value of this parameter is fixed as CONNECT_WALLET.
paymentMethod.paymentMethodId: indicates the payment code value. The value of this parameter is the same as that of the paymentCode parameter from the getPaymentCode API.
paymentMethod.customerId: indicates the MPP user ID. This parameter is required and the MPP must be able to handle payment requests with the specified user ID.

paymentExpiryTime: indicates when the payment times out. For User-presented Mode Payment, the payment times out in 3 minutes by default.

Ensure the following parameters are configured properly in the response:

result: indicates the payment result. The MPP must be able to synchronously return the payment result by using this parameter.

result.resultCode: The following table shows how to set the value of the result.resultCode parameter under different conditions.

Condition	Value of *result.resultCode*	Required or not
The payment timed out.	`ORDER_IS_CLOSED`	Required
The payment amount exceeds the limit of a single transaction.	`PAYMENT_AMOUNT_EXCEED_LIMIT`
The accumulated payment amount exceeds the user payment limit.	`USER_AMOUNT_EXCEED_LIMIT`
The number of payments exceeds the limit.	`PAYMENT_COUNT_EXCEED_LIMIT`
The user's account balance is not enough.	`USER_BALANCE_NOT_ENOUGH`
The payment is declined because the user's KYC failed.	`USER_KYC_NOT_QUALIFIED`
The payment is declined due to risk control.	`RISK_REJECT`	Recommended
the payment failed because the payment method used by the MPP is not available	`UNAVAILABLE_PAYMENT_METHOD`
The payment is declined because the merchant verification failed.	`MERCHANT_NOT_REGISTERED`
The payment is declined because the user verification failed.	`USER_PAYMENT_VERIFICATION_FAILED`

Sample

The following samples show the request and response when Alipay+ calls the pay API in the User-presented Mode Payment scenario.

Request from Alipay+ to the MPP

copy
{
  "order": {
    "referenceOrderId": "OrderID_010101****",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M00xxxxx0001",
      "merchantMCC": "5411",
      "merchantName": "UGG",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      },
      "store": {
        "referenceStoreId": "S00xxxx0001",
        "storeName": "UGG-2",
        "storeMCC": "5411"
      }
    }
  },
  "acquirerId": "102218800000000****",
  "pspId": "102217200000000****",
  "paymentRequestId": "201811291907410100070000007****",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006050000000000125733DAHJ****",
    "customerId":"2160xxxxxxxxxxx1"
  },
  "payToAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "paymentQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "paymentFactor": {
    "isInStorePayment": "true"
  }
}

Response from the MPP to Alipay+

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 },
 "paymentId":"201xxxxxxxxxxxxxxxxxxxxxxx4444",
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "customerId":"1234567"
}

For more information about how to use the API (such as the parameter description), see pay.

Step 4: Return the payment result

After the payment is processed, the MPP must inform the user and Alipay+ of the payment result.

To the user, display the payment result page in the MPP app. For references on how to design the payment result page, see Payment result page.
To Alipay+, return the payment result in the pay API response. Also, use the inquirePayment and the notifyPayment APIs to send the payment result. See Return the payment result for details.