alipay.marketing.card.formtemplate.set

2020-10-16 11:40

Use this interface to configure the parameters for customers to authorize.

#Request

#Service address

Environment	HTTPS request URL
Production environment	https://openapi.alipay.com/gateway.do

#Request parameters

Parameter

Description

Basic parameter

app_id

String (32) Required

The unique ID that is assigned by Alipay to identify an app

Example:2014072300007148

method

String (128) Required

The interface name

Example:alipay.marketing.card.formtemplate.set

format

String (40)

Only JSON is supported.

Example:JSON

charset

String (10) Required

The charset with which the request data are encoded. UTF-8, GBK, and GB2312 are supported.

Example:UTF-8

sign_type

String (10) Required

The signature algorithm used by the merchant to generate the pre-sign string. RSA and RSA2 are supported. RSA2 is preferred.

Example:RSA2

sign

String (344) Required

The signature value. See Signature for details.

Example:2118ac8fad6bc1d9e88a6cd017c18d37

timestamp

String (19) Required

The time when the request is sent. The format is yyyy-MM-dd HH:mm:ss.

Example:2014-07-24 03:07:50

version

String (3) Required

The interface version. The value is fixed as 1.0.

Example:1.0

biz_content

Required

Collection of request parameters. The maximum length is not limited. Except for common parameters, all other request parameters must be passed in to this parameter.

Business parameter

template_id

String (128) Required

The ID that is assigned by Alipay to identify a membership card template. The value is the same as that of template_id returned by Alipay in the template creation interface.

Example:20170228000000000210102000300974

fields

OpenFormFieldDO

Specifies the required or optional information for users to authorize when issuing the membership card. Multiple common fields can be defined, which are contained in the array common_fields. The number of common fields cannot exceed 20. For more information, see fields.

Example:[OPEN_FORM_FIELD_MOBILE,OPEN_FORM_FIELD_GENDER]

#fields

Parameter

Description

required

String (10240)

Specifies the information that users must authorize, by including corresponding values in the array common_fields. Possible values are :

OPEN_FORM_FIELD_MOBILE: mobile phone number
OPEN_FORM_FIELD_GENDER: gender
OPEN_FORM_FIELD_NAME: name
OPEN_FORM_FIELD_BIRTHDAY: birthday with the format MM-dd
OPEN_FORM_FIELD_BIRTHDAY_WITH_YEAR: birthday with the format yyyy-MM-dd
OPEN_FORM_FIELD_IDCARD: ID card
OPEN_FORM_FIELD_CERT_TYPE: ID type
OPEN_FORM_FIELD_CERT_NO: ID number
OPEN_FORM_FIELD_EMAIL: email address
OPEN_FORM_FIELD_ADDRESS: address
OPEN_FORM_FIELD_CITY: city
OPEN_FORM_FIELD_IS_STUDENT: indicates whether the user is a student
OPEN_FORM_FIELD_MEMBER_GRADE: membership card level

Notes:

If the values of OPEN_FORM_FIELD_IS_STUDENT and OPEN_FORM_FIELD_MEMBER_GRADE cannot be obtained, the two fields are not displayed.
OPEN_FORM_FIELD_IDCARD cannot be included in the array with OPEN_FORM_FIELD_CERT_TYPE and OPEN_FORM_FIELD_CERT_NO at the same time.
If OPEN_FORM_FIELD_IDCARD cannot meet the business requirements, use OPEN_FORM_FIELD_CERT_TYPE and OPEN_FORM_FIELD_CERT_NO. Supported ID types are ID card, passport, Mainland Travel Permit for Hong Kong and Macao Residents, and Mainland Travel Permit for Taiwan Residents.

Example:{"common_fields":["OPEN_FORM_FIELD_MOBILE"]}

optional

String (10240)

Specifies information that is optional for users to authorize, by including corresponding values in the array common_fields.

Possible values are same as that of the required field. This field cannot contain values that already exist in the required field.

Example:{"common_fields":["OPEN_FORM_FIELD_GENDER"]}

#Response

Parameter

Description

Basic parameter

code

String Required

Gateway return code, which indicates whether the request is accepted by Alipay gateway.

Example:40004

msg

String Required

Description of the gateway return code

Example:Business Failed

sub_code

String

Processing result of the request

Example:ACQ.TRADE_HAS_SUCCESS

sub_msg

String

Description of the processing result of the request

Example:Payment for the transaction is completed.

sign

String Required

