SaaS Platform Integration
This feature is an OAuth-based authorization framework designed for SaaS platforms to securely access merchants' Wonder accounts. Traditionally, SaaS platforms have to create and maintain separate credentials for every single customer, which creates a heavy maintenance burden and security risks. With BizConnect, a SaaS platform only needs to maintain a single App. Merchants can seamlessly link their accounts by simply scanning a QR code using the Wonder App.
Workflow
- Exchange an app token. Call the create an app tokenAPI with
Authorization: Basic base64(client_id:client_secret)and returnaccess_token. Thisaccess_tokenis only used to request QR codes and poll for results. - Create a login QR code. Call the create login QR codeAPI and return the
contentfield. - Render the QR code. Encode
contentas a QR image and let your customer to scan it with the Wonder App. - Your customer scans the QR code. The Wonder App will handle this page and your application does not render it.
- Your customer can approves or rejects.
- Poll for the result. Your server continuously polls the query login QR code statusAPI. Once your customer approves, then the status changes from
PENDINGtoSUCCESS, and the response returns the customer'stokenandrefresh_token; however, if your customer rejects, then the status changes toREJECTEDand please dont poll result anymore, and re-create a new login QR code again(see step 2). - Refresh token. In order to avoid duplicated scanning QR code, you can call refresh tokenAPI. Only when your customer approve the QR code, then can call the refresh tokenAPI with
refresh_tokenthat return from the query login QR code statusAPI.
Prerequisites: Your merchant already onboarding via the Wonder App and the configuration(client_id / client_secret / all token validity period ) has been done by Wonder backend. For the configuration, please contact support@wonder.app for help.
QR code validity period: 120 seconds, after 120 seconds, the QR code will be expired, need to re-create a new login QR code.
Token Types & Usage
| Type | Role / Identity | How to obtain it | Core purpose |
|---|---|---|---|
| App_token | Your application's identity | Exchange client_id / client_secret | Used only to create login QR codeAPI and query login QR code statusAPI. |
| Token | Your customer's authorization credential | Returned by the query login QR code statusAPI after your customer approves | --. |
| Refresh_token | Session Renewal Key | Returned by the query login QR code statusAPIafter your customer approves | Used to silently exchange for a new User Token when the current one expires, avoiding repeated QR code scans. |
The status for QR code
| Status | Meaning | Triggered by | Your server |
|---|---|---|---|
| PENDING | Waiting to be scanned / approved. | When the QR code is created. | Keep polling. |
| SUCCESS | The user approved and the token can be delivered. | The user taps approve. | Stop polling; complete the login. |
| REJECTED | The user explicitly rejected. | The user taps 'reject' button. | Stop polling; offer to scan again. |
| EXPIRED | The QR code was not handled before its expiry. | Evaluated lazily on the next poll or detail query. | Stop polling; offer to scan again. |
Multi-device login
You can optionally pass a device_id (max 64 chars) when creating the QR code.
| Scenario | Behaviour |
|---|---|
device_id passed | Each device holds an independent session with its own token and refresh_token. Logging in on one device does not sign the others out. |
Same device_id authorized again | The session for previous one will be blacklisted immediately. Other devices are untouched. |
device_id omitted | The new authorization will invalidate the previous session (single-device semantics). |
Revoking Authorization
Your customer can revoke the access at any time via the Wonder App. Once revoked, all device sessions are immediately terminated, and the associated tokens are blacklisted.
Related APIs
Exchanges client_id and client_secret for an app_token used to request QR codes and poll status.
Generates a one-time login QR code (with content and server_code) for the customer to scan and authorize.
Checks the current status of the QR code (e.g., PENDING, SUCCESS, REJECTED, EXPIRED) and retrieves the Token upon success.
Uses a refresh_token to silently exchange for a new User Token, avoiding re-scanning.