Skip to main content

Integrate Strong Customer Authentication in a web app

Learn how to run Strong Customer Authentication (SCA) from your web app, for both signing in (OAuth) and consenting to sensitive operations.

Swan opens SCA in the user's browser. Your web app redirects the user to a Swan URL, Swan handles authentication, then Swan redirects the user back to a URL you own.

Open Swan pages in the top-level browser only

Don't open Swan's authorization, consent, or sensitive card information pages:

  • In an iframe
  • In a WebView
  • In a popup (for example, with window.open)

Swan no longer supports these flows, and they stop working from 31 December 2026.

Instead, redirect the user to the URL:

  • On the web, in the current browser tab.
  • In a mobile app, in the device's browser or an in-app browser tab (SFSafariViewController on iOS, Chrome Custom Tabs on Android).

How it works​

  1. Your server gets a Swan URL: the authorization URL for sign-in, or the consentUrl returned by a sensitive operation.
  2. Your web app redirects the user to that URL in the current tab.
  3. The user completes SCA. On a phone, they do it in the same tab. On a computer, Swan's page asks for their phone number, sends them an SMS with a link, and shows a "Check your phone" message while they confirm or cancel on the phone.
  4. Swan redirects the tab to your redirect URL with query parameters. On a computer, this happens automatically once the user finishes on their phone. They don't need to do anything in the tab.
  5. Your server checks the result with the Swan API, then shows the user the next step.

Sign in with OAuth​

Follow the Get a user access token guide to build the authorization URL and exchange the code.

On the web, send the user to the authorization URL with a plain redirect:

// Server: build the URL, then redirect the user's browser to it
app.get("/auth", (req, reply) => {
const params = new URLSearchParams({
client_id: "$YOUR_CLIENT_ID",
response_type: "code",
redirect_uri: "https://my-company.com/auth/callback", // registered in your Dashboard
scope: "openid offline",
state: generateUserState(req),
});
return reply.redirect(`https://oauth.swan.io/oauth2/auth?${params}`);
});

Swan sends the user back to redirect_uri with code and state in the query string. Check that state matches before exchanging the code.

This example uses the viewCardNumbers mutation. The same flow applies to every sensitive operation.

Call the mutation with a user access token, setting consentRedirectUrl to a page on your site.

app.post("/cards/:cardId/numbers", async (req, reply) => {
const { consentUrl } = await swanClient.viewCardNumbers({
input: {
cardId: req.params.cardId,
consentRedirectUrl: "https://my-company.com/cards/callback",
},
});
return reply.json({ consentUrl });
});

In the browser, redirect in the current tab.

const { consentUrl } = await fetch("/cards/123/numbers", { method: "POST" }).then((r) => r.json());
window.location.assign(consentUrl);

After SCA, Swan redirects the user to consentRedirectUrl and adds these query parameters:

  • consentId.
  • env: Sandbox or Live.
  • status: Accepted, CustomerRefused, OperationCommitting, Created, Started, Expired, Failed, or Canceled.
  • resourceId, if the consent only impacts one resource.

The status parameter is informational. Always confirm the consent with the API before acting on it.

Open in API Explorer
query GetConsentStatus {
consent(id: "$YOUR_CONSENT_ID") {
id
status
updatedAt
}
}
app.get("/cards/callback", async (req, reply) => {
const { consent } = await swanClient.getConsentStatus({ id: req.query.consentId });
if (consent.status !== "Accepted") {
return reply.redirect("/cards?error=consent");
}
return reply.redirect("/cards?numbers=shown");
});

Good to know​

  • Consent links time out 20 minutes after being opened. Request a new consentUrl if the user comes back later.
  • For card numbers, the consentUrl only works in the browser where it was opened, even if the user confirms SCA on their phone. The same URL doesn't work in another browser or in a private window. For five minutes after the user consents, you can reopen the same consentUrl without repeating SCA.
  • Use the state parameter on OAuth redirects to protect against Cross-Site Request Forgery (CSRF).