YUNIT SL
YUNIT SL
Senior Hands on Delivery
English Deutsch Català Русский

Merchant integration guide

Merchant integration for YUNIT consent and wallet flows

This page explains how a merchant POS or backend integrates with YUNIT to create consent requests, handle callbacks, poll status, and fetch only the customer data approved for a single transaction.

Open the portal Consumer overview

Merchant onboarding prerequisites

  • Each merchant is provisioned as a YUNIT tenant with one or more POS or backend OAuth clients.
  • Each OAuth client has registered redirect URIs, allowed scope requests, and a merchant display name shown on the consent screen.
  • The merchant defines which POS flows need customer data and what business purposes should be shown to the customer.
  • Store staff receive operational guidance for scanning wallet QR codes and handling denied or expired requests.

Scope catalog and request model

  • Merchants request fields from a predefined YUNIT scope catalog such as name, billing address, tax number or NRT, email, and phone.
  • Each consent request must include the requested scopes, the merchant name, and a purpose such as an invoice or account action.
  • The request is one-time and produces no standing permission for the merchant after the approved response is completed.
  • YUNIT returns a request id, customer consent URL, callback context, and a status endpoint for polling.

Consent request lifecycle

  • The POS or merchant backend creates a consent request server-side with its OAuth client credentials.
  • The customer presents a YUNIT wallet QR, which the POS scans to start the lookup and approval flow.
  • YUNIT sends or displays the OTP-backed approval path on the customer's phone and records the final allow or deny outcome.
  • If approved, the merchant exchanges the authorisation code and fetches only the scoped fields granted for that request.

Callback, polling, and expiry behavior

  • Merchant systems should support both redirect or callback completion and status polling for reliable POS operation.
  • Denied, cancelled, or expired requests must be treated as final and should never unlock data retrieval on the merchant side.
  • Expired authorisation codes and access tokens require the merchant to restart the request rather than retry old credentials.
  • POS screens should clearly surface waiting, approved, denied, and expired states to avoid staff confusion at checkout.

Security and audit expectations

  • Wallet QR codes represent rotating lookup tokens, not stable readable customer identifiers for the merchant.
  • Merchants should store request references, approval outcome, and minimal necessary transaction data, not a parallel copy of all YUNIT profile data.
  • YUNIT maintains the authoritative record of requested scopes, granted scopes, purpose text, and release events for audit review.
  • Redirect URI registration, token lifetime handling, and strict scope usage are required to keep the integration compliant and supportable.

Merchant integration sequence

  1. Step 1 Provision the merchant tenant, register redirect URIs, and issue OAuth client credentials for the POS backend or middleware.
  2. Step 2 Create a consent request with the required scopes, purpose reference, and POS session context.
  3. Step 3 Scan the consumer wallet QR so YUNIT can resolve the wallet token and launch the OTP-backed approval flow.
  4. Step 4 Receive the short-lived authorization code after approval and exchange it for an access token.
  5. Step 5 Fetch only the approved scoped data, complete the merchant transaction, and keep the request audit trail.

Consent request example

curl -H "Authorization: Bearer POS_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/consent-requests \
  -d '{
    "merchant_id": "restaurant-abc",
    "terminal_id": "pos-03",
    "purpose": "Invoice #12345",
    "scopes": ["name", "billing_address", "tax_number"],
    "callback_url": "https://merchant.example.com/yunit/callback"
  }'

Authorization code exchange

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/token \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_req_9f8d",
    "redirect_uri": "https://merchant.example.com/yunit/callback"
  }'

Scoped data fetch example

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET "https://api.yunit.tech/oauth/consent-requests/auth_req_9f8d/data"

Operational notes

  • Use callback plus polling so the POS stays resilient if one delivery path is delayed.
  • Treat every approval as one-time consent. A later request needs a new approval, even for the same merchant.
  • Authorization codes and access tokens should be short-lived and scoped to the approved request only.
  • Merchant logs should keep request IDs, scopes, purpose references, and outcome states without storing unnecessary PII.