Alipay+Alipay+

APIs for Network Proxy Solution

For Mobile Payment Partners (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.

image.png

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.

copy
/**
 * 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 Partners
     * @return httpProxyResponseInfo  the Mobile Payment Partner 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.
  1. The MPP server forwards the request to Alipay+ server.
  2. If the request succeeds, the MPP converts the data body of the Alipay+ server response to anHttpProxyResponseInfo object and returns httpProxyResponseInfo.
  3. If the request fails, the MPP returns null.

Parameters

Input Parameter Name

Android Type

Description

Required

httpProxyRequestInfo 

HttpProxyRequestInfo 

The request that is sent by Alipay+ client SDK, including the business type, the header, and the data body.

M

Output Parameter Name

Android Type

Description

Required

httpProxyResponseInfo 

HttpProxyResponseInfo 

The response that is returned by the MPP server.

If the request fails, the MPP returns null.

M

Sample code

The sample code below is an implementation example for MPPs.

copy
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.

copy

@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

Input parameter name

iOS Type

Description

Required

requestInfo 

IAPProxyRequestInfo

The request that is sent by Alipay+ client SDK, including the business type, the header, and the data body.

M

Output parameter name

iOS Type

Description

Required

responseInfo 

IAPProxyResponseInfo

The response that is returned by the MPP server.

M

Callback function

iOS Type

Description

Required

completionHandler 

Block  

An asynchronous callback. After the request succeeds, the completionHandler sends the response back to Alipay+ client SDK.

If the request fails, the completionHandler returns nil.

M

Sample code

The sample code below is an implementation example for MPPs.

copy

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.

copy
{
    "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.

Name

Required

Type

Description

sdkRequestHeader

M

String

The SDK request header.

sdkRequestData

M

String

The SDK request data body.

customerId

M

String

The unique ID that is assigned by the MPP to identify a customer.

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.

copy
{
    "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.

Name

Required

Type

Description

result

M

String

The request processing result, which contains information such as result code, result status and result message. See Result for details.

sdkResponseHeader

O

String

The SDK response header.

sdkResponseData

O

String

The SDK response data body.

Appendix

Data model for Android

public class HttpProxyRequestInfo

Item

Type

Description

Required

scene 

ProxyScene

The business scenario of the Alipay+ client SDK request.

M

httpProxyRequestHeader 

String

The header of the Alipay+ client SDK request.

M

httpProxyRequestData 

String

The data body of the Alipay+ client SDK request.

M

public class HttpProxyResponseInfo

Item

Type

Description

Required

isSuccess 

Boolean

The result status that is returned from Alipay+:

  • true : indicates the request succeeds.
  • false : indicates the request fails.

M

errorCode 

String

The result code that is returned by Alipay+ server.

errorMessage 

String

The result message that is returned by Alipay+ server.

httpProxyResponseHeader 

String

The SDK header information that is returned by Alipay+ server.

M

httpProxyResponseData 

String

The SDK data body that is returned by Alipay+ server.

M

public enum ProxyScene

Item

Description

PROXY_SCENE_MINIPROGRAM 

Indicates a specific business scenario (mini-program scenario) of a network request proxy.

When a request needs to access only the Alipay+ regional server, the request is transferred to the designated network proxy that is registered under this scenario.

PROXY_SCENE_PAY 

Indicates a specific business scenario (payment scenario) of a network request proxy.

If a network proxy is registered under this scenario, the request is transferred to this network proxy.

Data model for iOS

public class IAPProxyRequestInfo

Item

Type

Description

Required

scene 

IAPProxyScene

The business scenario of the Alipay+ client SDK request.

M

proxyRequestHeader 

String

The header of the Alipay+ client SDK request.

M

proxyRequestData 

String

The data body of the Alipay+ client SDK request.

M

public class IAPProxyResponseInfo

Item

Type

Description

Required

isSuccess 

Boolean

The result status that is returned from Alipay+:

  • true : indicates the request succeeds.
  • false : indicates the request fails.

M

errorCode 

String

The result code that is returned by Alipay+ server.

O

errorMessage 

String

The result message that is returned by Alipay+ server.

O

proxyResponseHeader 

String

The SDK header information that is returned by Alipay+ server.

M

proxyResponseData 

String

The SDK data body that is returned by Alipay+ server.

M

public enum IAPProxyScene

Item

Description

IAPProxySceneMiniProgram 

Indicates a specific business scenario (mini-program scenario) of a network request proxy.

When a request needs to access only the Alipay+ regional server, the request is tranferred to the designated network proxy that is registered under this scenario.

IAPProxyScenePay 

Indicates a specific business scenario (payment scenario) of a network request proxy.

If a network proxy is registered under this scenario, the request is tranferred to this network proxy.

Data Model for Alipay+ Server API

Result

Item

Required

Description

resultCode

M

See Result Code for details.

resultStatus

M

The Result status. Valid values are:

  • S indicates the request succeeds
  • F indicates the request fails
  • U  indicates the result status is unknown

resultMessage

O

The result message that describes the result code in detail.

Result Code

resultCode

resultStatus

resultMessage

SUCCESS

S

Success

ACCESS_DENIED

F

Access is denied.

INVALID_API

F

The called API is invalid or not active.

INVALID_CLIENT

F

The client is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

KEY_NOT_FOUND

F

The key is not found.

MEDIA_TYPE_NOT_ACCEPTABLE

F

The server does not implement the media type that is acceptable to the client.

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTPS method.

PARAM_ILLEGAL

F

Illegal parameters. For example, non-numeric input, invalid date.

PROCESS_FAIL

F

A general business failure occured. Do not retry.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

UNKNOWN_EXCEPTION

U

An API call failed, which is caused by unknown reasons.