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.
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:
| Value | Language |
|---|---|
| en | English |
| zh | Chinese (Simplified) |
| zh-Hant | Chinese (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.
https://airwallex.com/issuing/pci/v2/:cardId/details#:hash
Display card PIN iframe
The card PIN iframe can be displayed using the following endpoint.
https://airwallex.com/issuing/pci/v2/:cardId/pin/#:hash
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
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.