The signature value. See Signature for details.

Example:DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

#Error codes

Error code	Description	Solution
INVALID_PARAMETER	Incorrect parameters	Check if the request parameters are correct.
SYSTEM_ERROR	Alipay system error	Try again.
CARD_TEMPLATE_NOT_EXIST	The membership card template does not exist.	Check if the value of template_id is correct.
DUPLICATE_FORM_FIELD	Duplicate fields exist in the fields parameter.	Avoid duplication in the required field and the optional field of the fields parameter.
FORM_FIELD_INVALID	Invalid values exist in the `fields` parameter.	Use correct values in the `fields` parameter.
OPEN_FORM_SET_FAIL	Failed to configure the parameters to be authorized	Try again later.
DUPLICATE_BIRTHDAY_FIELD	OPEN_FORM_FIELD_BIRTHDAY and OPEN_FORM_FIELD_BIRTHDAY_WITH_YEAR cannot exist at the same time.	Use OPEN_FORM_FIELD_BIRTHDAY or OPEN_FORM_FIELD_BIRTHDAY_WITH_YEAR only.
DUPLICATE_CERT_NO	OPEN_FORM_FIELD_CERT_NO and OPEN_FORM_FIELD_IDCARD cannot exist at the same time.	Use OPEN_FORM_FIELD_CERT_NO or OPEN_FORM_FIELD_IDCARD only.
INVALID_CERT_TYPE_AND_NO	OPEN_FORM_FIELD_CERT_TYPE and OPEN_FORM_FIELD_CERT_NO must exist at the same time.	Use both OPEN_FORM_FIELD_CERT_TYPE and OPEN_FORM_FIELD_CERT_NO.

#Sample

#Request sample

Java

copy

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCardFormtemplateSetRequest request = new AlipayMarketingCardFormtemplateSetRequest();
request.setBizContent("{" +
"\"template_id\":\"20170228000000000210102000300974\"," +
"\"fields\":{" +
"\"required\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_MOBILE\\\"]}\"," +
"\"optional\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_GENDER\\\"]}\"" +
"}" +
"}");
AlipayMarketingCardFormtemplateSetResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("The calling succeeds.");
} else {
System.out.println("The calling is failed.");
}

.NET

copy

IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
AlipayMarketingCardFormtemplateSetRequest  request= new AlipayMarketingCardFormtemplateSetRequest() ;
request.BizContent="{" +
"\"template_id\":\"20170228000000000210102000300974\"," +
"\"fields\":{" +
"\"required\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_MOBILE\\\"]}\"," +
"\"optional\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_GENDER\\\"]}\"" +
"}" +
"}";
AlipayMarketingCardFormtemplateSetResponse response=client.execute(request);
Console.WriteLine(response.Body);

PHP

copy

$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->appId = 'your app_id';
$aop->rsaPrivateKey = 'Please fill in the developer's private key in a line of string, removing the head, tail, and carriage return';
$aop->alipayrsaPublicKey='Please fill in Alipay public key in a line of string';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new AlipayMarketingCardFormtemplateSetRequest ();
$request->setBizContent("{" .
"\"template_id\":\"20170228000000000210102000300974\"," .
"\"fields\":{" .
"\"required\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_MOBILE\\\"]}\"," .
"\"optional\":\"{\\\"common_fields\\\":[\\\"OPEN_FORM_FIELD_GENDER\\\"]}\"" .
"}" .
"}");
$result = $aop->execute ( $request); 

$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "Success";
} else {
echo "Fail";
}

HTTP request source code

copy

https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.marketing.card.formtemplate.set&app_id=4800&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content=
  {
"template_id":"20170228000000000210102000300974",
"fields":{
"required":"{\"common_fields\":[\"OPEN_FORM_FIELD_MOBILE\"]}",
"optional":"{\"common_fields\":[\"OPEN_FORM_FIELD_GENDER\"]}"
    }
  }


//To ensure a secure communication, verify whether the sign value in the response sample is provided by Ant Financial.

#Response sample

JSON

copy

{
    "alipay_marketing_card_formtemplate_set_response": {
        "code": "10000",
        "msg": "Success"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

XML

copy

<alipay_marketing_card_formtemplate_set_response>
<code>10000</code>
<msg>Success</msg></alipay_marketing_card_formtemplate_set_response>

#Exception sample

JSON

copy

{
    "alipay_marketing_card_formtemplate_set_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "The system is busy."
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}