Documentation hub

Install the SDK

Add @visaacceptance/embed-js to your frontend project.

Get an access_token (server-side)

Exchange your client credentials for an access_token. 15-minute TTL, no refresh — server-side only.

// Step 1 — client_credentials grant
const oauthRes = await fetch(
  'https://apitest.visaacceptance.com/oauth2/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type:    'client_credentials',
      client_id:     process.env.VISA_CLIENT_ID,
      client_secret: process.env.VISA_CLIENT_SECRET,
      solution_id:   process.env.VISA_SOLUTION_ID,
      org_id:        process.env.VISA_ORG_ID,
      scope:         'boarding',
    }),
  }
);
const { access_token } = await oauthRes.json();

Exchange for an ec_token

Token-exchange grant produces a session-scoped ec_token — the only token your frontend ever sees.

// Step 2 — token-exchange grant
const ecRes = await fetch(
  'https://sandbox.api.visa.com/v1/oauth2/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type:         'urn:ietf:params:oauth:grant-type:token-exchange',
      subject_token:      access_token,
      subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
      solution_id:        process.env.VISA_SOLUTION_ID,
      org_id:             process.env.VISA_ORG_ID,
    }),
  }
);
const { ec_token } = await ecRes.json();
res.json({ sessionToken: ec_token });

Mount the component

Pass the ec_token from Step 3. The component renders inside a sandboxed iframe — card data and KYB documents never touch your DOM.

// React: mount the boarding component
import { VisaMerchantOnboarding } from '@visaacceptance/embed-js/react';

<VisaMerchantOnboarding
  sessionToken={ec_token}
  onSuccess={(r) => save(r.org_id)}
  onError={(e) => show(e)}
  onSessionTimeout={refresh}
/>

Handle events

Three callbacks. All required for production. onSessionTimeout in particular is mandatory — without it, merchants see a frozen form after 15 minutes with no recovery.

That's it Your Merchant Boarding component is live in sandbox. Run a test merchant through to verify the full flow, then move on to the go-live checklist when you're ready for production.