> ## 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.

# Hosted Card Entry Form

> Embed a PCI-compliant hosted card entry form via iframe or standalone page. URL parameters and API sessions with 3D Secure.

The Hosted Card Entry Form is a PCI Booking-hosted page where cardholders enter their card details securely. You embed it as an iframe or redirect to it as a standalone page. Card data never touches your servers.

<iframe src="https://service.pcibooking.net/api/payments/capturecard?sessionToken=123&brand=SoBookIt&language=en&removeBaseCss=false&success=success&failure=failure&showOwnerId=false&submitWithPostMessage=False" width="100%" height="500" style={{ border: "1px solid #e5e7eb", borderRadius: "8px" }} />

<Note>
  This is a non-functional preview showing the default card entry form. The form's appearance can be fully customized with your own [CSS stylesheet](/account-setup/stylesheets).
</Note>

There are two ways to create a card entry form: **URL with query parameters** or **API session**. Both produce the same form. The difference is how you configure it and how you receive the result.

## Option 1: URL with Query Parameters

Build the form URL directly by appending configuration as query parameters. This is the simpler approach and requires no server-side API call to set up the form.

```
https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure
```

Embed it in your page:

```html theme={null}
<iframe
  src="https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure"
  width="400"
  height="350"
  frameborder="0">
</iframe>
```

When the cardholder submits the form, PCI Booking redirects to your `success` URL with the token appended. You can also specify a `failure` URL for declined or cancelled submissions.

See the [full parameter reference](/api-reference/tokenize-cards/request-card-entry-form) for all available query parameters.

## Option 2: API Session

Create a card entry form session via a server-side API call. Configuration is set in the request body rather than in the URL, so nothing is exposed to the client. Results are delivered via a server-to-server callback.

<Steps>
  <Step title="Set up a callback endpoint">
    Create an endpoint on your server to receive tokenization results from PCI Booking. This is a one-time setup. See the [callback reference](/api-reference/tokenize-cards/card-entry-form-callback) for the payload format.
  </Step>

  <Step title="Create a card entry form session">
    Send a POST request to [create the session](/api-reference/tokenize-cards/create-card-entry-form-session):

    ```bash theme={null}
    curl -X POST https://service.pcibooking.net/api/capturecard \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "TTL": 120,
        "CallBackURL": "https://your-server.com/card-captured",
        "Properties": {
          "CardCaptureType": "Tokenize",
          "Language": "en",
          "ShowCVV": true,
          "AutoDetectCardType": true
        }
      }'
    ```

    The response returns a `RequestID` and a `Location` header containing the form URL.
  </Step>

  <Step title="Embed the form">
    Take the URL from the `Location` header and set it as the iframe source in your page:

    ```html theme={null}
    <iframe src="{{Location-header-URL}}" width="400" height="300" frameborder="0"></iframe>
    ```
  </Step>

  <Step title="Receive the callback">
    When the cardholder submits the form, PCI Booking sends a POST to your `CallBackURL` with the token details. You can also [poll the session status](/api-reference/tokenize-cards/retrieve-card-entry-session) using the request ID:

    ```bash theme={null}
    curl -X GET https://service.pcibooking.net/api/capturecard/{requestId} \
      -H "Authorization: APIKEY your-api-key"
    ```
  </Step>

  <Step title="Clean up (optional)">
    [Delete the session](/api-reference/tokenize-cards/delete-card-entry-form) if the cardholder abandons the form or you no longer need it.
  </Step>
</Steps>

## Which Should I Use?

|                      | URL with Query Parameters                                                             | API Session                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup**            | No server-side call needed. Build the URL directly.                                   | Requires a server-side API call to create the session.                                                                                                   |
| **Configuration**    | Query parameters in the URL.                                                          | JSON body in the API request.                                                                                                                            |
| **Result delivery**  | Redirect to success/failure URLs.                                                     | Callback POST to your server, plus session polling.                                                                                                      |
| **Session tracking** | No built-in tracking.                                                                 | Request ID for status queries.                                                                                                                           |
| **TTL control**      | No configurable TTL.                                                                  | Set session expiry via `TTL` parameter.                                                                                                                  |
| **Security**         | Parameters are visible in the iframe URL and could be manipulated on the client side. | Parameters are set server-side. The generated short URL contains no configuration, so there is nothing for an attacker to manipulate via site injection. |

For quick integrations and prototyping, the URL approach is fastest. For production use, the API session provides better security, callback support, and session management.

## Key Features

Both approaches support:

* **CSS customization**. Style the form to match your brand by storing a stylesheet. See the [Stylesheets guide](/account-setup/stylesheets) for details.
* **3D Secure**. 3DS verification is supported during card capture. When enabled, a 3DS challenge is presented to the cardholder automatically if required by the issuing bank. The cardholder has 5 minutes to complete the challenge before it expires. See the [3DS Merchant Setup](/account-setup/3ds-merchant-setup) page to configure your merchant details for 3DS.
* **[Multi-language](/account-setup/custom-translations)**. Set the form language via the `Language` parameter (ISO 639-1 two-letter code).

<Warning>
  When embedding in an iframe, ensure your Content Security Policy allows framing from `service.pcibooking.net`.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Card Validation Errors" icon="code" href="/reference/card-validation-errors">
    Error messages the cardholder may see when entering invalid card data.
  </Card>

  <Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
    Customize the look and feel of your card entry form.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>