Alipay+ ACQP iOS SDK interfaces

The following sections introduce the interfaces that are provided by the Alipay+ ACQP iOS SDK.

Note: The payment sheet mentioned in the following sections is also known as the Alipay+ checkout page.

1. Overview

This section describes the interfaces that are used in the interaction between the SDK and your project.

1.1 API（ACQP -> SDK）

Interface name	Description
setConfiguration	Set up the SDK.
inquirePaymentOption	Inquire about the availability of and how to render the Alipay+ payment method on the payment method page.
showPaymentSheet	Show the payment sheet for the user to complete the payment.

1.2 SPI (SDK -> ACQP)

Interface name	Description
log	Provide a delegate that you can use to log the user behavior or exceptions.

2. APIs

setConfiguration

Use this API to set up the SDK with required configurations before you use other APIs. The configuration is stored in the RAM and may be used in the internal logic of the other APIs.

Method signature

copy

@Interface AlipayPlusClient:NSObject
@property (nonatomic, strong) IAPConfiguration *configuration;
- (void)setConfiguration:(IAPConfiguration *)configuration;

Input parameters

Name

Type

Length

Description

Required

configuration

IAPConfiguration

An object that includes the parameters for setting up the SDK.

See IAPConfiguration for details.

Sample code

copy

IAPConfiguration *configuration = IAPConfiguration.new;
configuration.envType = @"PROD";
configuration.acquirerId = @"xxx";
configuration.merchantId = @"yyy";
configuration.language = @"zzz";
[[AlipayPlusClient shared] setConfiguration:configuration];

inquirePaymentOption

Use this API to inquire whether the Alipay+ payment method is available and if so, related data about the Alipay+ payment method, such as the Alipay+ logo information and promotion information.

Method signature

copy

@Interface AlipayPlusClient:NSObject
- (void)inquirePaymentOption:(IAPInquirePaymentOptionParams *)params
           completionHandler:(void(^)(IAPPaymentOption *paymentOption, NSError *error))completionHandler;
@end

Input parameters

Name

Type

Length

Description

Required

params

IAPInquirePaymentOptionParams

An object that contains the parameters for querying the data about the Alipay+ payment method.

completionHandler

Block

