postMessage Protocol

Low-level reference for the PROPHETX_* postMessage events exchanged between your page and the ProphetX embed iframe.

📘

When to use this guide

If you're using one of the ProphetX SDKs (@prophetx/sdk-react, @prophetx/sdk-react-native, or @prophetx/sdk-js), the SDK handles all messaging for you. This guide is for partners who need direct iframe control — custom modal wrappers, non-JavaScript hosts, or advanced orchestration.

Message flow

A complete session follows this sequence:

Your page                              Embed (iframe)
    |                                       |
    |  <-- PROPHETX_EMBED_LOADED ---------- |  iframe mounted
    |                                       |
    |  --- PROPHETX_SESSION --------------> |  send JWT
    |  --- PROPHETX_THEME (optional) -----> |  send theme
    |                                       |
    |                                       |  validate token
    |                                       |  (client + server)
    |                                       |
    |  <-- PROPHETX_READY ----------------- |  session valid
    |                                       |
    |  <-- PROPHETX_RESIZE (repeated) ----- |  content height changes
    |                                       |
    |      ... user completes flow ...      |
    |                                       |
    |  <-- PROPHETX_SUCCESS --------------- |  transaction complete
    |      or PROPHETX_ERROR                |  something went wrong
    |                                       |  (the embed shows its own success
    |                                       |   or retry screen; keep it open)
    |                                       |
    |  <-- PROPHETX_CANCEL ---------------- |  user closed the flow
    |      or PROPHETX_SUCCESS_ACTION       |  user pressed the success button
    |                                       |
    |  --- (remove iframe) ---              |

If the token expires mid-flow:

    |  <-- PROPHETX_SESSION_EXPIRED ------ |  an API call returned 401
    |                                      |
    |  --- PROPHETX_SESSION_REFRESH -----> |  send fresh JWT within 10 s
    |                                      |
    |        ... flow resumes ...          |

If you don't answer within 10 seconds, or the embed has to ask more than 3 times in 10 seconds, it gives up and shows its session-expired screen. It sends nothing further, so remove the iframe and open a new one with a fresh token.

Origins

  • Your page's origin must be on the allowlist ProphetX configures for each environment. Wildcard subdomains (https://*.yourdomain.com) are supported. Register every origin you embed from, including localhost ports for development.
  • The embed pins your origin to the one that sent the first PROPHETX_SESSION. After that it only accepts messages from that origin, and sends every message to it.
  • PROPHETX_EMBED_LOADED is the one exception: it's sent to '*', because the embed doesn't know your origin yet. It carries no data.
  • On your side, check both event.origin and event.source. The origin must be the embed's origin, and event.source must be your iframe's contentWindow, so a second ProphetX iframe on the same page can't be mistaken for this one.

Outbound messages (Embed → Your page)

These are the messages your message event listener will receive from the embed.

PROPHETX_EMBED_LOADED

The iframe has mounted and is waiting for a session token. This is always the first message the embed sends.

{ "type": "PROPHETX_EMBED_LOADED" }

When you receive this: respond immediately with PROPHETX_SESSION (and optionally PROPHETX_THEME).

PROPHETX_READY

The route's first screen has rendered and the user can interact with it. Each route sends it once: deposit and withdraw after the payment methods load, Terms after the terms document loads, ID Upload and 1-Click Signup as soon as they mount.

PROPHETX_READY is never sent when the flow can't start — a session error, a geofence block when the flow opens, a failure to load payment methods, or ROUTE_NOT_FOUND. Use a timeout on your loading state rather than waiting for it forever.

{ "type": "PROPHETX_READY" }

When you receive this: the embed is live. Show it to the user if it was hidden during loading.

PROPHETX_SUCCESS

A flow reached its success outcome:

  • Deposit: the money is in the user's ProphetX balance, or the payment was accepted and is still settling (the embed shows "Deposit Processing"). Cash at Retail never sends it: the user leaves with a barcode, and the flow ends with PROPHETX_CANCEL. Wire Transfer only shows instructions and doesn't send it either.
  • Withdrawal: the withdrawal was accepted. A debit-card withdrawal is held for review, so the money hasn't arrived yet.
  • Terms and Conditions (/tandc): the user accepted, or had already accepted the current version. The payload is always { "transactionId": "tandc", "amount": 0 }.
{
  "type": "PROPHETX_SUCCESS",
  "payload": {
    "transactionId": "tx_abc123",
    "amount": 50.00
  }
}
FieldTypeDescription
transactionIdstringTransaction identifier. Store it on your backend. For PayNearMe deposits it is a reference the embed creates, not a backend transaction ID.
amountnumber | undefinedDollar amount of the transaction. May be omitted in edge cases.

