> ## 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). |
| none | 401 | Missing or invalid API key in the `Authorization` header. The response body is empty. |
| -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 72 (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

### Authentication

**API key only.** This endpoint does not accept access tokens or session tokens.

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. The `x-pcibooking-api-key` header is also accepted. 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 72 hours.
</ParamField>

### Card Form Settings

<ParamField body="CardTypes" type="string[]">
  Limits the list of card types accepted on the form. Use the exact `Code` values from [Supported Card Types](/reference/card-types), e.g. `["Visa", "MasterCard", "AMEX"]`. If omitted, all types are displayed. **Values that don't match a supported code are ignored - and if none of the provided values are valid, the form falls back to displaying all card types**, so double-check spelling if you rely on this restriction. The list can also be retrieved via the [Get Supported Credit Cards](/api-reference/general/get-supported-cards) endpoint.
</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. A duplicate is a card with the same card number and expiration date as an existing token in your account; differences in cardholder name or CVV do not matter.
</ParamField>

<ParamField body="TokenLocation" type="string">
  The region where the card data is stored when the cardholder submits the form. One of: `US`, `IN`, `AU`, `JP`, `CA`, `IE`, `GB`, `BR`. If omitted, your account's default region is used, or Ireland if your account has no default. See [Card Storage Regions](/concepts/tokenization-explained#card-storage-regions).
</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. Supported image formats: png, gif, bmp, jpeg, jpg.
</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">
  The page title to be displayed. Max 40 characters.
</ParamField>

<ParamField body="CustomHeaderText" type="string">
  Text displayed in the header of the card capture page. Max 1000 characters. Overrides the portal template. Supports dynamic variables in `$~name~$` syntax (e.g. `$~recipient_name~$`, `$~amount~$`) - see [Dynamic Variables](/account-setup/card-by-link-templates#dynamic-variables). Variables you do not use here (or in the footer) are embedded in the page automatically by PCI Booking when their values are provided in other request parameters.
</ParamField>

<ParamField body="CustomFooterText" type="string">
  Text displayed in the footer of the card capture page. Max 1000 characters. Overrides the portal template. Supports dynamic variables in `$~name~$` syntax (e.g. `$~cs_phone~$`, `$~cs_email~$`, `$~cs_link~$`) - see [Dynamic Variables](/account-setup/card-by-link-templates#dynamic-variables). Variables you do not use here (or in the header) are embedded in the page automatically by PCI Booking when their values are provided in other request parameters.
</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). An unregistered `merchantName` does not return an error - PCI Booking silently falls back to its default merchant and the cardholder sees PCI Booking's name.
  * **`UnavailThreeDSAuth` defaults to `Accept`.** If 3DS can't complete for any reason, the card is still tokenized - silently, without 3DS data. If you later charge that token through a PSP that requires 3DS, the charge will be rejected. Set this to `Reject` if every token in your flow must have 3DS data.
</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. If omitted, authentication uses 0 EUR.
</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. If omitted, authentication uses 0 EUR.
</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"
      ]
  }
  ```

  ```text 401 theme={null}
  Empty response body.
  Authentication failed: the API key, session token or access token is missing or was not accepted.
  See "Authentication and Permission Failures" on the Error Handling page.
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.