# Card Capture IFrame API

To initiate the Card Capture IFrame, please insert the IFrame tag into your target page.

```markup
<iframe
  id="cardCaptureIframe"
  height="300"
  scrolling="no"
  style="border: 0;"
  src="{{cardCaptureIframeUrl}}">
</iframe>
```

Where `cardCaptureIframeUrl` is valid Card Capture URL.

## IFrame communication

To communicate with the IFrame to submit form or get results you should use [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) browser API.

### Submit Form

To submit Card Capture form you should trigger `submit` event.

```javascript
const cardCaptureIframe = document.getElementById("cardCaptureIframe");
cardCaptureIframe.contentWindow.postMessage("submit", "https://pci.vaultera.co");
```

### Validate Form

To Validate Card Capture form you should trigger `validate` event.

{% hint style="info" %}
This validation method can be used to get validity from state from your js code. With this you can build workflows on your side based on this information. For example, you can prevent form submission if the card in the iframe is not valid.

This validation also triggers on submit event and does the same validations as you can see in real time. So, if you don't have any external logic which is based on card form validity state you can just use the "submit" method.
{% endhint %}

```javascript
const cardCaptureIframe = document.getElementById("cardCaptureIframe");
cardCaptureIframe.contentWindow.postMessage("validate", "https://pci.vaultera.co");
```

### Handle response

To handle responses from Card Capture Form you should create `listener` function.

```javascript
const PCI_PROXY_DOMAIN = "https://pci.vaultera.co";
const listener = (event) => {
  if (event.origin !== PCI_PROXY_DOMAIN) {
    return;
  }
  if (event.data.valid) {
    console.log("card valid: ", event.data.valid);
  }
  if (event.data.success) {
    console.log(event.data);
  }
}

window.addEventListener("message", listener);
```

#### Validate response

```javascript
{
  "event_type": "validate",
  "valid": true|false
}
```

#### Submit response

```javascript
{
  "event_type": "submit",
  "success": true,
  "card": {
    "card_number": "411111******1111",
    "card_token": "<token>",
    "cardholder_name": "JHON DOE",
    "expiration_month": "11",
    "expiration_year": "2023",
    "service_code": "***",
    "card_type": "visa"
  }
}
```

## IFrame configuration

### Accepted card types

Param: `only|except`

Value: *list of card types*

Default: *none*

You can pass additional query param for card capture iframe and configure which cards you accept. This can be done in two ways.

1. You can set a list of cards you accept and only these cards would be allowed to be created from an iframe.&#x20;
2. You can provide a list of cards you want to exclude, for example American Express.&#x20;

To configure the list of card types you want to accept you should provide a `only` query param with a list of card types.

Example to accept only visa and mastercard:

```
https://pci.vaultera.co/api/v1/capture_form?session_token=<SESSION_TOKEN>&only=visa,mastercard
```

To accept all cards except some specific type you should provide `except` query params with list of card types.

Example to exclude American Express:

```
https://pci.vaultera.co/api/v1/capture_form?session_token=<SESSION_TOKEN>&except=american-express
```

List of card types:

* visa
* mastercard
* american-express
* money-club
* discover
* jcb
* unionpay
* maestro
* link
* me
* hyper
* hypercard

So if you want just to accept all cards except American Express you need to modify your card capture iframe url to something like this

```
https://pci.vaultera.co/api/v1/capture_form?session_token=<SESSION_TOKEN>&except=american-express
```

### Custom styles

Param: `style`

Value: style name

Default: *none*

Card capture iframe can be customized with your own css to match your needed look and feel. To load additional css styles you need to provide `style` query param with styles name. These styles can be added to your account by contacting support.

### Language

Param: `lang`

Value: en|ru

Default: en

To change language of your capture form `lang` query param needed to be specified.

Supported languages:

* de
* en
* el
* es
* is
* it
* pt
* ru

Any additional language can be added by contacting support.

### Service Code

#### Optional

Param: `service_code_optional`

Value: true|false

Default: false

Make service code optional and not require.

#### Hidden

Param: `service_code_visible`

Value: true|false

Default: true

Make service code not visible.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vaultera.co/card-capture-iframe-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.