When you receive this: record the transactionId and refresh the user's balance. Don't close the embed: it now shows its own success screen. Remove the iframe when PROPHETX_CANCEL or PROPHETX_SUCCESS_ACTION arrives.

PROPHETX_ERROR

Something went wrong — a failed transaction, an invalid session, a geofence block, or an unexpected runtime error.

{
  "type": "PROPHETX_ERROR",
  "payload": {
    "code": "DEPOSIT_FAILED",
    "message": "The deposit could not be completed."
  }
}
FieldTypeDescription
codestringMachine-readable error code. Every code is listed in Error Codes.
messagestringDescription for your logs. Don't display it: it can contain raw transport or provider text, and the embed has already shown the user its own error screen.

When you receive this: log it. Don't close the embed on most codes; the embed shows an error screen, often with a retry. Some codes (like SESSION_EXPIRED) need specific handling — see the error codes table.

PROPHETX_CANCEL

The user explicitly closed or cancelled the flow (e.g. tapped a close button inside the embed).

{ "type": "PROPHETX_CANCEL" }

When you receive this: close the embed. No error occurred — the user chose to leave. The embed also sends this from its own success and error screens when the user taps Close, so it can arrive after PROPHETX_SUCCESS or PROPHETX_ERROR.

PROPHETX_SUCCESS_ACTION

The user pressed the button on the deposit or withdrawal success screen, and you asked to handle that button. The embed sends this only when the iframe URL includes successAction=1, optionally with successButtonLabel=<text> (at most 40 characters, not translated). Without those parameters the button starts another deposit or withdrawal inside the embed.

{ "type": "PROPHETX_SUCCESS_ACTION" }

When you receive this: close the embed and take the user where you want them next. PROPHETX_CANCEL doesn't follow.

PROPHETX_RESIZE

The embed's content height changed. Sent whenever the visible content grows or shrinks — for example, when a form expands or an error banner appears.

{
  "type": "PROPHETX_RESIZE",
  "payload": {
    "height": 580
  }
}
FieldTypeDescription
heightnumberContent height in pixels. A value of 0 means the embed has no content — use a default height (420px is recommended).
widthnumber | undefinedOnly 1-Click Signup sends it, because Verified's modal needs a narrower frame. 0 means "go back to your default width". Other routes omit it.

When you receive this: update the iframe's height style to match. This prevents scrollbars inside the iframe and gives users a seamless experience.

PROPHETX_SESSION_EXPIRED

An API call inside the open flow returned 401, usually because the JWT expired while the user was on a screen. The embed pauses until it receives a fresh token.

{ "type": "PROPHETX_SESSION_EXPIRED" }

When you receive this: fetch a new JWT from your backend and send it back via PROPHETX_SESSION_REFRESH within 10 seconds. If you can't, remove the iframe: the embed stays on its session-expired screen and won't recover. A token that is already expired when the flow opens doesn't produce this message; it produces PROPHETX_ERROR with SESSION_EXPIRED.

PROPHETX_GEOFENCE_BLOCKED

The user's location isn't eligible, according to the location check in their session token. The embed sends this when the flow opens and shows its own blocked screen. It never fires on 1-Click Signup, which runs before a user exists. A second check runs just before a deposit or withdrawal is submitted and reports through PROPHETX_ERROR with GEOFENCE_BLOCKED instead — see Error Codes.

{
  "type": "PROPHETX_GEOFENCE_BLOCKED",
  "payload": {
    "stateCode": "unknown",
    "reason": "unknown"
  }
}
FieldTypeDescription
stateCodestringCurrently always "unknown". Kept for compatibility; don't branch on it.
reasonstringCurrently always "unknown". Don't display it.

When you receive this: show your own location messaging. The user can't proceed from this state.

Identity verification: two separate message families

There are two distinct flows for identity verification, with different messages — they are not interchangeable:

  • 1-Click Signup (new users, useOneClickSignup) — Verified Inc's own hosted modal collects and shares an identity. KYC hasn't run yet at this point.
  • Document verification (existing users re-verifying after FAILURE, useKyc/useIdUpload) — a government-ID photo upload reviewed by IDComply. This is the KYC decision.

PROPHETXONE_CLICK_SUCCESS / FAILED / _DECLINED

