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

# Send Card Capture Link

> Send a Card By Link request via email or SMS with a link to a secure card capture form.

<Card title="Card By Link Guide" icon="book" href="/capture-cards/card-by-link">
  Send secure card capture links via email or SMS
</Card>

Use this endpoint to send a secure card capture link to a cardholder via email or SMS. The recipient clicks the link to open a PCI-compliant form where they enter their card details, which are tokenized and stored by PCI Booking. This is ideal for scenarios like phone bookings or back-office operations where you need to collect card data without handling it directly.

## Error Responses

| Code  | HTTP Status | Condition                                                                                |
| ----- | ----------- | ---------------------------------------------------------------------------------------- |
| -179  | 400         | Validation error: missing required fields, invalid field format, or malformed JSON body. |
| -112  | 400         | Destination phone number exceeds maximum length (SMS delivery).                          |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                                |
| -1003 | 401         | `SenderID` does not match the identity associated with the API key.                      |
| -150  | 500         | Internal system error while creating the card request.                                   |

## Parameter Constraints

| Parameter                 | Constraint                                                                                                                                         |                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `RequestTTL`              | Integer, range 1 to 24 (hours).                                                                                                                    |                       |
| `Destination`             | Max 255 characters. For SMS, phone number is sanitized (non-digit characters and leading `+`/`0` removed) then validated against a maximum length. |                       |
| `RecipientName`           | Required. Max 70 characters.                                                                                                                       |                       |
| `SenderReference`         | Max 50 characters.                                                                                                                                 |                       |
| `Description`             | Max 50 characters.                                                                                                                                 |                       |
| `CompanyName`             | Max 20 characters. Required when `DestinationType` is `sms`.                                                                                       |                       |
| `CustomHeaderText`        | Max 1000 characters.                                                                                                                               |                       |
| `CustomFooterText`        | Max 1000 characters.                                                                                                                               |                       |
| `CustomerSupportPhone`    | Max 20 characters.                                                                                                                                 |                       |
| `CustomerSupportEmail`    | Max 50 characters.                                                                                                                                 |                       |
| `CustomerSupportLink`     | Max 255 characters. Must be a valid URL.                                                                                                           |                       |
| `CustomerSupportLinkText` | Max 100 characters.                                                                                                                                |                       |
| `LogoTitle`               | Max 100 characters.                                                                                                                                |                       |
| `SiteTitle`               | Max 40 characters.                                                                                                                                 |                       |
| `ClientLogoUrl`           | Must be a valid fully-qualified HTTP, HTTPS, or FTP URL (if provided).                                                                             |                       |
| `MinExpiration`           | Format `mmyyyy`, regex \`^(1\[0-2]                                                                                                                 | 0\[1-9])(20\d\d)\$\`. |

## Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Configuration

<ParamField body="SenderID" type="string" required>
  The user ID of the booker.
</ParamField>

<ParamField body="Language" type="string" default="EN">
  The form's language in ISO 639-1 (2-letter) format. See [supported languages](/account-setup/custom-translations#supported-languages). If an unsupported language is received, English will be displayed.
</ParamField>

<ParamField body="Css" type="string">
  The CSS resource name. Follow the guide on [managing stylesheets](/account-setup/stylesheets). If not provided, PCI Booking will use the [default CSS](/account-setup/stylesheets).
</ParamField>

<ParamField body="CallBackURL" type="string">
  A URL where the status of the request will be pushed to by PCI Booking.
</ParamField>

<ParamField body="RequestTTL" type="integer" required>
  The number of hours the request will be valid for. Minimum 1 hour, maximum 24 hours.
</ParamField>

### Card Form Settings

<ParamField body="CardTypes" type="string[]">
  Limits the list of card types. If omitted or no valid card types are found, all types will be displayed. Separate card types by comma. Read more on [supported card types](/api-reference/general/get-supported-cards).
</ParamField>

<ParamField body="ShowOwnerID" type="boolean" default="false">
  Whether to display the Owner ID field in the form (required in some countries). `true`: include the field. `false`: exclude the field.
</ParamField>

<ParamField body="DefaultCardType" type="string">
  Which card type will be set as default in the card drop down menu. Read more on [supported card types](/api-reference/general/get-supported-cards).
</ParamField>

<ParamField body="AutoDetectCardType" type="boolean" default="false">
  Whether to use card detection according to card number. `true`: use card detection. `false`: show a drop down menu for card type selection.
</ParamField>

<ParamField body="MinExpiration" type="string">
  Minimum expiration month/year. Format: **mmyyyy**. The expiration validation will be checked against this date. Must be a valid date in the specified format. Use case: when the card expiration should be later than a check-in date.
</ParamField>

<ParamField body="CVV" type="boolean" default="false">
  Whether to add the CVV field. `true`: include the CVV and save it in the database. `false`: exclude the field.
</ParamField>

<ParamField body="nameOnCardValidation" type="string">
  Additional input validation on the `Name On Card` field. Possible values: `NO_DIGITS` - the field cannot contain digits.
</ParamField>

<ParamField body="eliminateCardDuplication" type="boolean">
  Whether PCI Booking should look up this card in previously stored cards and return the existing token (if found) or always return a new token. `True`: look up in existing cards. `False`: always create new tokens. If not specified, the default behavior is taken from the account settings.
</ParamField>

### Delivery

<ParamField body="DestinationType" type="string" required>
  How to send the link to the card capture form. Values: `email` or `sms`.
</ParamField>

<ParamField body="Destination" type="string" required>
  The destination of the message - email address or phone number. For phone numbers, format as international dial number: `Country code + area code + phone number`.
</ParamField>

<ParamField body="RecipientName" type="string" required>
  The recipient's name. Max 70 characters.
</ParamField>

<ParamField body="Description" type="string">
  Free text description of this request. Max 50 characters.
</ParamField>

<ParamField body="SenderReference" type="string">
  A reference value that can be used to query for this card token later.
</ParamField>

### Branding

<Info>
  `CustomerSupportLink`, `CustomerSupportLinkText`, `CustomerSupportEmail`, and `CustomerSupportPhone` can also be set in your [account settings](https://users.pcibooking.net/booker/Login). Values provided in the request override the account defaults.
</Info>

<Note>
  URLs in the request body (e.g. `ClientLogoURL`, `Success`, `Failure`) should **not** be URL-encoded, since they are sent in JSON, not as query parameters.
</Note>

<ParamField body="CompanyName" type="string">
  The name of the company sending the message. Required when sending via SMS.
</ParamField>

<ParamField body="ClientLogoURL" type="string">
  URL to the logo displayed in the Card By Link email and landing page. Submit with a null value to hide the logo. If not supplied, the logo from the Booker information in the portal is used. Images must be publicly accessible, HTTPS URL.
</ParamField>

<ParamField body="LogoTitle" type="string">
  The title of the logo. If not provided, the booker name (as set in the portal) is used. Submit with a null value for no title. Max 100 characters.
</ParamField>

<ParamField body="FaviconURL" type="string">
  URL to the favicon displayed in the Card By Link landing page. If not supplied, the browser default is used. Images must be publicly accessible, HTTPS URL in ico or png format, size 16x16 or 32x32.
</ParamField>

<ParamField body="SiteTitle" type="string" default="Card Display">
  The page title to be displayed. Max 40 characters.
</ParamField>

<ParamField body="CustomHeaderText" type="string">
  Text displayed in the header of the message to the recipient. Max 1000 characters. If `RecipientName`, `Amount` and `Currency` placeholders are not listed here or in the [portal customizations](/account-setup/card-by-link-templates), but are provided in other request parameters, they will not be displayed.
</ParamField>

<ParamField body="CustomFooterText" type="string">
  Text displayed in the footer of the message to the recipient. Max 1000 characters. If `CustomerSupportEmail` and `CustomerSupportPhone` placeholders are not listed here or in the [portal customizations](/account-setup/card-by-link-templates), but are provided in other request parameters, they will not be displayed.
</ParamField>

<ParamField body="CustomerSupportPhone" type="string">
  Phone number displayed in the email message and landing page. Max 20 characters.
</ParamField>

<ParamField body="CustomerSupportEmail" type="string">
  Email address displayed in the email message and landing page. Max 50 characters.
</ParamField>

<ParamField body="CustomerSupportLink" type="string">
  URL for customer support displayed in the email message and landing page. Max 255 characters. Required if `CustomerSupportLinkText` is provided.
</ParamField>

<ParamField body="CustomerSupportLinkText" type="string">
  Display name for the customer support URL in the email message and landing page. Max 100 characters. Required if `CustomerSupportLink` is provided.
</ParamField>

### Redirect URLs

<ParamField body="Success" type="string">
  URL where a successful response will be redirected to. Read more on [setting up success / failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField body="Failure" type="string">
  URL where a failed response will be redirected to. Read more on [setting up success / failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

### 3D Secure

<Warning>
  * 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` or `phone` for 3DS authentication.
