Overview

The SimpliFi Virtual Card SDK allows you to securely display sensitive card information (PAN, CVV) and manage PINs within your application. To ensure PCI-DSS compliance, these details are rendered directly from SimpliFi servers via a secure web page.

Base URL: https://{env}-virtualcard.simplifipay.com/simplifi-sdk/

Parameters through postMessage

The SDK accepts credentials via postMessage. The message is delivered securely to the SDK page using the browser postMessage API after the SDK has fully loaded and signalled readiness.

The Handshake

Host loads the SDK URL in an iframe or WebView

SDK mounts and sends SIMPLIFI_SDK_READY to the host

Host receives SIMPLIFI_SDK_READY and sends SIMPLIFI_SDK_CONFIG with credentials

SDK validates the config and sends SIMPLIFI_SDK_CONFIG_ACK (accepted) or SIMPLIFI_SDK_CONFIG_ERROR (rejected)

On flow completion, SDK sends SDK_FLOW_RESULT

Important: Never send credentials before receiving SIMPLIFI_SDK_READY. The SDK may not have mounted yet and the message will be lost.

Config Payload

Sent to the SDK after it signals readiness via SIMPLIFI_SDK_READY.

Field	Type	Required	Description
token	String	Yes	Bearer token obtained from the Auth API.
cardID	String	Yes	The unique 36-character ID of the card to display.
userID	String	Yes	The unique 36-character ID of the cardholder.
action	String	Yes	The operation to perform (see list below).

Available Actions

Action	Description
view_card_detail	Reveal Card Number and CVV
set_pin	Set a new PIN for Physical Card
activate_card	Activate a new physical Card

Message Protocol

The SDK and host communicate via postMessage. All messages are JSON objects.

SDK → Host

eventName	source	Description
`SIMPLIFI_SDK_READY`	`simplifi-sdk`	SDK loaded and waiting for config
`SIMPLIFI_SDK_CONFIG_ACK`	`simplifi-sdk`	Config accepted, SDK initialising
`SIMPLIFI_SDK_CONFIG_ERROR`	`simplifi-sdk`	Config rejected — check `errorCode` and `message`
`SDK_FLOW_RESULT`	`simplifi-sdk`	Flow completed — check `status` (`SUCCESS`/`FAILURE`) and `flow`

Host → SDK

eventName	source	Description
`SIMPLIFI_SDK_CONFIG`	`simplifi-parent`	Send config payload to SDK

Config message

{
  "source": "simplifi-parent",
  "eventName": "SIMPLIFI_SDK_CONFIG",
  "payload": {
    "token": "YOUR_TOKEN",
    "cardId": "YOUR_CARD_UUID",
    "userId": "YOUR_USER_UUID",
    "action": "view_card_detail"
  }
}

Flutter Integration

Dependency

Step 1 — Define SDK URL and origin

sdkOrigin scopes all postMessage communication to the SDK domain only. Derive it from sdkUrl — never hardcode it separately.

Step 2 — Set up WebViewController

All three parts below are required. Missing any one will break the integration.

Step 3 — Load the SDK

Always append ?platform=webview to the URL. This tells the SDK it is running inside a WebView and to use SimplifiSDKChannel instead of window.parent. Without this param the SDK will not send any events.

Call this after the controller is fully configured in Step 2.

Step 4 — Handle incoming SDK messages

The SDK sends four events. You must handle all of them.

Step 5 — Send config to the SDK

Only called from inside the SIMPLIFI_SDK_READY handler. Never send config before the SDK signals ready — the message will be lost.
Use a flag to ensure config is sent only once per session.

Step 6 — Timeout handling (Optional)

The SDK should respond within a few seconds. Add a timeout in case the page fails to load or the WebView is blocked.

Web Integration

To integrate this into a website (React, Vue, or plain HTML), use a standard HTML iFrame.

Create Element: Add an <iframe> tag to your page structure.

Styling: Ensure the iframe has sufficient height (approx. 600px) and width (100%) to display the card visually properly. No additional headers or authentication logic is needed inside the browser code; the token in the URL handles validation.

Security Notes

Always set targetOrigin to the SDK origin when calling postMessage — never "*".

Always validate e.origin on all incoming messages before processing.

?platform=webview is required for Flutter — without it the SDK will not dispatch any events in a WebView context.

Never log the token field from the config payload.

SimpliFi Virtual Card SDK Integration Guide

Overview#

Parameters through postMessage#

Message Protocol#

SDK → Host#

Host → SDK#

Flutter Integration#

Dependency#

Step 1 — Define SDK URL and origin#

Step 2 — Set up WebViewController#

Step 3 — Load the SDK#

Step 4 — Handle incoming SDK messages#

Step 5 — Send config to the SDK#

Step 6 — Timeout handling (Optional)#

Web Integration#

Security Notes#