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

# Retrieve Card By Link Request

> Retrieve the status and details of a Card By Link request.

<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 check the current status and configuration of a Card By Link request. The response includes the request parameters, delivery status, and the card token URI if the cardholder has already submitted their card details.

## Error Responses

| Code | HTTP Status | Condition |
| - | - | - |
| none | 401 | Missing or invalid API key in the `Authorization` header. The response body is empty. |
| -160 | 404 | Card request with the specified `requestID` was not found. |

### Error detail

Each condition below gives the exact `moreInfo` text, why it happens and how to resolve it. The full set is on the [Error Handling](/reference/error-handling) page.

<AccordionGroup>
  <Accordion title="-160 Uri not found - card request not found">
    **HTTP status:** `404`

    **`message`:** `Uri not found`

    **`moreInfo`:**

    ```text theme={null}
    Card request not found
    Card request with the specified requestID was not found
    ```

    **Reason.** No card request exists for the `requestID` given. Card requests are not permanent: once completed or expired, a request is no longer retrievable.

    **How to resolve.**

    1. Check the `requestID` is the one returned when the request was created.
    2. Check the request has not already been completed by the cardholder, or passed its expiry.
    3. Confirm the credential belongs to the account that created the request.
  </Accordion>

  <Accordion title="-1003 You are not authorized to access this resource - SenderID does not match the credential">
    **HTTP status:** `401`

    **`message`:** `You are not authorized to access this resource. Please contact customer support.`

    **`moreInfo`:**

    ```text theme={null}
    Wrong sender id
    ```

    **Reason.** The `SenderID` in the body does not match the account the API key authenticates as. The API will not let one account send a card request on behalf of another.

    **How to resolve.**

    1. Set `SenderID` to the user ID of the account whose API key you are using.
    2. If you operate several accounts, check you have not paired one account's key with another account's `SenderID`.
  </Accordion>
</AccordionGroup>

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

### Path Parameters

<ParamField path="requestID" type="string" required>
  The request ID returned from sending a [card capture link](/api-reference/tokenize-cards/cotp-send-card-form) or [CVV capture link](/api-reference/tokenize-cards/cotp-send-cvv-form).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const requestID = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb';

  const response = await fetch(
    `https://service.pcibooking.net/api/cardrequest/${requestID}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log('Status:', data.Status);
  console.log('Card URI:', data.CardUri);
  ```

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

  request_id = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb'

  response = requests.get(
      f'https://service.pcibooking.net/api/cardrequest/{request_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  data = response.json()
  print('Status:', data['Status'])
  print('Card URI:', data['CardUri'])
  ```
</RequestExample>

## Response

**200**

Returns the full request configuration and its current status.

<ParamField body="Status" type="string">
  The current status of the request. Possible values:

  | Channel | Value | Description |
  | - | - | - |
  | Email / SMS | `MessageQueued` | Message was added to the PCI Booking queue. |
  | SMS only | `MessageSent` | The message was sent to the recipient. |
  | SMS only | `MessageFailed` | Message delivery to the recipient failed. |
  | SMS only | `MessageDelivered` | Message was successfully delivered to the recipient. |
  | Email / SMS | `FormViewed` | Recipient opened the link and the capture form loaded. |
  | Email / SMS | `CardStored` | Card was captured and tokenized. The `CardUri` field contains the token URL. |
  | Email / SMS | `StoreFailed` | Recipient submitted the form and the capture failed: the card was rejected, 3DS failed with `UnavailThreeDSAuth` set to `Reject`, or the form was submitted after its one-time token had already been used. Set only from `FormViewed`. |
  | Email / SMS | `Aborted` | Request cancelled by the sender. |
  | Email / SMS | `Expired` | The time-to-live passed without a stored card. Includes recipients who never opened the link, and failures that were not reported back to PCI Booking before expiry. |
  | Email / SMS | `Archived` | Request archived after expiry or completion. |
</ParamField>

<ParamField body="RequestID" type="string">
  The unique identifier for this request.
</ParamField>

<ParamField body="RequestType" type="string">
  The type of request: `Card` for card capture, `CVV` for CVV-only capture.
</ParamField>

<ParamField body="CardUri" type="string">
  The PCI Booking token URL for the stored card. Only populated when `Status` is `CardStored`.
</ParamField>

<ParamField body="StatusTime" type="string">
  Timestamp of the last status change (ISO 8601 format).
</ParamField>

<ParamField body="OriginCardUri" type="string">
  The original token URL. Only present for CVV-only requests (`RequestType: CVV`).
</ParamField>

<Warning title="CVV capture requests">
  For CVV-only requests, PCI Booking creates a **new token** that is a full copy of the original card details plus the captured CVV (returned in `CardUri`). The original token (`OriginCardUri`) is not modified and does not contain the CVV. You should delete the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

<Info>
  Once `Status` is `CardStored`, remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```json Card - Queued 200 theme={null}
  {
    "RequestID": "SULqe7pa22gghYDnX6O3J7QDMhyyUzNb",
    "RequestType": "Card",
    "Status": "MessageQueued",
    "StatusTime": "2018-03-21T13:28:38",
    "CardUri": null,
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": "nadya@recipientDomain.com",
    "DestinationType": "Email",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "CardTypes": "Visa,MasterCard,AMEX",
    "DefaultCardType": "AMEX",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082018",
    "CVV": true,
    "ShortUrl": "SULqe7",
    "Css": "TEst CSS"
  }
  ```

  ```json Card - Stored 200 theme={null}
  {
    "RequestID": "UPzpUmAj2NIRbciQCim3tHS0hZk7b2HE",
    "RequestType": "Card",
    "Status": "CardStored",
    "StatusTime": "2018-03-21T12:53:28",
    "CardUri": "https://service.pcibooking.net/api/payments/paycard/d919fe8ee51c4adbbbc22cef85e736a6",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": "nadya@recipientDomain.com",
    "DestinationType": "Email",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "CardTypes": "Visa,MasterCard,AMEX",
    "DefaultCardType": "AMEX",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082018",
    "CVV": true,
    "ShortUrl": "7inQGn",
    "Css": "TEst CSS"
  }
  ```

  ```json CVV - Queued 200 theme={null}
  {
    "RequestID": "pMdsvukESyaUIFuSBmvIufYtKjI0vOrj",
    "RequestType": "CVV",
    "Status": "MessageSent",
    "StatusTime": "2018-03-21T12:56:00",
    "CardUri": null,
    "OriginCardUri": "https://service.pcibooking.net/api/payments/paycard/7175f98744434ca89615b1cc86c69a45",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": null,
    "DestinationType": "SMS",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "ShortUrl": "pMdsvu",
    "Css": "TEst CSS"
  }
  ```

  ```json CVV - Stored 200 theme={null}
  {
    "RequestID": "pMdsvukESyaUIFuSBmvIufYtKjI0vOrj",
    "RequestType": "CVV",
    "Status": "CardStored",
    "StatusTime": "2018-03-21T13:26:29",
    "CardUri": "https://service.pcibooking.net/api/payments/paycard/d4ffa09028a044d2ac0d8bada49b6502",
    "OriginCardUri": "https://service.pcibooking.net/api/payments/paycard/7175f98744434ca89615b1cc86c69a45",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": null,
    "DestinationType": "SMS",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "ShortUrl": "pMdsvu",
    "Css": "TEst CSS"
  }
  ```

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

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Card request not found",
      "errorList": null
  }
  ```
</ResponseExample>


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