Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewHow Airwallex Issuing worksSupported regions and currenciesSupported card programs
Use Cases
Manage cards
Retrieve sensitive card details
Secure iframes
Cancel or freeze a card

Secure iframes

As an Airwallex customer, you are required to be PCI compliant to retrieve sensitive details of individual cards or cards issued to connected accounts (if you have a Scale implementation) using Get sensitive card details API.

The PAN delegation feature allows you to retrieve sensitive details using a secure token in a PCI-compliant manner regardless of your PCI compliance status.

Before you begin

  • Contact your Airwallex Account Manager to enable Issuing APIs, Cards, and PAN delegation for your Airwallex account.
  • Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.

Step 1: Retrieve a token

Use Create a PAN token API with the card_id parameter (the ID of the individual card or the card issued to the connected account). Note that as a platform account, must specify the connected account’s open ID (starting with the prefix acct_) in the x-on-behalf-of header as you are acting on behalf of the connected account.

A successful response will return a token and its expiration date. The token expires after a minute from when it’s issued. The iframe in the next step will need to be loaded within this time.

Example request
Example response

Step 2: Prepare a hash

After retrieving the token, prepare a hash for the iframe. The hash allows you to inject the initial values and options for the iframe. Currently, its typing is as below:

The hash accepts three fields described in the following sections.

rules [Optional]

To provide a consistent, seamless user experience when displaying the card details or card PIN, you can provide rules to style the iframe. Rules are a map of selectors and CSS properties. Both the selectors and the CSS properties are white listed.

Here's an example of hash with style configuration.

The available CSS properties are listed below, for a list of available selectors, see Style iframe.

langKey [Optional]

You can use langKey to define the language of the iframe. When not provided or if the specified language is unavailable, it defaults to “en”. The list of valid langKey values include:

zhChinese (Simplified)
zh-HantChinese (Traditional)

Step 3: Embed iframe on your page

You can embed two types of iframes on your page:

  • The card details iframe displays the card number, expiry and cvv.
  • The card PIN iframe displays the card PIN

Display card details iframe

The card details iframe can be displayed using the following endpoint.

Display card PIN iframe

The card PIN iframe can be displayed using the following endpoint.

The PIN iframe does not accept any langKey as it only displays numbers.

Step 4: Style iframe

You can style the iframe by providing rules when preparing the hash.

Style card details iframe

The available selectors for the card details iframe are listed below:

Example code

Styled card details iframe

The example code above creates the styling changes as shown in the visual.

Before styling vs after styling

Before vs After card iframe styling

Style card PIN iframe

The available selectors for the card PIN iframe are:

Step 5: Handle iframe event lifecycle

The iframe uses the postMessage API to inform the parent page about its lifecycle including load status and/or errors. Possible event types for the card details iframe are listed below.

The card PIN iframe has the same events except details is replaced with pin.

Full example code (React)

On this page