Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Request funds-distribution API

Latest update time:2022.08.04 Release notes

After the Weixin transaction is successfully completed, the merchant initiates a funds-distribution request and distributes the settled funds to the receiver.

Tips:

• The funds-distribution requests for the same transaction can be initiated up to 50 times and the funds can be distributed to a maximum of 50 parties each request;

• The API is in asynchronous processing mode, that is, after receiving the merchant's request, it will be accepted first and then processed asynchronously, and the final funds-distribution result can be obtained through the funds-distribution Result Query API;

• API supports the merchant to initiate funds-distribution multiple times for the same transaction. See the description of the unfreeze_unsplit field in the request parameters for details (refer to the supplementary call example after the documents);

• The unfrozen funds for the sponsor outbound through the API, together with the non-funds-distribution transaction amount, is subject to the net settlement. The regulations are consistent with the settlement period, starting point and other withdrawal rules in the settlement contract with the merchant;

• The sponsor refers to the merchant who has actually settled the funds and entered the funds into the account via Weixin Pay. It refers to a merchant in the overseas institution mode, and a sub-merchant in the service provider mode.

• Merchants use the public key of Weixin Pay for encryption when uploading sensitive information. The certificate serial number is included in Weixinpay-Serial in the HTTP header of the request. SeeAPI Rulesfor details.

1. API Intro

Applicable object: Common mode Institutional mode

API rules:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/orders

Request method:POST


Pathparameter is a path parameter.
Queryparameter needs to be passed in the request URL.
Bodyparameter needs to be passed in the request JSON.

2. Request Parameters

Name Variable Name Type Required Description
Sub-merchant ID sub_mchid string[1, 32] No Body Sub-merchant ID allocated by Weixin Pay. It needs to be consistent with the sub-merchant ID in the transaction of Weixin Pay.
Note: Only forInstitutional mode
Example: 1900000109
Official account ID appid string[1, 32] No Body Merchant official account ID allocated by Weixin. When the receiver type includes PERSONAL_OPENID, its filling is required.
Example: wx8888888888888888
Sub-merchant official account ID sub_appid string[1, 32] No Body Sub-merchant official account ID allocated by Weixin. When the receiver type includes PERSONAL_SUB_OPENID, its filling is required.
Note: Only forInstitutional mode
Example: wx8888888888888889
Weixin Pay transaction ID transaction_id string[1, 32] Yes Body Weixin Pay transaction ID
Example: 4208450740201411110007820472
Merchant order No. out_order_no string[1, 64] Yes Body The order No. in the merchant system, which is unique. It can only include numbers, capital letters and lowercase letters _-.
Note: This order No. is used to identify different requests of funds-distribution commands (including funds-distribution request API/unfreezing remaining funds API) initiated from the merchant side.
If the funds of one transaction is distributed multiple times, change the [merchant order No.] before requesting funds-distribution. Otherwise it will be considered as a repeated request.
Example: P20150806125346
Whether to unfreeze the remaining undistributed funds unfreeze_unsplit boolean Yes Body 1. If true, the remaining undistributed funds amount of the transaction will be unfrozen to the sponsor's account outbound;
2. If false, the remaining undistributed funds amount of the transaction will not be unfrozen to the sponsor's account and the transaction funds can be distributed again.
Example: true
Receiver list receivers array[1,50] No BodyReceiver list. If unfreeze_unsplit=false, the sponsor can be set as the receiver. Otherwise, the funds-distribution request will be rejected. There can be up to 50 receivers.
Name Variable Name Type Required Description
Distribution currency currency string[3, 3] Yes Distribution currency, a three-letter code that meets the requirements of ISO 4217 standard. Currently only support "CNY".
Example: CNY
Receiver type type string[1, 32] Yes Receiver type.
MERCHANT_ID: Merchant ID,
PERSONAL_OPENID: Personal OpenID, converted by merchant APPID
PERSONAL_SUB_OPENID: Personal Sub_OpenID, converted by sub-merchant APPID
Example: MERCHANT_ID
Receiver account account string[1, 64] Yes 1. When the type is MERCHANT_ID, it is the merchant ID
2. When the type is PERSONAL_OPENID, it is the personal OpenID
3. When the type is PERSONAL_SUB_OPENID, it is the personal Sub_OpenID.

