For Mobile Payment Providers (MPPs) who require the communication between the Alipay+ client SDK and the Alipay+ server to be forwarded by the MPP, Alipay+ provides an SDK network proxy solution. This solution allows the MPP to forward the request from Alipay+ client SDK and the response from Alipay+ server.

The following diagram illustrates the flow and procedures of the network proxy solution.

Figure 1. Sequence diagram for the network proxy solution

Alipay+ provides the MPP with two new interfaces:

• An Alipay+ Client SDK API: Alipay+ client SDK uses this interface to send network requests to the MPP server (step 2-4) and receive the response from the MPP server (step 12-13). For detailed information about this interface, see Alipay+ Client SDK API.
• An Alipay+ Server API: The MPP server uses this interface to forward network requests to Alipay+ server (step 8) and receive the response from Alipay+ server (step 11). For detailed information about this interface, see Alipay+ Server API.

The following list describes the procedures in detail:

1. [Client] Step 2: The MPP client needs to implement the API implemented by Alipay+ client SDK.
2. [Client] Step 3: Before sending the request, the MPP client needs to add the MPP login information to the request.
3. [Server] Step4: The MPP server needs to provide another interface to distinguish network requests that are its own or that are sent from Alipay+ client SDK.
4. [Server] Step5: After the MPP server receives the request from Alipay+ client SDK, the MPP server needs to verify the login status to ensure that the user is logged in before calling the Alipay+ server API.
5. [Server] step6-7: When assembling the Alipay+ server API request body, the MPP server needs to put the HTTP header and HTTP body sent by the client side, and the MPP user ID into the request. The MPP server does not need to be aware of the detailed parameters inside the HTTP headers and the HTTP body.
6. [Server] Step8: The MPP server calls the Alipay+ server API to forward the assembled data to Alipay+ server.
7. [Server] Step12: The MPP server exacts the parameters of HTTP header and HTTP body from the response returned by Alipay+ server, and forwards them to the MPP client.
8. [Client] Step13: the MPP client returns the HTTP header and HTTP body to the Alipay+ client SDK.

Alipay+ Client SDK API

For Android

API

The sample code below is a description of the interface.

/**
 * The Network Proxy interface
 */
public interface NetworkProxy{
    /**
     * 
     *
     * Note: for Android it is a synchronous API
     * @param httpProxyRequestInfo    the request, the network proxy information, to be sent by Mobile Payment Providers
     * @return httpProxyResponseInfo  the Mobile Payment Provider needs to convert the data body of the response to HttpProxyResponseInfo object. Otherwise, if the request fails, null is returned.
     * @throws IOException
     */
    @Nullable
    HttpProxyResponseInfo sendHttpRequest(@NonNull HttpProxyRequestInfo httpProxyRequestInfo) throws IOException;
}

How the API works

The following description explains how this interface works:

1. Alipay+ client SDK sends a request with httpProxyRequestInfo that complies with Open API specifications to the MPP server synchronously.

2. The MPP server forwards the request to Alipay+ server.
3. If the request succeeds, the MPP converts the data body of the Alipay+ server response to an HttpProxyResponseInfo object and returns httpProxyResponseInfo.
4. If the request fails, the MPP returns null.

Parameters

Sample code

The sample code below is an implementation example for MPPs.

InitConfig initConfig = new InitConfig();
        initConfig.registerNetworkProxy(ProxyScene.PROXY_SCENE_AC, new NetworkProxy() {
            @Override
            public HttpProxyResponseInfo sendHttpRequest(HttpProxyRequestInfo httpProxyRequestInfo) {
                //this is a sample code for how to use the proxy network.
                HttpURLConnection connection = null;
                URL url = null;
                try {
                    url = new URL("hostUrl");
                    connection = (HttpURLConnection) url.openConnection();
                    if (connection.getResponseCode() == 200) {//if the http request succeeds,fetch body from the response,and assemble an httpProxyResponseInfo.
                        HttpProxyResponseInfo httpProxyResponseInfo = new HttpProxyResponseInfo();
                        httpProxyResponseInfo.setxxx();   //the setxxx function is to configure fields/properties of the request data body.
                        return httpProxyResponseInfo;
                    } else {
                        return null;    //if the http request fails, return null.
                    }
                } catch (Exception e) {
                    e.printStackTrace();
                    return null;
                }
                return null;
            }
        });

For iOS

API

The sample code below is a description of the interface.

@protocol IAPNetworkProxy <NSObject>
- (void)sendProxyRequest:(IAPProxyRequestInfo *)requestInfo 
   withCompletionHandler:(void(^)(IAPProxyResponseInfo *responseInfo))completionHandler;
@end

How the API works

The following description explains how this interface works:

1. Alipay+ client SDK sends a request with requestInfo that complies with Open API specifications to the MPP server asynchronously.
2. The MPP server forwards the request to Alipay+ server.
3. If the request succeeds, the MPP converts the data body of the Alipay+ server response to anIAPProxyResponseInfo object, and the callback functioncompletionHandler returns the asynchronous response responseInfo .
4. If the request fails, the completionHandler returns nil.

Parameters and callback

Sample code

The sample code below is an implementation example for MPPs.

IAPConnectInitConfig *config = [IAPConnectInitConfig new];
config.envType = kIAPACDev;
[config registerNetworkProxy:PSPHttpRequestRegionProxy.new forScene:IAPProxySceneMiniProgram];
[IAPConnect initWithContext:config];

