Third-party Developer Mode

  1. Merchants whose Official Accounts are verified can use their Official Accounts to apply for the Cards & Offers feature, and then authorize the developer via "Official Account Login Authorization" on the Weixin Open Platform to develop and apply this feature. The card/coupon data and membership belong to the merchants' Official Accounts. This mode is referred to as "common authorization" without development APIs. You can just refer to all basic card/coupon APIs.

  2. To reduce the access cost for merchants who do not have Official Accounts, they can access the Cards & Offers feature via third-party endorsement. The company of the developer endorses the credit of sub-merchants and can help them create cards/coupons. This simplified developer mode is called "Entrusted Card/Coupon Creation Mode" (see introduction and guide documentation). Additional APIs are required in this mode. See the following API documentation.

Contents 1 Entrusted Card/Coupon Creation Mode

1.1 Creating Sub-merchants

1.2 Sub-merchant Approval Event

1.3 Querying Supported Card/Coupon Categories

1.4 Updating Sub-merchants

1.5 Pulling Single Sub-merchant's Information

1.6 Pulling Sub-merchants' Information in Batch

1.7 Creating Cards/Coupons for Sub-merchants

1.8 Error Codes

1.9 Contact Us

# 1. Entrusted Card/Coupon Creation Mode

Overview

To make it easy for merchants to access the Cards & Offers feature, Weixin Official Accounts Platform provides the "Entrusted Card/Coupon Creation" feature to Official Accounts who have accessed the Cards & Offers feature. After applying for and enabling this feature, developers can help merchants without Official Accounts quickly access and use the Cards & Offers feature via API. Developers who assist in creating cards/coupons are "parent merchants" and merchants receiving the assistance are "sub-merchants".

The parent merchant should upload the information of their sub-merchants and report it for approval in advance. The parent merchant can select a sub-merchant from the list of reported sub-merchants to help it create cards/coupons.

How to Enable

  1. Application path: Weixin Official Accounts Platform > Cards & Offers > Merchant Info in the upper right corner > Entrusted Card/Coupon Creation Mode.

  2. The merchant submits the information and qualifications of a sub-merchant via Weixin Official Accounts Platform or API for approval. Once approved, the information of the sub-merchant can be used to create cards/coupons.

  3. Fields specific to the mode are required when calling API to create a card/coupon. For more information, see response fields of the "Create Sub-merchant" API. In this mode, only the "Create Card/Coupon" API is changed, and other APIs and rest card/coupon APIs can be used as usual. See Homepage for details.

# 1.1 Creating Sub-merchants

API Description

The parent merchant can call this API to pass the information of the sub-merchant, and get the sub-merchant ID to manage the Cards & Offers feature for the sub-merchant. Qualifications of the sub-merchant include merchant name, merchant logo (image), card/coupon category, authorization letter (scanned copy or color photocopy), and the expiration time of the authorization letter.

API details

HTTP request method: POST URL:https://api.weixin.qq.com/card/submerchant/submit?access_token=TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example

{
 "info": {
 "brand_name": "aaaaaa",
 "app_id": "xxxxxxxxxxx",
 "logo_url": "http://mmbiz.xxxx",
 "protocol": "xxxxxxxxxx",
 "agreement_media_id":"xxxxxxxxxx",
 "operator_media_id":"xxxxxxxx",
 "end_time": 1438990559,
 "primary_category_id": 1,
 "secondary_category_id": 101
 }
}

Fields