Terminal outcomes of 1-Click Signup.

{
  "type": "PROPHETX_ONE_CLICK_SUCCESS",
  "payload": { "identityUuid": "id_f47ac10b-58cc-4372-a567-0e02b2c3d479" }
}
MessagePayloadMeaning
PROPHETX_ONE_CLICK_SUCCESS{ identityUuid: string }User shared their identity. Always includes identityUuid — 1-Click always yields an identity when it succeeds.
PROPHETX_ONE_CLICK_FAILED{ reason: string, retryable?: boolean }Terminal failure. retryable is true only when a fresh session key would help: INVALID_SESSION_KEY, SESSION_TIMEOUT, or SHARE_CREDENTIALS_ERROR. Mint a new key and reopen. Otherwise, fall back to manual signup.
PROPHETX_ONE_CLICK_DECLINED{}The user chose not to share. Not an error — fall back to manual signup.
triangle-exclamation

This means "identity shared," not "KYC passed." KYC hasn't been asked for yet at this point — it only starts once your backend redeems the identity at POST /private/v1/users/one-click. The resulting user can still resolve to FAILURE, MORTALITY, PEP, or OFAC. Poll GET /private/v1/users/USERID/kyc-status (or listen for the KycStatusEvent webhook) for the real result, per User Onboarding.

When you receive _SUCCESS: redeem the identity server-side. When you receive _DECLINED: show your own manual signup form. When you receive _FAILED: check retryable — if true, mint a fresh session key and reopen; otherwise fall back to manual signup.

PROPHETXKYC_SUCCESS / FAILED / _PENDING

Terminal outcomes of document verification (useKyc/useIdUpload). Unlike 1-Click, this is the actual KYC decision — by the time one of these fires, the verdict is final (except _PENDING, which means review is still in progress).

{ "type": "PROPHETX_KYC_SUCCESS", "payload": {} }
MessagePayloadMeaning
PROPHETX_KYC_SUCCESS{ identityUuid?: string }Document verified. identityUuid is always absent — the IDPV API behind this flow returns none. You already have the user's UUID from POST /users.
PROPHETX_KYC_FAILED{ reason: string, retryable?: boolean }Rejected, and final. retryable is always false: a photo the user can retake stays inside the embed with a Try again button and sends nothing. reason is one of MORTALITY, PEP, OFAC, ATTEMPTS_EXHAUSTED, NOT_ELIGIBLE — for logging and routing only, never display it.
PROPHETX_KYC_PENDING{}Document submitted, review not yet resolved.

When you receive this: for _SUCCESS, treat the user as verified — no further polling needed, this flow already waited for the verdict. It also fires for a user who was already verified before opening the flow. For _FAILED, the user can't verify through this flow; route them to support. For _PENDING, show a "still under review" state.

PROPHETX_HEADER_UPDATE (not sent)

This message type is still defined, and the SDKs still listen for it, but the embed doesn't send it. The embed always renders its own header, title and back button inside the iframe. Don't build custom modal chrome that depends on it.

Inbound messages (Your page → Embed)

These are the messages you send to the embed iframe via iframe.contentWindow.postMessage(message, embedOrigin).

PROPHETX_SESSION

Delivers the signed JWT to the embed. Send this immediately after receiving PROPHETX_EMBED_LOADED.

{
  "type": "PROPHETX_SESSION",
  "payload": {
    "token": "eyJhbGciOiJFZERTQSIs..."
  }
}
FieldTypeDescription
tokenstringA signed JWT. See Embedded UI for how to mint one.

The embed accepts only the first PROPHETX_SESSION it receives; later ones are ignored. To use a different token, open a new iframe.

It validates the token in this order:

  1. Client-side — decodes the JWT and checks exp.
  2. Server-side — GET /embed/v1/token/validate checks the signature, issuer and expiry. If that request fails with a 5xx or a network error, the embed proceeds on the client-side check alone, so a server outage doesn't block your users.
  3. Origin — the origin that sent PROPHETX_SESSION must be on the allowlist (see Origins).

If a step fails, it sends PROPHETX_ERROR with SESSION_EXPIRED, SESSION_INVALID or ORIGIN_UNAUTHORIZED. Otherwise the route renders and sends PROPHETX_READY.

PROPHETX_SESSION_REFRESH

Provides a fresh JWT after the embed reports PROPHETX_SESSION_EXPIRED. Only send this in response to an expiration: the embed ignores it at any other time.