Note: Currently, the personal OpenID cannot be added as a receiver
Example: 86693852
Funds-distribution personal receiver name name string[1, 1024] No Optional, when the receiver type is personal. If filled in, check whether the name is consistent with the real-name of the Weixin user. If the name is inconsistent, the funds-distribution request will be rejected
When the receiver type is PERSONAL_OPENID or PERSONAL_SUB_OPENID, the ciphertext of the personal name can be filled in (Optional. Check it When you fill it in). This field needs to be encrypted. See the description of sensitive information encryption at the beginning of the document for the encryption method.
Example: hu89ohu89ohu89o
Whether the user has given authorization to use their real-name information authorized boolean No The merchant uploads the real-name and account information of the user to Weixin Pay. The Weixin Pay backstage will assist in verifying the consistency of the user information to reduce the risk of mistakes of the receiver. This field indicates the authorization status of the user information to the merchant for confirmation and transmission:
1) False indicates that the user information is not authorized and Weixin Pay will refuse to receive data
2) True indicates that the user information has been authorized and Weixin Pay will receive data
Note: When the personal receiver name field is set, it is a required field
Example: true
Funds-distribution amount amount int Yes Funds-distribution amount, unit: cents;Can only be an integer and cannot exceed the payment amount of the original transaction;
In addition, in the scenario of funds-distribution to other receivers, verify whether the distributed funds amount exceeds the maximum funds-distribution proportion amount.
Example: 888
Funds-distribution description description string[1, 80] Yes Reason description of Funds-distribution, to be reflected in the funds-distribution record
Example: Distribute to merchant A

Request Eample


{
    "appid": "wx7bc98d929da735fe",
    "out_order_no": "MCH13SFDG234155321146",
    "receivers": [
      {
        "account": "2480248971",
        "amount": 99,
        "currency": "CNY",
        "description": "distribute to xxx merchant-10%",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 99,
        "currency": "CNY",
        "description": "distribute to xxx user-10%",
        "type": "PERSONAL_OPENID"
      }
    ],
    "sub_mchid": "999968479",
    "transaction_id": "4200000012202203235765130087",
    "unfreeze_unsplit": true
  }

{
    "appid": "wx7bc98d929da735fe",
    "out_order_no": "MCH1349FG041421146",
    "receivers": [
      {
        "account": "2480248971",
        "amount": 1000,
        "currency": "CNY",
        "description": "order 1: distribute to xxx merchant",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 1000,
        "currency": "CNY",
        "description": "order 1: distribute to xxx user",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "999952224", # Note: fill in the sponsor merchant ID here
        "amount": 8000,
        "currency": "CNY",
        "description": "order 1: unfreeze funds outbound",
        "type": "MERCHANT_ID"
      }
    ],
    "sub_mchid": "999968479",
    "transaction_id": "4200000028202203236604547485",
    "unfreeze_unsplit": false
  }

									{
										"stock_id": ".NET",
										"limit": 10,
									}

									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. Response Parameters

