> ## 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.
# Create Card Entry Form Session
> Create a new session for the card entry form. Parameters are sent in the request body instead of as URL query strings. Returns a Location header with the card form URL.
API session approach for embedded card capture
The successful response of this method will include the following:
* `RequestID` for this Card Entry Form session. You will need to use this request ID in future requests relating to this Card Entry Form session.
* `Location` header for the URL of the card form. You will need to set this URL as the value of the `SRC` attribute of your iframe in your webpage.
All URLs should be HTTPS.
## Error Responses
| Code | HTTP Status | Condition |
| ----- | ----------- | ---------------------------------------------------------------------------------------- |
| -179 | 400 | Validation error: missing required fields, invalid field format, or malformed JSON body. |
| -125 | 400 | Invalid credentials ID provided via the `credentialsId` query parameter. |
| -1003 | 401 | Missing or invalid API key in the `Authorization` header. |
| -160 | 404 | Resource not matching request (e.g. wrong capture type). |
## Parameter Constraints
| Parameter | Constraint | |
| ---------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `TTL` | Integer, range 30 to 600 (seconds). Default: 120. | |
| `CreatorReference` | Max 50 characters. | |
| `CallBackURL` | Must be a valid URL. | |
| `Properties.MinExpiration` | Format `mmyyyy`, regex \`^(1\[0-2] | 0\[1-9])(20\d\d)\$\`. Cards with expiration before this date are rejected. |
| `Properties.Language` | 2-letter ISO 639-1 language code. `zh` is automatically mapped to `cn` internally. | |
| `Properties.CardCaptureType` | One of `Tokenize`, `Charge`, or `ChargeToken`. Default: `Tokenize`. | |
## Parameters
### Headers
Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
### Request Body
URL where PCI Booking will push the status of the request.
Number of seconds the request will be valid for. Minimum 30, maximum 600.
A reference value that can be used to query for this card token.
The set of properties defining the card entry form. See the 201 response example below for the full list of available properties.
* The 3DS challenge window has a **5 minute timeout**. If the cardholder does not respond in time, authentication is rejected.
* Do not use `merchantName` unless you have configured your [3DS merchant information](/account-setup/3ds-merchant-setup). To use PCI Booking's merchant, set `ThreeDs` to `True` and leave `merchantName` blank (Visa and Mastercard only).
* **Visa requirement (Aug 2024):** You **must** provide at least the cardholder's email address or phone number for 3DS authentication.
```javascript Node.js theme={null}
const response = await fetch('https://service.pcibooking.net/api/capturecard', {
method: 'POST',
headers: {
'Authorization': 'APIKEY your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
TTL: 300,
creatorReference: 'booking-12345',
CallBackURL: 'https://yoursite.com/webhook/card-captured',
Properties: {
Language: 'en',
AutoDetectCardType: true,
ShowCVV: true,
Success: 'https://yoursite.com/success?cardToken={cardToken}',
Failure: 'https://yoursite.com/failure',
postMessageHost: 'yoursite.com',
CardTypes: ['Visa', 'MasterCard', 'AMEX']
}
})
});
const formUrl = response.headers.get('Location');
const data = await response.json();
console.log('Request ID:', data.RequestID);
console.log('Form URL:', formUrl);
```
```python Python theme={null}
import requests
response = requests.post(
'https://service.pcibooking.net/api/capturecard',
headers={
'Authorization': 'APIKEY your-api-key',
'Content-Type': 'application/json'
},
json={
'TTL': 300,
'creatorReference': 'booking-12345',
'CallBackURL': 'https://yoursite.com/webhook/card-captured',
'Properties': {
'Language': 'en',
'AutoDetectCardType': True,
'ShowCVV': True,
'Success': 'https://yoursite.com/success?cardToken={cardToken}',
'Failure': 'https://yoursite.com/failure',
'postMessageHost': 'yoursite.com',
'CardTypes': ['Visa', 'MasterCard', 'AMEX']
}
}
)
form_url = response.headers.get('Location')
data = response.json()
print('Request ID:', data['RequestID'])
print('Form URL:', form_url)
```
## Response
**201** - Session created. A `Location` header is returned with the card form URL. Set this URL as the `src` of your iframe.
Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token once the card is captured.
```json 201 theme={null}
{
"RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
"SenderId": "RoeeSandbox",
"CreatorReference": "Card capture request",
"TTL": 600,
"CallBackURL": "http://httpbin.org/post",
"CreateTime": "2019-11-20T11:36:46.8062564Z",
"Properties": {
"Language": "en",
"Css": "test",
"removeBaseCss": false,
"CardTypes": [
"Visa",
"electron",
"mastercard",
"maestro",
"UnionPay"
],
"DefaultCardType": "Visa",
"AutoDetectCardType": true,
"ShowOwnerID": false,
"MinExpiration": "082020",
"ShowCVV": true,
"Success": "https://www.google.com?cardToken={cardToken}",
"Failure": "https://www.pcibooking.net",
"autoFocus": true,
"submitWithPostMessage": false,
"postMessageHost": "https://www.example.com",
"ThreeDS": true,
"UnavailThreeDSAuth": "Accept",
"ExpirationMonths": "Names"
}
}
```
```json 400 theme={null}
{
"code": -179,
"message": "Bad input parameter",
"moreInfo": "Bad input data",
"errorList": [
"Bad json format"
]
}
```
```json 401 theme={null}
{
"code": -1003,
"message": "Not authorized to access this resource",
"moreInfo": "Bad or missing authorization data, expected APIKEY",
"errorList": null
}
```