PCI Compliant SDK

Before You Start

Read the following guides before proceeding:

---

Overview

The PCI Compliant SDK is a set of npm packages for browser applications. Each package mounts one or more
iframes served from a Wirex-operated origin. The user types the card number, expiry and CVV inside those
iframes; the iframe posts the card data straight to Wirex and returns a token to your page. Your DOM, your
JavaScript and your servers never receive the PAN or the CVV.

Every frame authenticates with a user token — the per-user access token from
User Token Issuance (Login as User). The
SDK has no keys of its own, and S2S company tokens are not accepted. See
Which Token the SDK Needs.

Use it when your application collects or displays card data in a browser and you do not want that data in
your PCI scope. Everything the SDK produces — a card_id, an external card token, a completed 3DS
challenge — feeds the same REST flows documented in Card Top-Up,
Push to Card and Card Details.

Not the same package as the TypeScript SDK. @wirexapp/wpay-baas-sdk
(TypeScript / JavaScript SDK) wraps the REST API and on-chain wallet operations. The
PCI Compliant SDK covers only card-data surfaces. The two are installed and versioned independently and
can be used together.

Version. These pages document 1.0.0, the first stable release of the family. Every package ships
under the @wirexapp scope and releases in lockstep.

---

Packages

All packages release in lockstep under one version number, because they share the frame message protocol.
The current release is 1.0.0. Your lockfile must show that same version for @wirexapp/card-sdk-core and
every @wirexapp/card-* package — a version mismatch makes the loader and the frame refuse to
communicate.

---

Isolation Model

Your page (no card data)              Wirex frame origin              Wirex API
────────────────────────              ──────────────────              ─────────
npm package                ─mounts─►  card-field iframes
  • creates the iframes                 • user types PAN / CVV
  • receives events + tokens ◄──────    • validates, detects brand
                                        • POSTs card data direct ───►  tokenize
your flow continues                                                    card token
with the token only        ◄──────────  token + brand / bin / last4 ◄──

The npm packages carry no cardholder data. The iframes are served by Wirex from a dedicated origin, so the
browser's Same-Origin Policy prevents any script on your page — including an XSS or a compromised
dependency — from reading the card fields.

Two properties are enforced by Wirex, not by your integration:

• The frames' API endpoints are injected server-side. A compromised host page cannot redirect card data to
  another server. Selecting an environment is the only endpoint control you have.
• The frames are served with a frame-ancestors policy listing only the parent origins registered against
  your clientId. An unregistered origin renders an empty, browser-blocked frame.

---

Top-Up Collection Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your Page
    participant Frame as Wirex Card Frames
    participant BaaS as Wirex BaaS

    App->>Frame: 1. mount card field iframes
    User->>Frame: 2. type PAN / expiry / CVV / name
    Frame-->>App: 3. change event (validity + brand only)
    App->>Frame: 4. tokenizeTopUp (billing details)
    Frame->>BaaS: 5. POST card data
    BaaS-->>Frame: card_id
    Frame-->>App: 6. cardId, brand, bin, last4
    App->>BaaS: 7. POST /api/v1/cards/topup/estimate
    App->>BaaS: 8. POST /api/v1/cards/topup/execute
    BaaS-->>App: id, status, three_ds_state
    App->>Frame: 9. mount 3DS challenge on three_ds_state.url

---

Payout Collection Flow

sequenceDiagram
    participant User as Sender
    participant App as Your Page
    participant Frame as Wirex Card Frames
    participant BaaS as Wirex BaaS

    App->>Frame: 1. mount card-number iframe
    User->>Frame: 2. type destination PAN
    App->>Frame: 3. tokenizeOctDestination (cardholder name)
    Frame->>BaaS: 4. POST card data
    BaaS-->>Frame: card token
    Frame-->>App: 5. externalCardId, brand, bin, last4
    App->>BaaS: 6. POST /api/v2/recipients (type: Card)
    App->>BaaS: 7. POST /api/v1/cards/transfer/estimate
    App->>BaaS: 8. POST /api/v1/cards/transfer

---

Reveal Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your Page
    participant Frame as Wirex Reveal Frame
    participant BaaS as Wirex BaaS

    User->>App: 1. Request card details
    App->>BaaS: 2. POST /api/v1/confirmation/signature/verify
    BaaS-->>App: action_token
    App->>Frame: 3. mount reveal element (cardId + actionToken)
    Frame->>BaaS: 4. POST /api/v1/cards/{cardId}/details
    Frame->>BaaS: 5. POST /api/v1/cards/{cardId}/cvv
    BaaS-->>Frame: card_number, expiry_date, cvv
    Frame-->>App: 6. onStateChange status ready

---

Guides