(void(^)(IAPPaymentOption *paymentOption, NSError *error)

A block that is used to return the query result.

parameters in completionHandler

Name

Type

Length

Description

Required

paymentOption

IAPPaymentOption

The data about the Alipay+ payment method.

This parameter is returned if the inquiry is successful.

error

NSError

The error information about the inquiry.

This parameter is returned if the inquiry failed.

Sample code

copy

IAPInquirePaymentOptionParams *params = IAPInquirePaymentOptionParams.new;
params.paymentCurrency = @"PHP";
params.logoPattern = @"YYY";
[[AlipayPlusClient shared] inquirePaymentOptionWithParams:params 
completionHandler:^(IAPPaymentOption *paymentOption, NSError *error) {
    if (!error && paymentOption.enabled) {
       
    } else {
    }
}

showPaymentSheet

Use this API to show the payment sheet for the user to complete the payment. During the lifecycle of the payment sheet, you can receive callbacks about key events, such as when the user clicks the cancel button or when the user clicks the Pay Now button.

Method signature

copy

@Interface AlipayPlusClient:NSObject
- (void)showPaymentSheet:(NSString *)paymentData 
                        callback:(void(^)(IAPPaymentSheetEvent *sheetEvent))callback;

@end

Input parameters

Name

Type

Length

Description

Required

paymentData

NSString

The payment data that is used for rendering the payment sheet.

callback

Block

(void(^)(IAPPaymentSheetEvent *sheetEvent))

A block is used to return the status of the payment sheet.

params in completionHandler

Name	Type	Length	Description	Required
sheetEvent	IAPPaymentSheetEvent	/	An object that describes the event that occurred when the status of the payment sheet changed.	O

Sample code

copy


[[AlipayPlusClient shared] showPaymentSheetWithData:@"xxx"
callback:^(IAPPaymentSheetEvent *sheetEvent) {
    if ([sheetEvent.name isEqualToString:IAPPaymentSheetEventDidSelectWalletAndPay]) {
        // your own logic
    }
}

3. SPIs (SDK -> ACQP)

log

Implement this SPI to log the user behavior or exceptions during the interaction between the user and the SDK.

Method signature

copy

@protocol IAPLogServiceProtocol 

- (void)logWithName:(NSString *)name parameter:(NSDictionary *)parameter;

@end

Input parameters

Parameters

Name	Type	Length	Description
name	String	/	The name of the behavior or exception.
parameter	Map	/	The extra information.

Output parameters

N/A

Sample code

copy

@interface YOUR_LOG_SERVICE_CLASS: NSObject <IAPLogServiceProtocol>
- (void)logWithName:(NSString *)name parameter:(NSDictionary *)parameter;
@end

@implementation YOUR_LOG_SERVICE_CLASS
- (void)logWithName:(NSString *)name parameter:(NSDictionary *)parameter {
// your logic
}
@end

copy

[AlipayPlustClient shared].logService = YOUR_LOG_SERVICE_CLASS.new

4. Appendices

public class IAPConfiguration

Item	Type	Description	Required
merchantId	String	The unique ID that is assigned by the ACQP to identify a merchant. Note: The value of this parameter must be the same as the one that is specified when calling the pay API.	M
acquirerId	String	The unique ID that is assigned by Alipay+ to identify an ACQP.	M
language	String	The language that is preferred by the user. The value of the parameter consists of a language code following the ISO-639 standard and a country code following the ISO-3166 standard. The codes are connected by an underscore. For example, `en_US`. The default value is `en_US`. Valid values are: zh_CN: Simplified Chinese zh_HK: Traditional Chinese en_US: English ko_KR: Korean fil_PH: Filipino ms_MY: Malay id_ID: Indonesian th_TH: Thai Note: If a valid value is specified for the language parameter, the specified language is used. Otherwise, the English language is used.	O
envType	String	The type of environment where the SDK is installed. The value of this parameter affects the gateway address of the requests that are initiated from the SDK. Valid values: `PROD`: indicates the production environment. `SANDBOX`: indicates the sandbox environment. Default value: `RPOD`	O

public class IAPInquirePaymentOptionParams

Item

Type

Description

Required

paymentCurrency

String

The payment currency that is supported by the merchant.

The value of this parameter must be an alphabetic code that follows the ISO 4217 standard, for example, "EUR" for Euros.

logoPattern

String

The pattern of the logo, such as P1-WEB-01. The value consists of the following three parts:

The layout of the logo. Valid values are:

P1: indicates that the Alipay+ logo is located on the left of wallet logos.
P2: indicates that the Alipay+ logo is above wallet logos.

The terminal type that the logo is applied to. Valid values are WEB and APP.
Custom field with a maximum length of 10 characters. The default values are sequential numbers starting from01.

public class IAPPaymentOption

Item	Type	Description	Required
enabled	boolean	Indicates whether the Alipay+ payment method is available.	M
logos	Array<IAPLogo>	The logo information of the Alipay+ payment method. Note: Nullable if the value of the enabled parameter is `false`.	O
brandName	String	The brand name of the Alipay+ payment method. Note: Nullable if the value of the enabled parameter is `false`.	O
disableReason	String	The reason why the Alipay+ payment method is unavailable. Note: The value of this parameter is null if the value of the enabled parameter is `true`.	O
paymentMethodType	String	The payment method that is provided by Alipay+. Valid values are: `CONNECT_WALLET`: indicates the Alipay+ payment method.	M
promoNames	Array<String>	The list of promotion campaigns in the language that is preferred by the user. Each element in the array is a string that indicates the promotion name, such as `RM1 Voucher`. Currently, the array contains only one element indicating one specific promotion campaign, which is the best offer that Alipay+ recommends to be displayed alongside the logo, rather than multiple different promotion campaigns.	O

public class IAPLogo

Item	Type	Description	Required
logoName	String	The name of the logo.	O
logoUrl	String	The URL of the logo.	O
logoPattern	String	The pattern of the logo, such as `P1-WEB-01`. The value consists of the following three parts: The layout of the logo. Valid values are: `P1`: indicates that the Alipay+ logo is located on the left of wallet logos. `P2`: indicates that the Alipay+ logo is above wallet logos. The terminal type that the logo is applied to. Valid values are `WEB` and `APP`. Custom field with a maximum length of 10 characters. The default values are sequential numbers starting from`01`.	O
logoWidth	String	The width of the logo.	O
logoHeight	String	The height of the logo.	O

public class IAPPaymentSheetEvent

Item	Type	Description	Required
name	String(constant value)	The name of the event that occurred in the lifecycle of the payment sheet.	M
message	String	The message that is related to the event.	O

constant values and possible messages

constant value	Description
IAPPaymentSheetEventDidSelectWalletAndPay	The event where the user selected an MPP and clicked Pay Now to get redirected to the MPP app or WAP page.
IAPPaymentSheetEventThrowException	The event where an exception is thrown.
IAPPaymentSheetEventUserDidCancel	The event where the user clicked Close to cancel the payment.
IAPPaymentSheetEventDidShow	The event where the payment sheet was successfully rendered.

ErrorCode

Error code	Error message	Description
1001	PARAM_ILLEGAL	Illegal parameters exist.
1002	INVALID_NETWORK	A network error occurs.
1003	SYSTEM_ERROR	A system error occurs.