Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

Integration

System architecture

The following figure illustrates the solution system architecture. Generally, the 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 transaction system, promotion system, points system, and member management system.

image.png

Figure 1. System architecture of the membership card solution

Integrating with Alipay

Before you start, configure and obtain information that is required for integration, such as the identity information and the secret key. If help needed, contact Alipay Technical Support. 

Calling APIs

The integration with the membership card product consists of three steps:

  1. Create the template of the membership card.
  2. Configure the components of activating the membership card.
  3. Issue the membership card to the customer.

The following graphic shows the substeps of the integration process:

image.png

Figure 2. Substeps of the integration process

Step 1. Creating the template of the membership card

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

image.png

Figure 3. Membership card template

The following information is included in the template of the membership card:

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

会员卡界面_meitu_1.jpg

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. The uploaded image must conform to the following image specifications:
    1. For background images, the file must be within 2 M; the file format must be BMP, PNG, JPEG, JPG, or GIF; the image must be an equilateral rectangle of 1020 * 643 pixels. The image must avoid rounded corners or being stretched or deformed.
    2. For other images, the file must be within 1 M; the file format must be BMP, PNG, JPEG, JPG, or GIF; the image must be an equilateral rectangle of 500 * 500 pixels. 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:

  1. Merchant/ISV creates the membership card template.
  2. Merchant/ISV uploads related graphics to Alipay.

2.1 Alipay checks whether any sensitive information is included in the uploaded images.

  1. Alipay returns image IDs to Merchant/ISV.

3.1 Merchant/ISV constructs the template creation request.

  1. Merchant/ISV sends the template creation request to Alipay.

4.1 Alipay creates the membership card template according to the template provided by Merchant/ISV.

  1. Alipay returns the template ID to Merchant/ISV.

7.1 Merchant/ISV stores the template ID from Alipay and gets the template creation result.

The following graphic shows the process of creating the membership card template:

Figure 5. Membership card template creation process

Step 2. Configuring the components for activating the membership card.

Before the customer can activate the membership card, the customer must authorize to provide information required by the merchant. After the authorization, the customer receives an activation URL where they can activate the membership card.

Therefore, after the merchant creates the membership card template, the merchant needs to configure the components for the membership card activation process. To configure the components of activating the membership card, the merchant must specify the parameters that require customers to authorize, and apply for the card activation URL that will be sent to the customer.

Configuring the fields to be authorized by customers

Use the alipay.marketing.card.formtemplate.set interface to configure the parameters for customers to authorize, which consists of the following steps:

  1. Merchant/ISV configures the component template, which contains the fields to be authorized by the customer.
  2. Merchant/ISV sends the template configuration request to Alipay.

2.1 Alipay checks whether the membership card template ID exists.

2.2 Alipay returns the configuration result to Merchant/ISV.

The following graphic shows the process of configuration:

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.

Applying 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 promotion purpose.

The process of card activation URL application consists of the following steps:

  1. Merchant/ISV sends a request to apply for the card activation URL.

1.1 Alipay returns the activation URL.

The following graphic shows the application process of the card activation URL.

Figure 7. Process to apply for the card activation URL

Step 3. Issuing the membership card to the customer

The merchant might have requested for several membership card templates for different membership card levels, 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 the basic information (such as the external serial number, and membership card template), member information, membership card information and extended information for issuing the membership card.

Issuing the membership card to the customer consists of the following steps:

  1. The customer authorizes to Alipay.

1.1 Alipay redirects the customer to the membership card issuing page.

  1. The customer requests to be issued with a membership card.

2.1 Merchant/ISV gets the authorization information according to the auth_code parameter.

2.1.1 Alipay returns auth_token and userID to ISV.

2.1.1.1 Merchant/ISV checks whether the customer has already received an issued membership card.

2.1.1.2 The customer is redirected to the card binding page. (Optional)

  1. The customer confirms to bind the card. (Optional)

3.1 The customer is redirected to the card issuing page. (Optional)

  1. The customer configures information for being issued with the membership card. (Optional)
  2. The customer sends a request for being issued with the membership card. (Optional)

5.1 Merchant/ISV creates a membership card. (Optional)

  1. Alipay processes the membership card binding by using auth_token provided by Merchant/ISV.

6.1 Alipay checks the user authorization.

6.2 Alipay processes the membership card binding.

6.3 Alipay creates the electronic membership card.

  1. Alipay returns the card issuance result, including the biz_card_no parameter.

7.1 Merchant/ISV saves the biz_card_no parameter.

7.2 Merchant/ISV returns the result of issuing the membership card.

The following graphic shows the card issuance process:

Figure 8. Card issuance process