Integration guide

This topic guides you through how to build an integration to obtain Apple receipts by using the APIs provided by Alipay+.

Workflow

The following figure illustrates the workflow of obtaining Apple receipts.

Figure 1. Workflow of obtaining Apple receipts

The workflow contains the following steps:

1. On the transaction history page in the MPP app, the user selects an Apple transaction and clicks a button to request the corresponding Apple receipt (Steps 1-2).
2. The MPP initiates the user authentication process. Then the user gets authenticated through facial recognition, fingerprint recognition, or one-time password (OTP) verification (Steps 3-4).
3. The MPP generates an authorization code that allows Alipay+ to obtain the MPP customer ID of the user (Step 5).
4. The MPP calls the getBillDetailUrl API to request the Apple receipt URL from Alipay+, which assembles the URL and returns it to the MPP (Steps 6-8).
5. With the Apple receipt URL, the MPP app redirects the user to the Apple receipt page in the app's WebView (Step 9).
6. Apple requests an access token from the Acquiring Service Provider (ACQP), which forwards the request to Alipay+. Alipay+ then calls the applyToken API with the authorization code to request an access token from the MPP (Steps 10-12).
7. The MPP generates an access token and returns it along with the customer ID to Alipay+, which then returns it to Apple through the ACQP (Steps 13-15).
8. Apple verifies the relationship between the customer and the order related to the transaction (Step 16).
9. Apple then renders the receipt page of the order to the user (Step 17).
10. The user clicks the back icon in the upper left corner and gets redirected back to the transaction history page in the MPP app (Steps 18-19).

Step 1. Perform user authentication

After receiving the user's request to view the Apple receipt page, the MPP needs to perform user authentication in either of the following ways: facial recognition, fingerprint recognition, and OTP verification.

Step 2. Generate an authorization code

After the user completes the authentication, the MPP needs to generate an authorization code. It is recommended that the MPP limit the scope of the authorization code to BASE_USER_INFO because Apple only needs the MPP customer ID. With this authorization code, no further confirmation is required from the user when Apple renders the receipt page, thus providing a better user experience.

Step 3. Obtain the Apple receipt URL

To obtain the Apple receipt URL, the MPP needs to send a getBillDetailUrl API request to Alipay+.

Processing logic

• When calling the getBillDetailUrl API, ensure the following parameters are configured properly in the request:

• authCode: Set the value to the authorization code that is generated in Step 2.
• referenceOrderId: Required if the value of the paymentRequestId parameter is empty.
• referenceMerchantId: Required if the value of the paymentRequestId parameter is empty.
• paymentRequestId: Required if the values of the referenceMerchantId and referenceOrderId are both empty.

• The following table lists the different results that the MPP might receive from Alipay+.

Samples

Request

{
  "authCode":"281010132128181282",
  "referenceOrderId": "01202101201212",
  "referenceMerchantId": "2188121221"
}

Response

{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    },
    "acquirerId": "21001221091222",
    "pspId": "212219192",
    "billDetailUrl": "https://www.xx.com/billDetail"
}

More information

For more information about how to call the getBillDetailUrl API request and handle the response, see getBillDetailUrl.

Step 4. Redirect the user to the Apple receipt page

After receiving the Apple receipt URL from Alipay+, the MPP needs to redirect the user to the Apple receipt page by opening the URL in its app's WebView.

To ensure a smooth redirection, the MPP needs to trust the URL specified by the billDetailUrl parameter and complete the redirection without setting a whitelist.

Step 5. Provide the access token and customer id

From the redirection URL that is returned in Step 3, Alipay+ obtains the authorization code (authCode) and specifies it in the applyToken API request to apply for an access token. The MPP needs to provide the access token and customer ID in the response. Apple can then use the access token to access the corresponding user's resources.

Processing logic

When handling the applyToken API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• grantType: When Alipay+ uses the authorization code to apply for a new access token, the value of this parameter is set as AUTHORIZATION_CODE.
• authCode: The authorization code that is generated by the MPP in Step 2.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus: Each authorization code can be used once only. If an authorization code is used for a second time, the MPP needs to return a result.resultStatus of F with error code INVALID_AUTHCODE.

Samples

Request

{
  "acquirerId":"102218800000000001",
  "pspId":"102208800000000001",
  "authCode": "281010133AB2F588D14B432312345678",
  "grantType": "AUTHORIZATION_CODE"
}

Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35",
  "accessTokenExpiryTime": "2022-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811",
  "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
  "customerId":"2789808900000000000000001"
}

More information

For more information about how to handle the applyToken API request and send the response, see applyToken.