English
Redirect Mode

Redirect Mode

Redirect Mode allows you to send the user directly to the KYC URL (in a new tab, window, or webview). Upon completing the flow -- approval, rejection, or cancellation -- the user is redirected back to the integrator's URL with the results in the querystring.

This approach is an alternative to Embedded mode (iframe) and is ideal when the iframe is not feasible or when you want full control over navigation.

Comparison: Embedded vs Redirect

FeatureEmbedded (Iframe)Redirect
Integration<iframe> on the same pageFull-page navigation or new tab
Result communicationpostMessage to the parent windowQuerystring on the return URL
Recommended useWeb portals, SPAsMobile apps (webview), direct links

Input Parameters

Include these parameters in the KYC entry URL, along with the guid:

ParameterRequiredTypeDescription
redirectUrlNoStringFull URL (with https://) where the user will be redirected upon completing the KYC.
stateNoStringOpaque value returned unchanged in the response. Use for CSRF validation or session correlation.

If redirectUrl is not provided, the system operates in Embedded mode (compatible with postMessage).

Response Parameters

Upon completion, the following query params are added to the redirectUrl:

ParameterDescription
resultKYC result: approved, rejected, or canceled.
submissionIdSubmission ID (available in flows with liveness).
reasonReason for rejection or error (optional).
stateSame value sent in the input (optional).

Completion Flow

The redirect occurs in two scenarios:

  1. Automatic completion -- The user completed all steps and the system returned a result (approved or rejected).
  2. Explicit exit -- The user clicked "Close" or canceled the process.

Fallback: If the redirectUrl is invalid (e.g., malformed URL), the system ignores the redirect and sends the result via postMessage, as in Embedded mode.

Examples

Entry URL

https://kyc-front.pixtopay.com.br/?guid=d3b07384d1&redirectUrl=https://meubanco.app/callback/kyc&state=user123_nonce

Return URL (after approval)

https://meubanco.app/callback/kyc?result=approved&state=user123_nonce&submissionId=sub_987654321

React Example -- callback page

import { useSearchParams } from "react-router-dom";
 
function CallbackKycPage() {
  const [searchParams] = useSearchParams();
  const result = searchParams.get("result");
  const state = searchParams.get("state");
 
  if (result === "approved") {
    return <div>Identidade verificada com sucesso.</div>;
  }
 
  return <div>Verificação rejeitada ou cancelada. Tente novamente.</div>;
}

Embedded Example (comparison) -- without redirect

window.addEventListener("message", (event) => {
  if (event.data?.type === "processCompleted") {
    const result = event.data.status; // "approved" | "rejected" | "canceled"
    const reason = event.data.reason;
    console.log("KYC finalizado:", result);
  }
});

Security

  • URL Validation: The redirectUrl is validated with new URL(). Malformed URLs or those with invalid schemes (e.g., javascript:) are silently rejected.
  • GUID Isolation: Redirect parameters are stored in localStorage scoped by GUID, preventing conflicts between simultaneous flows.
  • Open Redirect: The system redirects to any valid URL provided. The integrator should validate the request origin on their backend using the state parameter (we recommend signed HMAC).

Compatibility

Redirect Mode is 100% backward compatible. Existing integrations via iframe and postMessage continue to work normally. The redirect is only activated when redirectUrl is provided in the entry URL.

PixFace IFramePixFace SDK