{
  "type": "PROPHETX_SESSION_REFRESH",
  "payload": {
    "token": "eyJhbGciOiJFZERTQSIs..."
  }
}
FieldTypeDescription
tokenstringA freshly signed JWT replacing the expired one.

The embed re-validates the new token and resumes the flow if valid. It waits 10 seconds for your answer, and gives up if it has to ask more than 3 times in 10 seconds; either way it shows its session-expired screen and sends nothing further.

PROPHETX_THEME

Configures the embed's visual appearance. Send alongside PROPHETX_SESSION on load, or at any time to update the theme dynamically (e.g. when the user toggles dark mode in your app).

{
  "type": "PROPHETX_THEME",
  "payload": {
    "primaryColor": "#e91e63"
  }
}

All fields are optional. Each message starts from the default dark palette and applies your overrides on top; it replaces the previous theme rather than merging with it. There is no light/dark flag: send a full light palette in colorOverrides for a light look (see the Theming Guide).

FieldTypeDescription
primaryColorstringPrimary brand color (CSS color value). Ignored when colorOverrides has keys.
colorOverridesobjectFine-grained color token overrides. See below.
spacingOverridesobjectSpacing scale overrides (xs through xl).
radiusOverridesobjectBorder-radius overrides (sm, md, lg, full).
fontSizeOverridesobjectFont-size scale overrides (xs through xl).

All color override tokens
TokenDescription
primaryPrimary brand color
primaryHoverPrimary color on hover
primaryForegroundText on primary background
secondarySecondary brand color
secondaryHoverSecondary color on hover
backgroundInput fields and inset panels
surfaceEmbed background and cards
surfaceElevatedElevated surface (modals, dropdowns)
textPrimary text color
textMutedSecondary text color
textSubtleTertiary/hint text color
borderDefault border color
borderSubtleSubtle/light border color
errorError text/icon color
errorBackgroundError banner background
successSuccess text/icon color
successBackgroundSuccess banner background
warningWarning text/icon color
warningBackgroundWarning banner background
ctaCall-to-action button background
ctaHoverCTA button hover state
ctaForegroundText on CTA buttons
filledFilled button background
filledHoverFilled button hover state
filledForegroundText on filled buttons
dangerDanger/destructive action color
dangerHoverDanger hover state
dangerForegroundText on danger buttons

PROPHETX_LOCALE

Sets the language used inside the embed. Send alongside PROPHETX_SESSION on load, or at any time to switch languages dynamically (e.g. when the user changes locale in your app).

{
  "type": "PROPHETX_LOCALE",
  "payload": {
    "locale": "es"
  }
}
FieldTypeDescription
localestringBCP 47 locale tag. Currently supported: "en" (default), "es". Unknown locales fall back to "en".

The embed swaps its UI strings as soon as the message is received. No restart or re-mount required.

PROPHETX_BACK

Cancels the current flow; it doesn't go back a step. On deposit, withdraw and Terms, the embed ends the flow and replies PROPHETX_CANCEL. Every other route ignores it. Use it when your own chrome needs to close the flow cleanly, for example on a system back gesture.

{ "type": "PROPHETX_BACK" }

The back button inside the embed handles in-flow navigation on its own; you don't need to send anything for it.

PROPHETX_CLOSE (no effect)

The embed accepts this message type but nothing acts on it today. To close a flow, remove the iframe, or send PROPHETX_BACK first if you want the embed to report PROPHETX_CANCEL.

Error codes

PROPHETX_ERROR carries the same codes the SDKs pass to onError. They're all listed, with what the embed shows after each one and what to do, in Error Codes. The ones a raw-iframe integration must handle:

CodeWhat to do
SESSION_EXPIREDThe token was already expired when the iframe opened. Remove the iframe and open a new one with a fresh token.
SESSION_INVALID / ORIGIN_UNAUTHORIZEDPass the /private/v1/tokens token unchanged, or register your origin; retrying won't help.
GEOFENCE_BLOCKEDThe pre-submit check failed, or the session couldn't be re-validated. Reopen with a fresh token before showing location messaging.
DEPOSIT_UNCONFIRMED / WITHDRAWAL_UNCONFIRMEDThe outcome is unknown. Refresh the user's balance before they retry.
DEPOSIT_WALLET_WRITE_FAILED / WITHDRAWAL_WALLET_WRITE_FAILEDMoney moved but the wallet didn't update. Send the transaction ID to ProphetX support.
ROUTE_NOT_FOUNDYour iframe URL doesn't match an embed route. Fix the URL.