Name Variable Name Type Required Description
Sub-merchant ID sub_mchid string[1, 32] No Merchant ID allocated by Weixin Pay
Note: Only forInstitutional mode
Example: 1900000109
Weixin Pay order No. transaction_id string[1, 32] Yes Weixin Pay transaction ID
Example: 4208450740201411110007820472
Merchant order No. out_order_no string[1, 64] Yes Merchant order No., same as the request parameter.
Example: P20150806125346
Weixin order ID order_id string[1, 64] Yes Weixin order ID, the unique identifier returned by Weixin system.
Example: 3008450740201411110007820472
Funds-distribution order state state string Yes Funds-distribution order state (see result field in receivers for funds-distribution results of each receiver).
PROCESSING: Funds-distribution is processing,
FINISHED: Funds-distribution is finished,
Example: FINISHED
Receiver list receivers array[1,50] Yes Receiver list
When a merchant initiates a funds-distribution request or a unfreeze the remaining funds request, the same transaction funds can be distributed to multiple receivers (including unfreezing funds to the sponsor). The funds-distribution detail describes each funds-distribution state of each receiver.
Name Variable Name Type Required Description
Distribution currency currency string[3, 3] Yes Distribution currency, same as the request parameter.
Example: CNY
Funds-distribution amount amount int Yes Funds-distribution amount, same as the request parameter.
Example: 100
Funds-distribution description description string[1, 80] Yes Merchant order No., same as the request parameter.
Example: Distribute to merchant 1900000110
Receiver type type string[1, 32] Yes Receiver type, same as the request parameter.
MERCHANT_ID: Merchant ID,
PERSONAL_OPENID: Personal OpenID, converted by merchant APPID
PERSONAL_SUB_OPENID: Personal Sub_OpenID, converted by sub-merchant APPID
Example: MERCHANT_ID
Receiver account account string[1, 64] Yes Receiver account, same as the request parameter.
Example: 1900000109
The result of each funds-distribution detail. result string[1, 32] Yes The result of each funds-distribution detail.
PENDING: Funds to be distributed,
SUCCESS: Funds-distribution succeeded,
CLOSED: Funds-distribution closed,
Example: SUCCESS
Funds-distribution detail fail reason fail_reason string[1, 64] No Funds-distribution detail fail reasons. Set only when funds-distribution detail result is "CLOSED."
NO_RELATION: The funds-distribution relationship has been terminated.
SUB_MERCHANT_FRONEN: The sub-merchant account is frozen,
MCH_CONTRACT_SETTLE_OFF: The merchant settlement contract is in closed state.
MCH_CONTRACT_FROZEN: The merchant settlement contract is frozen,
ACCOUNT_ABNORMAL: The receiver account is abnormal,
RECEIVER_HIGH_RISK: The receiver is at high risk,
RECEIVER_REAL_NAME_NOT_VERIFIED: The receiver has not been real-name verified,
NO_AUTH: The funds-distribution authorization has been canceled,
DEFAULT_ERROR: Default error,
Example: ACCOUNT_ABNORMAL
Funds-distribution detail creation time create_time string[1, 64] Yes Funds-distribution detail creation time follows RFC3339 standard format
Example: 2015-05-20T13:29:35.120+08:00
Funds-distribution detail finish time finish_time string[1, 64] No Funds-distribution detail finish time follows RFC3339 standard format. Set only when the funds-distribution detail result is "SUCCESS" or "CLOSED".
Example: 2015-05-20T13:29:35.120+08:00
Weixin funds-distribution detail ID detail_id string[1, 64] Yes Weixin funds-distribution detail ID is the details ID of each funds-distribution business.
Example: 36011111111111111111111
Receiver type detail_type string[1, 32] Yes The funds-distribution details include two categories of funds: Funds distributed to other receivers and funds unfrozen to sponsor. These two categories can be distinguished by the field. If the detail type is UNFREEZE_TO_SPONSOR, the funds-distribution details will indicate settlement currency, settlement amount and exchange rate and other information.
DISTRIBUTE_TO_OTHERS: Distribute funds to other receivers,
UNFREEZE_TO_SPONSOR: Unfreeze funds to the sponsor outbound,
Example: DISTRIBUTE_TO_OTHERS
Settlement currency settlement_currency string[3, 3] No The field is set only when the detail type is UNFREEZE_TO_SPONSOR.
Example: HKD
Settled amount settlement_amount int No The funds amount is finally settled via exchange rate to the sponsor, using the minimum currency unit.
Example: 110
Exchange rate value rate int No The value is the exchange ratio between the distribution currency and the settlement currency multiplied by the 8th power of 10.
If the distribution currency and settlement currency are both CNY, the exchange ratio is 1 and the exchange rate value is 100,000,000;
If the settlement currency is USD, assuming that the ratio of USD to CNY is 6.5, the exchange rate value is 650,000,000.
Example: 81000000

Return Example


