Authorization

applyToken

Exchanging the auth code for wallet access tokens.

Overview

POST /v1/authorizations/applyToken issues wallet access tokens for merchants. Call this endpoint after obtaining an authorization code (for example via my.getAuthCode or qicardSignContract) or when you need to refresh an existing token. The app returns accessToken and refreshToken values that must be stored securely on your server.

The client should invoke my.getAuthCode before calling applyToken to collect the authCode.
Use grantType: REFRESH_TOKEN with the refreshToken to renew expiring tokens without user interaction.
Never expose the resulting tokens to the Mini Program; keep them on the merchant backend.

To view the end-to-end diagram, see the Authentication flow.

Endpoint

Method	Path
`POST`	`/v1/authorizations/applyToken`

API Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: OpenAPIs Overview.

Request

Field	Type	Required	Description	Example
`grantType`	`string`	Yes	Token exchange mode. Accepted values: `AUTHORIZATION_CODE` (exchange `authCode`), `REFRESH_TOKEN` (exchange `refreshToken`).	`"AUTHORIZATION_CODE"`
`authCode`	`string`	Conditional	Authorization code obtained from the wallet. Required when `grantType` is `AUTHORIZATION_CODE`. Max length 64; no special characters `@#?`.	`"2810111301lGzcM9CjlF91WH00039190xxxx"`
`refreshToken`	`string`	Conditional	Refresh token issued previously. Required when `grantType` is `REFRESH_TOKEN`. Max length 128; no `@#?`.	`"2810110133AB2F588D14B43238637264FCA5AAF35xxxx"`
`extendInfo`	`string`	No	Additional metadata (max 4096 characters, no `@#?`).	`{ "memo": "Recurring agreement" }`

{
  "grantType": "AUTHORIZATION_CODE",
  "authCode": "2810111301lGzcM9CjlF91WH00039190xxxx"
}

{
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "2810110033AAB2F588D14B43238637264FCA5AAF35xxxx"
}

Response

Field	Type	Required	Description	Example
`result`	`object`	Yes	Outcome metadata including status and error codes.	`{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }`
`accessToken`	`string`	Conditional	Access token for user data APIs. Present when exchange succeeds. Max length 128; no `@#?`.	`"281010033AB2F588D14B43238637264FCA5AAF35xxxx"`
`accessTokenExpiryTime`	`string`	Conditional	Expiry timestamp (ISO 8601). Required when `accessToken` is issued.	`"2023-06-06T12:12:12+08:00"`
`refreshToken`	`string`	Conditional	Refresh token for future exchanges. Required when exchange succeeds.	`"2810100334F62CBC577F468AAC87CFC6C9107811xxxx"`
`refreshTokenExpiryTime`	`string`	Conditional	Expiry timestamp (ISO 8601). Required when `refreshToken` is issued.	`"2023-06-08T12:12:12+08:00"`
`customerId`	`string`	Yes	Identifier of the authorizing user or merchant app. Max length 64; no `@#?`.	`"1000001119398804xxxx"`
`extendInfo`	`string`	No	Extended response metadata (max 4096 characters, no `@#?`).	`null`

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "accessTokenExpiryTime": "2023-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811xxxx",
  "refreshTokenExpiryTime": "2023-06-08T12:12:12+08:00",
  "customerId": "1000001119398804xxxx"
}

Result Processing Logic

Status	Description
`S`	Request succeeded. `resultCode` is `SUCCESS` and `resultMessage` is `success`.
`U`	Outcome unknown. `resultCode` is `UNKNOWN_EXCEPTION`; retry after checking Common error codes or logs.
`F`	Request failed. Inspect `resultCode` and cross-reference Error codes.

Error Codes

Error Code	Result Status	Message	Next Step
`AUTH_CLIENT_UNSUPPORTED_GRANT_TYPE`	`F`	Merchant client does not support this `grantType`.	Use `AUTHORIZATION_CODE` or `REFRESH_TOKEN`.
`INVALID_REFRESH_TOKEN`	`F`	Refresh token is invalid.	Request a new refresh token via `applyToken`.
`EXPIRED_REFRESH_TOKEN`	`F`	Refresh token expired.	Re-authorize with `my.getAuthCode` to obtain a new refresh token.
`USED_REFRESH_TOKEN`	`F`	Refresh token already used.	Acquire a new refresh token via `applyToken`.
`INVALID_CODE`	`F`	Authorization code invalid.	Obtain a new `authCode` via `my.getAuthCode`.
`USED_CODE`	`F`	Authorization code already used.	Request a new `authCode` via `my.getAuthCode`.
`EXPIRED_CODE`	`F`	Authorization code expired.	Request a new `authCode` via `my.getAuthCode`.

Overview

Complete guide to Super Qi's backend-to-backend OpenAPIs for Mini Programs.

prepare

Initialize a QiCard agreement authorization request.