For every other code, log it and leave the iframe open: the embed shows its own error screen, usually with Try again. Provider reasons (an AeroPay refusal, a PayNearMe code) appear inside message, never as the code.

Complete example

A minimal integration without any SDK — just raw postMessage:

<button id="open-deposit">Deposit</button>
<div id="embed-container" style="display:none"></div>

<script>
  // Production. Sandbox: https://isv-embed-fe-embed-sandbox.vercel.app/deposit
  // Staging: https://isv-embed-fe-embed.vercel.app/deposit
  const EMBED_URL = 'https://embed.prophetx.co/deposit';
  const embedOrigin = new URL(EMBED_URL).origin;
  let iframe;

  document.getElementById('open-deposit').addEventListener('click', async () => {
    // 1. Fetch a session token from your backend
    const res = await fetch('/api/prophetx-token');
    const { token } = await res.json();

    // 2. Create the iframe
    iframe = document.createElement('iframe');
    iframe.src = EMBED_URL;
    iframe.style.width = '100%';
    iframe.style.height = '420px';
    iframe.style.border = 'none';

    const container = document.getElementById('embed-container');
    container.innerHTML = '';
    container.style.display = 'block';
    container.appendChild(iframe);

    // 3. Listen for messages from the embed
    window.addEventListener('message', function handler(event) {
      if (event.origin !== embedOrigin) return;
      if (event.source !== iframe.contentWindow) return;

      const { type, payload } = event.data;

      switch (type) {
        case 'PROPHETX_EMBED_LOADED':
          // Respond with the session token
          iframe.contentWindow.postMessage(
            { type: 'PROPHETX_SESSION', payload: { token } },
            embedOrigin
          );
          // Optionally set a theme
          iframe.contentWindow.postMessage(
            { type: 'PROPHETX_THEME', payload: { primaryColor: '#e91e63' } },
            embedOrigin
          );
          break;

        case 'PROPHETX_READY':
          console.log('Embed is ready');
          break;

        case 'PROPHETX_RESIZE':
          iframe.style.height = (payload.height || 420) + 'px';
          break;

        case 'PROPHETX_SUCCESS':
          // Record it, but keep the embed open: it shows its own success screen
          console.log('Transaction complete:', payload.transactionId, payload.amount);
          break;

        case 'PROPHETX_ERROR':
          // Log it; the embed shows its own error or retry screen
          console.error('Error:', payload.code, payload.message);
          // An expired token at open can't be refreshed in place: start over
          if (payload.code === 'SESSION_EXPIRED') cleanup(handler);
          break;

        case 'PROPHETX_CANCEL':
        case 'PROPHETX_SUCCESS_ACTION':
          // The flow is over
          cleanup(handler);
          break;

        case 'PROPHETX_SESSION_EXPIRED':
          // Fetch a fresh token and send it back
          fetch('/api/prophetx-token')
            .then(r => r.json())
            .then(({ token: freshToken }) => {
              iframe.contentWindow.postMessage(
                { type: 'PROPHETX_SESSION_REFRESH', payload: { token: freshToken } },
                embedOrigin
              );
            });
          break;
      }
    });
  });

  function cleanup(handler) {
    window.removeEventListener('message', handler);
    document.getElementById('embed-container').style.display = 'none';
    if (iframe) iframe.remove();
  }
</script>

Best practices

Always validate the origin and the source. Only process messages where event.origin matches the embed URL's origin and event.source is your iframe's contentWindow. Never use '*' as the targetOrigin when posting messages to the iframe — always use the embed's origin.

// Good
iframe.contentWindow.postMessage(message, 'https://embed.prophetx.co');

// Bad — any page could intercept this
iframe.contentWindow.postMessage(message, '*');

Handle PROPHETX_RESIZE for a smooth UX. Without it, the iframe will show internal scrollbars as content changes. Set the iframe height to payload.height on every resize event, and use 420px when the height is 0.

Always handle session refresh. Tokens are short-lived (10 minutes by default). If a user takes time filling out a form, the token will expire. Listen for PROPHETX_SESSION_EXPIRED and respond with a fresh token within 10 seconds to avoid interrupting the user's flow.

Clean up the event listener. Remove your message event listener when the flow ends (PROPHETX_CANCEL or PROPHETX_SUCCESS_ACTION). Stale listeners can process messages from an old iframe if the user opens a second flow.


Did this page help you?