{
    "order_id": "7100000751202203238026613597498",
    "out_order_no": "MCH13SFDG234155321146",
    "receivers": [
      {
        "account": "999952224", # Note: The account is the sponsor merchant ID
        "amount": 797,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "Unfreeze the remaining funds to sponsor",
        "detail_id": "7200000751202203238026613597602",
        "detail_type": "UNFREEZE_TO_SPONSOR",
        "rate_value": 83640300,
        "result": "PENDING",
        "settlement_amount": 952,
        "settlement_currency": "HKD",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 99,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "Distribute to xxx user-10%",
        "detail_id": "7200000751202203238026613597699",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "2480248971",
        "amount": 99,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "Distribute to xxx merchant-10%",
        "detail_id": "7200000751202203238026613597767",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "MERCHANT_ID"
      }
    ],
    "state": "PROCESSING",
    "sub_mchid": "999968479",
    "transaction_id": "4200000012202203235765130087"
  }

{
    "order_id": "7100000749202203238028118660977",
    "out_order_no": "MCH1349FG041421146",
    "receivers": [
      {
        "account": "999952224",
        "amount": 8000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "order 1: unfreeze funds outbound",
        "detail_id": "7200000749202203238028118661068",
        "detail_type": "UNFREEZE_TO_SPONSOR",
        "rate_value": 83640300,
        "result": "PENDING",
        "settlement_amount": 9564,
        "settlement_currency": "HKD",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 1000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "order 1: distribute to xxx user",
        "detail_id": "7200000749202203238028118661146",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "2480248971",
        "amount": 1000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "order 1: distribute to xxx merchant",
        "detail_id": "7200000749202203238028118661205",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "MERCHANT_ID"
      }
    ],
    "state": "PROCESSING",
    "sub_mchid": "999968479",
    "transaction_id": "4200000028202203236604547485"
  }

									{
										"stock_id": ".NET",
										"limit": 10,
									}

									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

4. Error Code

