Wonder

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

  1. Exchange an app token. Call the create an app tokenAPI with Authorization: Basic base64(client_id:client_secret)and return access_token. This access_token is only used to request QR codes and poll for results.
  2. Create a login QR code. Call the create login QR codeAPI and return the content field.
  3. Render the QR code. Encode content as a QR image and let your customer to scan it with the Wonder App.
  4. Your customer scans the QR code. The Wonder App will handle this page and your application does not render it.
  5. Your customer can approves or rejects.
  6. Poll for the result. Your server continuously polls the query login QR code statusAPI. Once your customer approves, then the status changes from PENDING to SUCCESS, and the response returns the customer's token and refresh_token; however, if your customer rejects, then the status changes to REJECTED and please dont poll result anymore, and re-create a new login QR code again(see step 2).
  7. 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_token that return from the query login QR code statusAPI.
INFO

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.

INFO

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

TypeRole / IdentityHow to obtain itCore purpose
App_tokenYour application's identityExchange client_id / client_secretUsed only to create login QR codeAPI and query login QR code statusAPI.
TokenYour customer's authorization credentialReturned by the query login QR code statusAPI after your customer approves--.
Refresh_tokenSession Renewal KeyReturned by the query login QR code statusAPIafter your customer approvesUsed to silently exchange for a new User Token when the current one expires, avoiding repeated QR code scans.

The status for QR code

StatusMeaningTriggered byYour server
PENDINGWaiting to be scanned / approved.When the QR code is created.Keep polling.
SUCCESSThe user approved and the token can be delivered.The user taps approve.Stop polling; complete the login.
REJECTEDThe user explicitly rejected.The user taps 'reject' button.Stop polling; offer to scan again.
EXPIREDThe 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.

ScenarioBehaviour
device_id passedEach 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 againThe session for previous one will be blacklisted immediately. Other devices are untouched.
device_id omittedThe 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.

Create an app tokenAPI

Exchanges client_id and client_secret for an app_token used to request QR codes and poll status.

Create login QR codeAPI

Generates a one-time login QR code (with content and server_code) for the customer to scan and authorize.

Query login QR code statusAPI

Checks the current status of the QR code (e.g., PENDING, SUCCESS, REJECTED, EXPIRED) and retrieves the Token upon success.

Refresh tokenAPI

Uses a refresh_token to silently exchange for a new User Token, avoiding re-scanning.