Integration

The following sections explain how to design your system and integrate with Alipay.

System architecture

The Alipay membership card solution contains two parts:

• The front end system, composed of an entrance that brings the customer to the service and the POS system or ECR cash register system.
• The back end system, composed of the transaction system, promotion system, points system, and member management system.

The following figure illustrates the solution system architecture:

Figure 1. System architecture of the membership card solution

Integrating with Alipay

Before you begin the Alipay integration, configure and obtain information that is required for integration, such as the identity information and secret key. Contact Alipay Technical Support at AlipayGlobalTechService@service.alipay.com if you need help.

Calling APIs

The integration with the Alipay membership card solution consists of three steps:

1. Create the membership card's template.
2. Configure the components for membership card activation.
3. Issue the membership card to the customer.

The following graphic shows the entire integration process, including its sub-steps:

Figure 2. The membership card integration process

Step 1: Create the membership card's template

Use the alipay.marketing.card.template.create interface to create membership card's template. The following graphic shows the components of the membership card template:

Figure 3. Membership card template

The following information is included in the membership card's template:

• Basic information, such as the membership card name, membership card type, and redemption method.
• Format information, such as the display mode of the membership card on the membership card page.
• Member benefits. The member benefits defined in the membership card template are general benefits, which will be inherited by all the issued membership cards defined by the template.
• Column information list that contains membership card functions, which is to be presented on the membership card page.
• Rules for the fields of the membership card, which are mainly used for explaining how to parse the membership card information from the request parameters in the card creation process.

The following graphic shows the locations to present the parameter values on the virtual membership card and related explanations about the parameters.

Figure 4. Fields on the membership card

Notes:

• The request_id parameter is the unique identifier of the request, of which the uniqueness must be guaranteed.
• The logo_id and background_id parameters can be obtained by the Alipay image upload interface alipay.offline.material.image.upload.
• In the process of creating the membership card template, the merchant also needs to use the alipay.offline.material.image.upload interface to upload images that will be used in the membership card. Uploaded images must adhere to the following image specifications:

1. Background image:

1. The file must be within 2 MB.
2. The file format must be BMP, PNG, JPEG, JPG, or GIF.
3. The image must be an equilateral rectangle of 1020 x 643 pixels.
4. The image must not have rounded corners, stretched, or deformed.

2. Other images:

1. The file must be within 1 MB.
2. The file format must be BMP, PNG, JPEG, JPG, or GIF.
3. The image must be an equilateral rectangle of 500 x 500 pixels.
4. The merchant logo is preferred.

The process of using the alipay.marketing.card.template.create interface to create the membership card template involves the merchant or independent software vendor (ISV), and Alipay. The following graphic shows the process of creating the membership card template:

Figure 5. Membership card template creation process

Note:

• In step 2.1, Alipay checks whether any sensitive information is included in the uploaded images.
  
  

Step 2: Configure the components for membership card activation

As the customer needs to authorize information required by the merchant before receiving a membership card activation URL, the merchant must configure the components that contain fields to be authorized by the customer.

The merchant must first specify the parameters that require the customer's authorization, then apply for the card activation URL that will be sent to the customer.

Configure fields to be authorized by customers

Use the alipay.marketing.card.formtemplate.set interface to configure the parameters for customers to authorize. The following graphic shows the configuration process:

Figure 6. Process to configure the fields to be authorized by customers

Note:

The template_id parameter is the membership card template ID, which is returned when the membership card template is created.

Apply for the card activation URL

Use the alipay.marketing.card.activateurl.apply interface to get the membership card activation URL. The activation URL can be presented in the Alipay Life Style Account Platform, mini program, and in-store QR code for promotional purpose.

The following graphic shows the membership card activation URL application process:

Figure 7. Process to apply for the card activation URL

Step 3: Issue the membership card to the customer

The merchant might have requested for several membership card templates for different membership card levels, and the issued membership cards for different levels must follow the corresponding template by using the specific template ID.

For physical membership cards that have already been issued to customers, the merchant can also use the alipay.marketing.card.open interface to digitalize the issued membership cards. In this way, the membership card can be presented in the e-wallet and the related information can be saved to the Alipay system.

Use the alipay.marketing.card.open interface to send a membership card issuance request. The request mainly includes:

• Basic information such as the external serial number and membership card template
• Member information
• Membership card information
• Extended information for issuing the membership card

The following graphic shows the card issuance process:

Figure 8. Card issuance process

Note:

• In step 2.1, The merchant/ISV gets the authorization information according to the auth_code parameter.