@interface PSPHttpRequestRegionProxy: NSObject <IAPNetworkProxy>
- (void)sendProxyRequest:(IAPProxyRequestInfo *)requestInfo 
   withCompletionHandler:(void(^)(IAPProxyResponseInfo *responseInfo))completionHandler;
@end

@implementation PSPHttpRequestRegionProxy
- (void)sendProxyRequest:(IAPProxyRequestInfo *)requestInfo 
   withCompletionHandler:(void(^)(IAPProxyResponseInfo *responseInfo))completionHandler
{
    NSString *proxyRequestHeader = requestInfo.proxyRequestHeader;
    NSString *proxyRequestData = requestInfo.proxyRequestData;
    // proxyRequestHeader、proxyRequestData as request parameters of the MPP server;
    // The MPP initiates and send a network request to Alipay+ server;
    // Obtain the response, error, data;
    if (error) {
        completionHandler(nil);
    } else {
        // NSDictionary *json = data.toJson;      // convert to JSON
        IAPProxyResponseInfo *responseInfo = IAPProxyResponseInfo.new;
        responseInfo.isSuccess = [json["resultCode"] isEqualToString:@"SUCCESS"]; // example
        if (!responseInfo.isSuccess) {
            responseInfo.errorCode = json["resultCode"];  // example
        } else {
            responseInfo.proxyResponseHeader = json[@"proxyResponseHeader"];    //example
            responseInfo.proxyResponseData = json[@"proxyResponseData"];        //example
        }
        completionHandler(responseInfo);
    }
}
@end

Alipay+ Server API

API

The MPP server uses this interface to communication with Alipay+ server. The following list describes the details about the interface:

• Method: POST
• Path: https://{host}/aps/api/v1/mobile/sdkProxy
• URI: /aps/api/v1/mobile/sdkProxy
• Version: v1
• Expiry time: The expiry time of Alipay+ server API is 10 seconds. The MPP server needs to set its expiry time longer than 10 seconds.

How the API works

Sign a request and validate the signature

To ensure message transmission security, the MPP must properly perform message signing before sending a request and perform signature validation after receiving a response. For how to sign a request and handle a response, see Sign a request and validate the signature.

Request

The MPP server sends the API request to Alipay+ server. The following sample shows the request body which contains the SDK request header and SDK request data from Alipay+ client SDK, and the customer ID.

{
    "sdkRequestHeader": "{\"AppId\":\"WALLET_ID\",\"AppKey\":\"WALLET_ID_ANDROID\",\"workspaceId\":\"default\",\"Content-Type\":\"application/x-www-form-urlencoded\"}",
    "sdkRequestData": "operationType=ap.mobileprod.mcop.wrapper.action&requestData=%5B%7B%22context%22%3A%5B%7B%22bizType%22%3A%22MOBILEAPPLY%22%2C%22campaignId%22%3A%2228100213CAMPAIGN202104161910233172448%22%2C%22requestId%22%3A%2229f40f14-0faa-451e-8545-68e716df282a%22%7D%5D%2C%22envInfo%22%3A%7B%22appId%22%3A%22%22%2C%22appVersion%22%3A%221.33.0-test02-debug%22%2C%22extendInfo%22%3A%7B%7D%2C%22latitude%22%3A%22%22%2C%22locale%22%3A%22en-US%22%2C%22longitude%22%3A%22%22%2C%22miniProgramVersion%22%3A%223.1.0%22%2C%22osType%22%3A%22Android%22%2C%22osVersion%22%3A27%2C%22sdkVersion%22%3A%22%22%2C%22terminalType%22%3A%22miniapp%22%2C%22tokenId%22%3A%22%22%7D%7D%5D&ts=1620471100", 
    "customerId": "20200415111215830128DANAW3ID123000000002"
}

The following table describes the request fields.

Response

Alipay+ server processes the request and return the response to the MPP server. The following sample shows the response body which contains the request processing result, the SDK response header and SDK response data.

{
    "result": "{\"resultCode\":\"SUCCESS\",\"resultMessage\":\"Success\",\"resultStatus\":\"S\"}",
    "sdkResponseHeader": "{\"Server-Time\":\"1626420412668\",\"Mgw-TraceId\":\"0ba767df162642040991643203583\",\"Ac-UserId\":\"210220900000003059489\",\"Result-Status\":\"1000\"}",
    "sdkResponseData": "{\"resultStatus\":\"1000\",\"result\":{\"traceId\":\"0ba767df162642040991643203583\",\"wrapperInvokeResult\":{\"bizInfo\":{\"prizeAwardOrders\":[{\"amount\":{\"amount\":\"10.00\",\"currency\":\"IDR\",\"currencyLabel\":\"Rp\",\"formattedAmount\":\"10.00\",\"value\":\"1000\",\"formattedAmountWithCurrency\":\"Rp 10.00\"},\"awardAssetId\":\"2021071619050111540150000000000102480003542771\",\"prizeType\":\"CUT_OFF_COUPON\",\"awardOrderId\":\"2021071619056122470010000000000102480015887038\",\"extendInfo\":{},\"prizeId\":\"PRIZE202107161910237777183\"}],\"campaignApplyStatus\":\"SUCCESS\",\"campaignApplyId\":\"2021071619056122460010000000000102480027837890\"}},\"success\":true,\"errorActions\":{},\"extendInfo\":{}}}"  
}

The following table describes each the response fields.

Appendix

Data model for Android

public class HttpProxyRequestInfo

public class HttpProxyResponseInfo

public enum ProxyScene

Data model for iOS

public class IAPProxyRequestInfo

public class IAPProxyResponseInfo

public enum IAPProxyScene

Data Model for Alipay+ Server API

Result

Result Code