/v1/authorizations/prepare
POST /v1/authorizations/prepare
The prepare interface is used to prepare the contract information. This interface can be used in the following cases:
- For subscription scenarios, including monthly or seasonal or yearly, the merchant can use this interface to prepare the contract information for the agreement payment authorization.
Message structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Request
Field Name | Data Type | Length | Required | Description | Example |
scopes | String | - | Yes | In the agreement pay business scenario, the fixed value is AGREEMENT_PAY | AGREEMENT_PAY |
extendInfo | String | 2048 | Yes | The extend information. Max. length: 2048 characters. e.g. {\"contractDesc\":\"agreement payment description. \"} | {\"contractDesc\":\"agreement payment description. \"} |
Response
Field Name | Data Type | Required | Description |
result | Yes | The request result, which contains information related to the request result, such as status and error codes. | |
authUrl | String | No | An authUrl can be used to call the my.call("signContract"). When authorization application is successful [result.resultStatus == S], the merchant might use authUrl to request for user's authorization with my.call("signContract"). Max. length: 256 characters. |
Result Code
# | Result code | Result status | Result message | Further action |
1 | SUCCESS | S | success. | Save the authorization URL to the data, and if the authorization content remains unchanged, it can be used continuously. |
2 | PARAM_ILLEGAL | F | Illegal parameters. | Return failure to mini program and prompt users |
3 | INVALID_AUTH_CLIENT | F | The auth client id is invalid. | Return failure to mini program and prompt users |
4 | INVALID_AUTH_CLIENT_STATUS | F | Invalid auth client status. | Return failure to mini program and prompt users |
5 | UNKNOWN_EXCEPTION | U | API failed due to unknown reason. | Return failure to mini program and prompt users |
6 | INVALID_SCOPE | F | The scope id is invalid. | Return failure to mini program and prompt users |
7 | AUTH_CLIENT_UNSUPPORT_SCOPE | F | The client do not support the requests scope. | Return failure to mini program and prompt users |
8 | REDIRECT_URL_NOT_MATCH | F | The redirect url is illegal. | Return failure to mini program and prompt users |
Sample
The data flow to prepare the contract information is illustrated as below:
Step1: The user opens the mini program and signs the contract.
Step2: Merchant mini program requests merchant backend to obtain authorization contract URL.
Step3: If there is an authorizationURL in the merchant's backend database, it can be returned directly to the mini program. The authorization URL is not related to the user, as long as the content has not changed, there is no need to create it again.
Step4~5: If there is no authorizationURL in the merchant's backend database or if authorization content needs to be updated, then it is necessary to request the superapp backend to create new authorization and obtain new authorizationURL.
Step6: After successful authorization prepare, The merchant backend save or update authorizationURL to database.
Step7~8 : Merchant backend returns authorizationURL to mini program. Mini program uses authorizationURL to open the signing page.
Step9~11: The superapp client requests the superapp backend to obtain this authorization information and display it to the user. In steps 8-9, security reinforcement will be carried out between the superapp client and superapp server to prevent hacker forgery attacks.
Step12~16 The user confirms authorization, and the superapp client apply authorization to the superapp server. After successful authorization, the superapp server returns the auth code to the superapp client, and the superapp client call back to the mini program. In steps 12-13, security reinforcement will be carried out between the superapp client and superapp server to prevent hacker forgery attacks.
Step17: Mini program passes auth code to merchant server.
Step18~21: The merchant backend obtains the access token through the auth code. After obtains the access token successful, the merchant backend save the user's accessToken of auto-debit contract.Then the merchant's backend returns the signing result to the mini program. The validity period of the auth code is only 10 minutes, and the merchant backend needs to apply access token within 10 minutes.
Step22: Mini program displays the signing result to the merchant.