Error Codes Error Message Description Solution
400 INVALID_REQUEST The user type is PERSONAL_SUB_OPENID, the sub_appid in parameter is not set The user type is PERSONAL_OPENID, please set appid field
400 INVALID_REQUEST The user type is PERSONAL_SUB_OPENID, the sub_appid in parameter is not set The user type is PERSONAL_SUB_OPENID, please set sub_appid field
400 INVALID_REQUEST The user OpenID and the uploaded AppID do not match Verify under which merchant authorization scenario the OpenID is obtained and set the related AppID field by referring to the description of the receiver type field in the APIs document
400 INVALID_REQUEST Duplicate IDs in the receiver list when requesting funds-distribution Check receiver list and remove duplicate IDs in the same request before requesting funds-distribution
400 INVALID_REQUEST Personal receiver selects to upload the name field but does not confirm authorized status of user If the personal receiver selects to upload the name to verify the consistency with user's real-name information, the merchant needs to obtain the user authorization first and set the authorized field to true
400 INVALID_REQUEST The real-name information of the personal receiver on Weixin does not match the uploaded name field value when requesting funds-distribution Confirm with the receiver their real-name information before executing the request
400 INVALID_REQUEST Currently, only CNY is supported in funds-distribution Check receiver list and adjust the distribution currency to CNY before requesting funds-distribution
400 INVALID_REQUEST The transaction has exceeded the maximum time limit for funds-distribution Re-check the payment time of the transaction. Transactions exceeding the maximum time limit for are not allowed to initiate funds-distribution. (the system has initiated unfreezing the funds for settlement outbound)
400 INVALID_REQUEST The transaction does not support funds-distribution Check whether the Weixin Pay transaction ID is filled in incorrectly and confirm that the Funds-distribution Mark API is called successfully before calling the transaction API
400 INVALID_REQUEST The merchant information in the request of funds-distribution is inconsistent with that in the original transaction Carefully check whether the transaction ID is filled in correctly and whether the sub-merchant has been filled in or filled in incorrectly
400 INVALID_REQUEST If you choose to unfreeze the remaining undistributed funds amount, that is, set unfreeze_unsplit to true in the funds-distribution request, you cannot add the sponsor as the receiver If you choose to unfreeze the remaining funds amount to be distributed, that is, set unfreeze_unsplit to true in the funds-distribution request, remove the sponsor account from the receiver list before requesting funds-distribution
400 INVALID_REQUEST When partial unfreezing is selected, the account for the unfrozen funds is filled in incorrectly. (Should be set as the actual sponsor) Set the sponsor as the actual settled funds Weixin account. Fill in merchant ID for the institution and sub-merchant ID for the service provider
400 INVALID_REQUEST When requesting funds-distribution and it has been verified that the funds receiver relationship does not exist. Check whether all receivers have been added Check whether all receivers have been added
400 INVALID_REQUEST When requesting funds-distribution and it has been verified that the funds receiver relationship is not in effect or has been terminated. Check whether all receivers are in effect Check whether all receivers are in effect
403 USER_ERROR There is a receiver that has not been real-name verified in the receiver list, and their Weixin balance account cannot accept the payment request Check receiver list and confirm that the receiver user has been real-name verified before requesting funds-distribution
403 USER_ERROR There is a receiver whose account is restricted for collection in the receiver list, and their cumulative collection amount in the balance + current collection amount has exceeded the limit In the case of exceeding the collection amount limit, the restricted user will receive Weixin's push message. Please guide the question receiver to complete the upgrade according to the guidelines before requesting funds-distribution
403 USER_ERROR There is a receiver whose account has hit the Weixin risk interception strategy in the receiver list, and their account is restricted from collection The user's account intercepted with risk prompts from the platform side is subject to full-scenario collection restriction. Please eliminate the related risky receiver before requesting funds-distribution
403 NO_AUTH The merchant has not signed the overseas funds-distribution product Refer to the product process and access preparation, confirm that the merchant has funds-distribution authorization, and initiate the request again
403 NO_AUTH The merchant has enabled the funds-distribution product and is waiting for it to take effect (Usually takes effect the next day) The funds-distribution function cannot be initiated on the first day. Please initiate the request on the next day
403 NO_AUTH Receiver Confirm that the receiver is legally compliant before requesting funds-distribution
403 NO_AUTH The parent-child relationship of the merchant does not exist. Please use correct sub-merchant ID to initiate the request Please check if the sub-merchant ID (sub_mchid) is filled in correctly
400 INVALID_REQUEST The command (out_order_no) already exists when the merchant requests funds-distribution and the receiver is inconsistent with that in the existing funds-distribution command In case of the same funds-distribution request, check whether the receiver information is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400 INVALID_REQUEST The command (out_order_no) already exists when the merchant requests funds-distribution and the funds-distribution amount is inconsistent with that in the existing funds-distribution command In case of the same funds-distribution request, check whether the funds-distribution amount is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400 INVALID_REQUEST The command (out_order_no) already exists when the merchant requests funds-distribution and the funds amount detail is inconsistent with that in the existing funds-distribution command In case of the same funds-distribution request, check whether the receiver list is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400 INVALID_REQUEST The command (out_order_no) already exists when the merchant unfreezes the remaining funds and the details are not as expected In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400 INVALID_REQUEST Funds settlement outbound amount cannot be 0 when requesting to unfreeze the distributed funds outbound Adjust the unfreezing funds amount (CNY) appropriately so that the amount of foreign currency after conversion into foreign currency is greater than 0
400 INVALID_REQUEST The split funds amount exceeds the maximum split percentage when requesting funds-distribution Adjust the split funds amount to be within the split ratio limit before requesting funds-distribution
400 INVALID_REQUEST The number of funds-distribution of the transaction has exceeded the maximum funds-distribution times, funds-distribution cannot be initiated. Call [Unfreeze Remaining Amount API] to unfreeze funds
403 NOT_ENOUGH The funds amount to be distributed is insufficient at the time of request The current remaining funds amount to be distributed can be obtained through [Remaining Funds Amount to be Distributed Query API]
500 SYSYTEM_ERROR The freeze process of the transaction funds specified by the merchant when initiating funds-distribution request has not been completed. Try again later After the user completes the payment, the fund freezing process for the transaction with funds-distribution will be triggered. It is recommended that the merchant try again after 3~5 mins


    Page Navigation

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

置顶