> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a Card Entry Form

> Build a URL that renders a PCI Booking card capture form. Use it as an iframe src or redirect the cardholder to it.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form">
  Embed a secure card capture form in your website
</Card>

This is not a typical API call that you make from your server. Instead, you build a URL with query parameters and use it in one of two ways:

* **iframe**: set it as the `src` attribute of an iframe element on your page
* **Redirect**: redirect the cardholder's browser to this URL as a standalone page

The URL renders a secure card capture form hosted by PCI Booking. When the cardholder submits the form, PCI Booking tokenizes the card and redirects to your `success` URL with the token details, or to your `failure` URL if something goes wrong.

```
https://service.pcibooking.net/api/payments/capturecard?accessToken=YOUR_TOKEN&brand=YOUR_BRAND&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure&postMessageHost=yoursite.com
```

<Note title="URL building tips">
  * All parameter values must be URL-encoded.
  * All URLs you pass (success, failure, postMessageHost) must use HTTPS.
  * See the [Hosted Card Entry Form guide](/capture-cards/hosted-card-entry-form) for a visual preview of the rendered form.
</Note>

<Info>
  If you prefer a clean iframe URL without query parameters, use the [session-based card entry form](/capture-cards/hosted-card-entry-form#option-2-api-session) instead. That method sends parameters in a server-side POST and returns a ready-to-use iframe URL.
</Info>

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField query="accessToken" type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField query="sessionToken" type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

All parameters are passed as **query string** parameters in the URL.

### Core Parameters

<ParamField query="accessToken" type="string">
  Access token for authentication. Recommended over session token.
</ParamField>

<ParamField query="sessionToken" type="string">
  Session token for authentication.
</ParamField>

<ParamField query="brand" type="string" required>
  Your PCI Booking username, used to identify your account.
</ParamField>

<ParamField query="language" type="string" required>
  Form language in ISO 639-1 format (e.g. `en`, `fr`, `de`). Unsupported languages fall back to English. See [custom translations](/account-setup/custom-translations).
</ParamField>

<ParamField query="postMessageHost" type="string" required>
  The domain of the host page where the iframe is displayed (e.g. `yoursite.com`). Required for postMessage communication between the form and your page.
</ParamField>

<ParamField query="success" type="string">
  URL to redirect to after successful card capture. The token details are appended as query parameters. Strongly recommended. See [success/failure URLs](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField query="failure" type="string">
  URL to redirect to if the card capture fails. See [success/failure URLs](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField query="creatorReference" type="string">
  A reference value you define, which you can later use to [query for this token](/manage-tokens/query-retrieve).
</ParamField>

### Card Form Display

<ParamField query="autoDetectCardType" type="boolean" default="false">
  When `true`, the form detects the card type from the card number automatically. When `false`, a dropdown menu is shown for manual card type selection.
</ParamField>

<ParamField query="defaultCardType" type="string">
  Which card type is pre-selected in the dropdown menu (only relevant when `autoDetectCardType` is `false`).
</ParamField>

<ParamField query="cardTypes" type="string">
  Comma-separated list of accepted card types. If omitted or no valid types are found, all card types are shown.
</ParamField>

<ParamField query="showOwnerId" type="boolean" default="false">
  Show an "Owner ID" field on the form. Required in some countries.
</ParamField>

<ParamField query="expirationMonths" type="string" default="numbers">
  Format of the expiration month dropdown. `numbers` shows `01, 02, ...`, `names` shows `January, February, ...`
</ParamField>

<ParamField query="minExpiration" type="string">
  Minimum allowed expiration date in `mmyyyy` format (e.g. `012027`). Useful when the card must be valid past a check-in date.
</ParamField>

<ParamField query="nameOnCardValidation" type="string">
  Additional validation for the Name on Card field. `NO_DIGITS` prevents digits in the name.
</ParamField>

<ParamField query="autoFocus" type="boolean" default="true">
  Auto-focus the first form field when the page loads. Focuses the card number field if `autoDetectCardType` is `true`, or the card type dropdown otherwise.
</ParamField>

### Styling

<ParamField query="css" type="string">
  CSS resource name. See [managing stylesheets](/account-setup/stylesheets). If omitted, PCI Booking's default stylesheet is used.
</ParamField>

<ParamField query="removeBaseCss" type="boolean" default="false">
  When `true`, removes PCI Booking's base CSS entirely. The base CSS does not collide with your site's styles, so this is rarely needed.
</ParamField>

### CVV

<ParamField query="cvv" type="boolean" default="false">
  When `true`, saves the CVV in PCI Booking's vault alongside the card. Remember to set a [CVV Retention Policy](/capture-cards/cvv-retention-policy) to control how long the CVV is stored.
</ParamField>

### 3D Secure

<Warning>
  If you enable 3D Secure, the challenge window has a **5-minute timeout**. If the cardholder does not complete the challenge in time, the authentication is rejected.
</Warning>

<ParamField query="ThreeDS" type="boolean" default="false">
  Enable 3D Secure authentication after card entry. If using access token auth, provide two access tokens (see Authentication section above).
</ParamField>

<ParamField query="UnavailThreeDSAuth" type="string" default="Accept">
  What to do if the 3DS service is unavailable. `Accept`: skip 3DS and tokenize the card anyway. `Reject`: do not tokenize, redirect to the failure URL.
</ParamField>

<ParamField query="merchantName" type="string">
  Merchant name for 3DS authentication. Must be URL-encoded and match a configured [3DS merchant](/account-setup/3ds-merchant-setup). Leave blank to use PCI Booking's merchant (Visa and Mastercard only).
</ParamField>

<ParamField query="amount" type="integer" default="0">
  Transaction amount shown in the 3DS challenge screen. Must be paired with `currencyCode`. If omitted, authentication uses 0 EUR.
</ParamField>

<ParamField query="currencyCode" type="string" default="EUR">
  ISO 4217 currency code for the 3DS challenge amount. Must be paired with `amount`.
</ParamField>

<ParamField query="email" type="string">
  Cardholder email for 3DS authentication. Since August 2024, Visa requires either `email` or `phone` for all 3DS authentications.
</ParamField>

<ParamField query="phone" type="string">
  Cardholder phone number for 3DS authentication (digits only, e.g. `00353112223344`). Required by Visa if `email` is not provided.
</ParamField>

<Warning title="Merchant name for 3DS">
  Do not use the `merchantName` parameter unless you have configured a [3DS merchant account](/account-setup/3ds-merchant-setup). Providing an unconfigured merchant name will cause 3DS processing to fail.
</Warning>

### Advanced

<ParamField query="submitWithPostMessage" type="boolean" default="false">
  When `true`, removes PCI Booking's submit button so you can trigger form submission from your own page via postMessage. See [postMessage setup](/capture-cards/postmessage-notifications).
</ParamField>

<ParamField query="eliminateCardDuplication" type="boolean" default="false">
  When `true`, PCI Booking checks if this card was previously stored and returns the existing token instead of creating a new one.
</ParamField>

<ParamField query="useCustomValidation" type="boolean" default="false">
  When `true`, PCI Booking sends the non-sensitive form data to your server via [postMessage](/capture-cards/postmessage-notifications) for custom validation before tokenizing. Your server has 3 seconds to respond.
</ParamField>

## Request Example

Since this is a URL you build (not a server-side API call), the "request" is the fully constructed URL placed in an iframe or used as a redirect target. Here is an example using curl to test the URL directly:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/capturecard" \
      --data-urlencode "accessToken=at_test_abc123" \
      --data-urlencode "brand=myhotel" \
      --data-urlencode "language=en" \
      --data-urlencode "autoDetectCardType=true" \
      --data-urlencode "success=https://yoursite.com/booking/success" \
      --data-urlencode "failure=https://yoursite.com/booking/failure" \
      --data-urlencode "postMessageHost=yoursite.com" \
      --data-urlencode "creatorReference=booking-12345" \
      --data-urlencode "cvv=true"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      accessToken: "at_test_abc123",
      brand: "myhotel",
      language: "en",
      autoDetectCardType: "true",
      success: "https://yoursite.com/booking/success",
      failure: "https://yoursite.com/booking/failure",
      postMessageHost: "yoursite.com",
      creatorReference: "booking-12345",
      cvv: "true"
    });

    const url = `https://service.pcibooking.net/api/payments/capturecard?${params}`;

    // Use this URL as an iframe src or redirect target
    console.log(url);

    // To test the URL directly:
    const response = await fetch(url);
    console.log(response.status);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    params = {
        "accessToken": "at_test_abc123",
        "brand": "myhotel",
        "language": "en",
        "autoDetectCardType": "true",
        "success": "https://yoursite.com/booking/success",
        "failure": "https://yoursite.com/booking/failure",
        "postMessageHost": "yoursite.com",
        "creatorReference": "booking-12345",
        "cvv": "true"
    }

    # Build the URL for iframe src or redirect target
    prepared = requests.Request("GET",
        "https://service.pcibooking.net/api/payments/capturecard",
        params=params
    ).prepare()
    print(prepared.url)

    # To test the URL directly:
    response = requests.get(
        "https://service.pcibooking.net/api/payments/capturecard",
        params=params
    )
    print(response.status_code)
    ```
  </Tab>
</Tabs>

In production, you would set this URL as the `src` of an iframe element on your page:

```html theme={null}
<iframe src="https://service.pcibooking.net/api/payments/capturecard?accessToken=at_test_abc123&brand=myhotel&language=en&autoDetectCardType=true&success=https%3A%2F%2Fyoursite.com%2Fbooking%2Fsuccess&failure=https%3A%2F%2Fyoursite.com%2Fbooking%2Ffailure&postMessageHost=yoursite.com"></iframe>
```

## Success Response

On successful card capture, PCI Booking redirects the cardholder's browser to your `success` URL with the token details appended as query parameters:

```
https://yoursite.com/success?token=TOKEN_URI&last4Digits=1234&expirationDate=12/2028&cardType=Visa&nameOnCard=John+Doe
```

If you are using postMessage instead of redirect, the token details are sent via a [postMessage event](/capture-cards/postmessage-notifications).

## Errors

If the form cannot be rendered (invalid or missing parameters, authentication failure), PCI Booking redirects to your `failure` URL with error details. If no `failure` URL is configured, PCI Booking displays an error page.

| Error                                   | Cause                                                                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid or expired session/access token | The authentication token is missing, malformed, or has expired. Generate a new token and rebuild the URL.                                                              |
| Missing required parameters             | `brand`, `language`, or `postMessageHost` was not provided.                                                                                                            |
| Invalid language code                   | The `language` value is not a valid ISO 639-1 code. The form falls back to English.                                                                                    |
| 3DS challenge timeout                   | The cardholder did not complete the 3D Secure challenge within 5 minutes.                                                                                              |
| 3DS authentication rejected             | The cardholder failed 3D Secure authentication and `UnavailThreeDSAuth` is set to `Reject`.                                                                            |
| 3DS service unavailable                 | The 3DS provider is unreachable. If `UnavailThreeDSAuth` is `Accept`, the card is tokenized without 3DS. If `Reject`, the cardholder is redirected to the failure URL. |
| Invalid merchant name                   | The `merchantName` value does not match any configured 3DS merchant account.                                                                                           |

Errors delivered to the `failure` URL are appended as query parameters. See [success/failure URLs](/account-setup/success-and-failure-urls) for the format and available error fields.