Parameter Required Type Example Description
info Yes JSON structure
app_id No String(36) wxxxxxxxxxxx Official Account's app_id of sub-merchant, which is used on the sub-merchant's cards/coupons once configured. Note that this app_id must be verified.
brand_name Yes String(36) 兰州拉面 (Lanzhou Lamian) Sub-merchant name (up to 12 Chinese characters or 24 English characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Yes string(128) http://mmbiz.xxxx Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
protocol Yes String(36) mdasdfkl Authorization letter ID, which is the media_id obtained after the authorization letter is uploaded via the "Upload Temporary Asset" API.
end_time Yes unsigned int 15300000 The expiration time (UTC+8, in sec) of the authorization letter, which should be the time on the submitted scanned copy.
primary_category_id Yes int 2 Primary category ID, which can be queried via the API hereof.
secondary_category_id Yes int 2 Secondary category ID, which can be queried via the API hereof.
agreement_media_id No string(36) 2343343424 Color photocopy or scanned copy of Business License or Individual Business License
operator_media_id No string(36) 2343343424 Color photocopy or scanned copy of ID card of the operator registered in the Business License

Note: Download the authorization letter in Entrusted Card/Coupon Creation Mode Guide, fill in the letter manually, affix it with the original stamp, and upload the scanned color copy or color photocopy of the letter.

1. The authorization letter must be affixed with the company's official seal, or the store seal of individual business, special invoice seal, financial seal, contract seal, and other legally binding seals. Personal seals are not allowed.

2. If the sub-merchant is an individual business operator without any of the above seals, the authorization letter can be signed by the individual business operator, and the color photocopies of Individual Business License and ID card of the operator registered in the license should also be uploaded. (The official seal must be affixed in the authorization letter in other scenarios)

3. If the sub-merchant has an Official Account and is unwilling to operate it on its own, it can authorize a third party to create cards/coupons and configure its Official Account. After the configuration, (1) there is no quota for card/coupon creation; (2) the Official Account linked to the details page of a card/coupon is the one configured for the sub-merchant.

Response Data

{
"info": {
 "merchant_id": 12,
 "app_id":"xxxxxxxxxxxxx",
 "create_time": 1438790559,
 "update_time": 1438790559,
 "brand_name": "aaaaaa",
 "logo_url": "http://mmbiz.xxxx",
 "status": "CHECKING",
 "begin_time": 1438790559,
 "end_time": 1438990559,
 "primary_category_id": 1,
 "secondary_category_id": 101
}
}

Note:

Parameter Description
merchant_id Sub-merchant ID, which is unique under a parent merchant's Official Account.
app_id If the sub-merchant has an Official Account and is unwilling to operate it on its own, it can authorize a third party to creating cards/coupons and configure its Official Account. After the configuration, (1) there is no quota for card/coupon creation; (2) the Official Account linked to the details page of a card/coupon is the one configured for the sub-merchant.
create_time Creation time of sub-merchant information
update_time Update time of sub-merchant information
brand_name Sub-merchant name (up to 12 Chinese characters or 24 Engish characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
status Sub-merchant status. "CHECKING": Under review; "APPROVED": Approved; "REJECTED": Rejected; "EXPIRED": Protocol has expired
bengin_time Creation time (not the start time of the protocol)
end_time The expiration time (UTC+8, in sec) of the authorization letter
primary_category_id Primary category of sub-merchant
secondary_category_id Secondary category of sub-merchant

If the sub-merchant's information is submitted via the Weixin Official Accounts Platform, the sub-merchant ID can be found in Cards & Offers > Sub-merchant Management > Sub-merchant Details on the Weixin Official Accounts Platform, or returned via the "Create Sub-merchant" API, or obtained via the "Pull Sub-merchant Information" API.

# 1.2 Sub-merchant Approval Event

After the sub-merchant who use developer as its proxy is approved, it will receive an event pushed from the Weixin server.

<xml> 
  <ToUserName><![CDATA[toUser]]></ToUserName>  
  <FromUserName><![CDATA[FromUser]]></FromUserName>  
  <CreateTime>123456789</CreateTime>  
  <MsgType><![CDATA[event]]></MsgType>  
  <Event><![CDATA[card_merchant_check_result]]></Event>  
  <MerchantId>0</MerchantId>  
  <IsPass>1</IsPass>  
  <Reason><![CDATA[reason]]></Reason> 
</xml>

Fields

Parameter Description
ToUserName Developer's Weixin ID
FromUserName Event pusher ID (OpenID)
CreateTime Creation time of message (integral)
MsgType Message type (event)
Event Event type (card_merchant_check_result, i.e. sub-merchatn approval event)
MerchantId Sub-merchant ID
IsPass Indicates whether the sub-merchant is approved (1: Approved)
Reason Reason for rejection

# 1.3 Querying Supported Card/Coupon Categories

API Description

This API is called to query the supported card/coupon category ID. The category changes with business development. Always use this API to get the latest card/coupon category.

Notes:

  1. Card/Coupon qualification ID is also returned via this API. The qualification is required when the Official Account who has completed the Weixin Verification applies for the Cards & Offers feature via the Weixin Official Accounts Platform.

  2. In the third-party developer proxy (without Official Account) mode, the returned qualification is not required, regardless of the category selected by the sub-merchant. For the return value, refer to category ID.

API details

API Request Format

HTTP request method: GET URL:https://api.weixin.qq.com/card/getapplyprotocol?access_token=TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
GET data Yes JSON data

Response Data


{
   "category": [
       {
           "primary_category_id": 1,
           "category_name": "Food",
           "secondary_category": [
               {
                   "secondary_category_id": 101,
                   "category_name": "Cantonese cuisine",
                   "need_qualification_stuffs": [
                       "food_service_license_id",
                       "food_service_license_bizmedia_id"
                   ],
                   "can_choose_prepaid_card": 1,
                   "can_choose_payment_card": 1
               },
                       }
   ],
   "errcode": 0,
   "errmsg": "ok"
}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
primary_category_id Primary category ID
secondary_category_id Secondary category ID

# 1.4 Updating Sub-merchants

API Description

This API is called to update the sub-merchant's information.

API details

API Request Format

HTTP request method: POST https://api.weixin.qq.com/card/submerchant/update?access_token=TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example


{
  "info": {
  "merchant_id": 12,
  "app_id":"xxxxxxxxxxxxx",
  "brand_name": "aaaaaa",
  "logo_url": "http://mmbiz.xxxx",
  "protocol": "media_id",
  "agreement_media_id":"xxxxxxxxxx",
  "operator_media_id":"xxxxxxxx",
  "end_time": 1438990559,
  "primary_category_id": 1,
  "secondary_category_id": 101
 }
}
Parameter Required Type Example Description
info Yes JSON structure
merchant_id Yes int 12 Sub-merchant ID, which is unique under a parent merchant's Official Account.
app_id No String(36) wxxxxxxxxxxx Official Account's app_id of sub-merchant, which is used on the sub-merchant's cards/coupons once configured. Note that this app_id must be verified.
brand_name Yes String(36) 兰州拉面 (Lanzhou Lamian) Sub-merchant name (up to 12 Chinese characters or 24 English characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Yes string(128) http://mmbiz.xxxx Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
protocol Yes String(36) mdasdfkl Authorization letter ID, which is the media_id obtained after the authorization letter is uploaded via the "Upload Temporary Asset" API.
end_time Yes unsigned int 15300000 The expiration time (UTC+8, in sec) of the authorization letter, which should be the time on the submitted scanned copy.
agreement_media_id No string(36) dhskdjklfjk Color photocopy or scanned copy of Business License or Individual Business License
operator_media_id No string(36) dhskdjklfjk Color photocopy or scanned copy of ID card of the operator registered in the Business License
primary_category_id Yes int 2 Primary category ID, which can be queried via the API hereof.
secondary_category_id Yes int 2 Secondary category ID, which can be queried via the API hereof.

Response Data

{
"info": {
 "merchant_id": 12,
 "create_time": 1438790559,
 "update_time": 1438790559,
 "brand_name": "aaaaaa",
 "logo_url": "http://mmbiz.xxxx",
 "status": "CHECKING",
 "begin_time": 1438790559,
 "end_time": 1438990559,
 "primary_category_id": 1,
 "secondary_category_id": 101
 }
}
Parameter Description
merchant_id Sub-merchant ID, which is unique under a parent merchant's Official Account. This ID is required when creating a card/coupon. Field structure: base_info:{sub_merchant_info:{merchant_id:}}. See "Create Card/Coupon" API for details.
create_time Creation time of sub-merchant information
update_time Update time of sub-merchant information
brand_name Sub-merchant name (up to 12 Chinese characters or 24 Engish characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
status Sub-merchant status. "CHECKING": Under review; "APPROVED": Approved; "REJECTED": Rejected; "EXPIRED": Protocol has expired
bengin_time Creation time (not the start time of the protocol)
end_time The expiration time (UTC+8, in sec) of the authorization letter
primary_category_id Primary category of sub-merchant
secondary_category_id Secondary category of sub-merchant

Note:

If the sub-merchant's information is submitted via the Weixin Official Accounts Platform, the sub-merchant ID can be found in Cards & Offers > Sub-merchant Management > Sub-merchant Details on the Weixin Official Accounts Platform, or returned via the "Create Sub-merchant" API, or obtained via the "Pull Sub-merchant Information" API.

# 1.5 Pulling Single Sub-merchant's Information

API Description

Pulls a sub-merchant's basic information using the specified sub-merchant ID. Note: The parent merchant calls this API but passes the sub-merchant's appid.

API details

API Request Format

HTTP request method: POST URL:https://api.weixin.qq.com/card/submerchant/get?access_token=TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example

{  "merchant_id": 12 }

Response Data

{
 "info": {
 "merchant_id": 12,
 "create_time": 1438790559,
 "update_time": 1438790559,
 "brand_name": "aaaaaa",
 "logo_url": "http://mmbiz.xxxx",
 "status": "CHECKING",
 "begin_time": 1438790559,
 "end_time": 1438990559,
 "primary_category_id": 1,
 "secondary_category_id": 101
 }
}

Example of response for a failed query (errcode is not 0, and errmsg is error message):

{  "errcode":xxxx,  "errmsg":"xxxx" }
Parameter Description
merchant_id Sub-merchant ID, which is unique under a parent merchant's Official Account.
create_time Creation time of sub-merchant information
update_time Update time of sub-merchant information
app_id Official Account's app_id of sub-merchant
brand_name Sub-merchant name (up to 12 Chinese characters or 24 English characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
status "CHECKING": Under review; "APPROVED": Approved; "REJECTED": Rejected; "EXPIRED": Protocol has expired
begin_time Creation time (not the start time of the protocol). If it is the same as create_time, it should be deleted.
end_time Expiration time of the protocol
primary_category_id Primary category of sub-merchant
secondary_category_id Secondary category of sub-merchant

# 1.6 Pulling Sub-merchants' Information in Batch

API Description

The parent merchant can use this API to pull the information of up to 100 sub-merchants at a time. This operation can be performed multiple times to meet different query requirements.

API details

API Request Format

HTTP request method: POST URL:https://api.weixin.qq.com/card/submerchant/batchget?access_token=TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example

{
  "begin_id": 0,
  "limit": 50,
  "status": "CHECKING"
}

Fields

Parameter Description
begin_id Initial sub-merchant ID, which is unique under a parent merchant's Official Account.
limit Number of sub-merchants whose information is to be pulled, which is up to 100.
status The review status of sub-merchant. If specified, only the information of the sub-merchant in the current status is pulled.

Response Data


{ "info_list": [ {
  "merchant_id": 12,
  "create_time": 1438790559,
  "update_time": 1438790559,
  "brand_name": "aaaaaa",
  "logo_url": "http://mmbiz.xxxx",
  "status": "CHECKING",
  "begin_time": 1438790559,
  "end_time": 1438990559,
  "primary_category_id": 1,
  "secondary_category_id": 101 }, {
  "merchant_id": 13,
  "create_time": 1438790559,
  "update_time": 1438790559,
  "brand_name": "bbbbbb",
  "logo_url": "http://mmbiz.xxxx",
  "status": "APPROVED",
  "begin_time": 1438790559,
  "end_time": 1438990559,
  "primary_category_id": 1,
  "secondary_category_id": 101 } ] "next_begin_id": 13
}

Parameter Description
merchant_id Sub-merchant ID, which is unique under a parent merchant's Official Account.
create_time Creation time of sub-merchant information
update_time Update time of sub-merchant information
brand_name Sub-merchant name (up to 12 Chinese characters or 24 English characters), which is entered when creating a card/coupon and displayed on the card/coupon page.
logo_url Sub-merchant logo, which can be obtained via the "Upload Logo" API. This logo is uploaded when creating a card/coupon and displayed on the card/coupon page.
status "CHECKING": Under review; "APPROVED": Approved; "REJECTED": Rejected; "EXPIRED": Protocol has expired
begin_time Creation time (not the start time of the protocol). If it is the same as create_time, it should be deleted.
end_time Expiration time of the protocol
primary_category_id Primary category of sub-merchant
secondary_category_id Secondary category of sub-merchant
next_begin_id ID of the last sub-merchant in the list

Note:

If a parent merchant has more than 100 sub-merchants, it can enter the begin_id to pull the list multiple times, so as to meet the query requirements. The next_begin_id returned from the this call is used as the begin_id in the next call.

# 1.7 Creating Cards/Coupons for Sub-merchants

If the parent merchant needs to create its own cards/coupons, it shall refer to the original card/coupon creation API.

API Request Format

HTTP request method: POST URL:https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example


{
    "card": {
        "card_type": "GROUPON",
        "groupon": {
            "base_info": {
                "sub_merchant_info": {
                    "merchant_id": 123456
                },
                "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
                "brand_name": "Hai Di Lao",
                "code_type": "CODE_TYPE_TEXT",
                "title": "132 CNY Hotpot Set Meal for Two Persons",
                "sub_title": "Best choice for weekend fun",
                "color": "Color010",
                "notice": "Present this coupon to the waiter at the time of use",
                "service_phone": "020-88888888",
                "description": "Using with other coupons is not allowed\nAsk the merchant for an invoice for the group purchase during check-out\nAvailable for eat-in only",
                "date_info": {
                    "type": "DATE_TYPE_FIX_TIME_RANGE",
                    "begin_timestamp": 1397577600,
                    "end_timestamp": 1422724261
                },
                "sku": {
                    "quantity": 500000
                },
                "get_limit": 3,
                "use_custom_code": false,
                "bind_openid": false,
                "can_share": true,
                "can_give_friend": true,
                "location_id_list": [
                    123,
                    12321,
                    345345
                ],
                "custom_url_name": "Use Now",
                "custom_url": "http://www.qq.com",
                "custom_url_sub_title": "6 Chinese characters (12 English characters) at most",
                "promotion_url_name": "More discounts",
                "promotion_url": "http://www.qq.com",
                "source": "dianping.com"
            },
            "deal_detail": "Select a soup base from the following options: mushroom soup, spicy soup, bone soup, tomato soup, nourishing soup, pickled fish soup: \n1 Big Pot: 12 CNY; 2 Small Pots:16 CNY.
        }
    }

 }

For coupon-related fields, see Creating Coupon.

For member card-related fields, see Creating Member Card.

# 1.8 Error Code

Error Code Description
-1 System error
40070 SKU entered in the base info is invalid. See CreateCard API.
40104 The category ID entered when creating a sub-merchant is incorrect
40140 The sub-merchant status is incorrect. When creating a coupon, the status should be "Approved", and when updating the sub-merchant's information, the status should be "Rejected".
40139 The sub-merchant ID is incorrect
40079 The time is entered incorrectly
45021 The parameter length exceeds the limit
43014 Sub-merchant cannot be created without authorization from the platform

# 1.9 Contact Us

For any questions regarding the entrusted coupon creation mode, contact us by emailing to weixin_card@foxmail.com.