</Warning>

<ParamField body="ThreeDS" type="boolean" default="False">
  Whether to perform 3D Secure authentication following card entry. If enabled with access token authorization, provide two access tokens.
</ParamField>

<ParamField body="UnavailThreeDSAuth" type="string" default="Accept">
  What to do if there is a technical problem with the 3DS process. **Accept** - ignore 3DS and proceed with tokenizing the card. **Reject** - do not continue or tokenize; the card owner will be directed to the failure page URL.
</ParamField>

<ParamField body="merchantName" type="string">
  The merchant to use for 3D Secure authentication. Must match a merchant name registered in your [3DS merchant setup](/account-setup/3ds-merchant-setup).
</ParamField>

<ParamField body="Amount" type="double">
  The transaction amount, also displayed in the 3DS challenge screen. Required if `Currency` is provided.
</ParamField>

<ParamField body="Currency" type="string">
  The transaction currency in ISO 4217 (3-letter) format, also displayed in the 3DS challenge screen. Required if `Amount` is provided.
</ParamField>

<ParamField body="email" type="string">
  Cardholder's email address for 3D Secure authentication. Must be in a valid email format, e.g. [joe@bloggs.com](mailto:joe@bloggs.com).
</ParamField>

<ParamField body="phone" type="string">
  Cardholder's telephone number for 3D Secure authentication. May only contain digits \[0-9], e.g.: 00353112223344.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/cardrequest', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      SenderID: 'myhotel',
      DestinationType: 'email',
      Destination: 'guest@example.com',
      RecipientName: 'Jane Smith',
      RequestTTL: 12,
      Language: 'en',
      AutoDetectCardType: true,
      CVV: true,
      SenderReference: 'booking-12345',
      Description: 'Card for reservation #12345',
      CompanyName: 'Sunrise Hotel',
      Success: 'https://yoursite.com/success',
      Failure: 'https://yoursite.com/failure',
      CallBackURL: 'https://yoursite.com/webhook/card-status'
    })
  });

  const requestUri = response.headers.get('Location');
  console.log('Request URI:', requestUri);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/cardrequest',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'SenderID': 'myhotel',
          'DestinationType': 'email',
          'Destination': 'guest@example.com',
          'RecipientName': 'Jane Smith',
          'RequestTTL': 12,
          'Language': 'en',
          'AutoDetectCardType': True,
          'CVV': True,
          'SenderReference': 'booking-12345',
          'Description': 'Card for reservation #12345',
          'CompanyName': 'Sunrise Hotel',
          'Success': 'https://yoursite.com/success',
          'Failure': 'https://yoursite.com/failure',
          'CallBackURL': 'https://yoursite.com/webhook/card-status'
      }
  )

  request_uri = response.headers.get('Location')
  print('Request URI:', request_uri)
  ```
</RequestExample>

## Response

**201** - Empty body. A `Location` header is returned with the URI for this card request. Use this URI to [retrieve the request status](/api-reference/tokenize-cards/cotp-retrieve-request) or [delete the request](/api-reference/tokenize-cards/cotp-delete-request).

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token once the card is captured.
</Info>

<ResponseExample>
  ```text 201 theme={null}
  Empty response body. The Location header contains the request URI:
  Location: https://service.pcibooking.net/api/payments/paycard/CardForm/SULqe7pa22gghYDnX6O3J7QDMhyyUzNb
  ```

  ```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
  }
  ```
</ResponseExample>