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

# Issue Virtual Card

> Issue a single-use virtual card through a supported provider and automatically tokenize it.

Issues a virtual card through a supported provider (e.g. WEX, Rapyd) and automatically stores the issued card as a PCI Booking token. The card number and CVV in the response are masked for security.

The token URI is returned in the `Location` response header.

## Error Responses

| Code    | HTTP Status | Condition                                                                               |
| ------- | ----------- | --------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                          |
| `-125`  | `400`       | Invalid provider name, missing required fields, or credential validation failed.        |
| `-125`  | `400`       | The `credentialsId` was provided but credentials were not found or could not be parsed. |
| `-150`  | `500`       | Virtual card was issued but could not be tokenized internally.                          |

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

### Query String

<ParamField query="credentialsId" type="string">
  The ID of [stored credentials](/api-reference/process-cards/store-credentials) for a virtual card provider. When provided, `ProviderName` and `Credentials` in the request body are ignored.
</ParamField>

<ParamField query="tokenLocation" type="string">
  Token storage region. One of: `US`, `IN`, `AU`, `JP`, `CA`, `IE`, `GB`, `BR`. If omitted, uses the account default.
</ParamField>

### Request Body

<ParamField body="ProviderName" type="string" required>
  The virtual card provider name (e.g. `WEX`, `Rapyd`). See [List Virtual Card Providers](/api-reference/additional/list-virtual-card-providers) for available providers. Not required when `credentialsId` is provided.
</ParamField>

<ParamField body="Credentials" type="object">
  Provider-specific credential key-value pairs. Not required when `credentialsId` is provided. See the provider's credential structure for required fields.
</ParamField>

<ParamField body="Request" type="object" required>
  The virtual card issuance request.

  <Expandable title="Properties">
    <ParamField body="Request.MaxValue" type="object">
      Maximum amount that can be charged on the virtual card.

      <Expandable title="Properties">
        <ParamField body="Request.MaxValue.Amount" type="number" required>
          The maximum charge amount.
        </ParamField>

        <ParamField body="Request.MaxValue.CurrencyCode" type="string" required>
          ISO 4217 currency code (e.g. `USD`, `EUR`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="Request.MinAuthDate" type="string">
      Earliest date the card can be authorized. ISO 8601 format.
    </ParamField>

    <ParamField body="Request.MaxAuthDate" type="string">
      Latest date the card can be authorized. ISO 8601 format.
    </ParamField>

    <ParamField body="Request.UniqueReference" type="string">
      Your own reference for this virtual card. If omitted, the provider assigns one.
    </ParamField>

    <ParamField body="Request.CustomData" type="object">
      Arbitrary provider-specific data.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/VirtualCard?tokenLocation=IE', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ProviderName: 'WEX',
      Credentials: {
        MerchantID: 'your-merchant-id',
        SharedSecret: 'your-shared-secret',
        Account: 'your-account',
        RebatePWD: 'your-rebate-password'
      },
      Request: {
        MaxValue: {
          Amount: 500.00,
          CurrencyCode: 'USD'
        },
        MinAuthDate: '2026-07-10T00:00:00Z',
        MaxAuthDate: '2026-08-10T00:00:00Z',
        UniqueReference: 'booking-98765'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.post(
      'https://service.pcibooking.net/api/VirtualCard',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      params={
          'tokenLocation': 'IE'
      },
      json={
          'ProviderName': 'WEX',
          'Credentials': {
              'MerchantID': 'your-merchant-id',
              'SharedSecret': 'your-shared-secret',
              'Account': 'your-account',
              'RebatePWD': 'your-rebate-password'
          },
          'Request': {
              'MaxValue': {
                  'Amount': 500.00,
                  'CurrencyCode': 'USD'
              },
              'MinAuthDate': '2026-07-10T00:00:00Z',
              'MaxAuthDate': '2026-08-10T00:00:00Z',
              'UniqueReference': 'booking-98765'
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**201** - Virtual card issued and tokenized. The `Location` header contains the PCI Booking token URI.

### Response Fields

<ParamField body="CardToken" type="string">
  The PCI Booking token for the issued virtual card.
</ParamField>

<ParamField body="ProviderResponse" type="object">
  The virtual card provider's response.

  <Expandable title="Properties">
    <ParamField body="ProviderResponse.Result" type="string">
      The outcome. One of: `Success`, `Accepted`, `Rejected`, `TemporaryFailure`, `FatalFailure`.
    </ParamField>

    <ParamField body="ProviderResponse.Message" type="string">
      Detailed explanation of the result.
    </ParamField>

    <ParamField body="ProviderResponse.MaxValue" type="object">
      The maximum value set on the issued card.
    </ParamField>

    <ParamField body="ProviderResponse.VirtualCard" type="object">
      The issued card details (number and CVV are masked).
    </ParamField>

    <ParamField body="ProviderResponse.UniqueReference" type="string">
      The reference for this virtual card.
    </ParamField>

    <ParamField body="ProviderResponse.CardId" type="string">
      The unique ID assigned by the virtual card provider.
    </ParamField>

    <ParamField body="ProviderResponse.ProviderName" type="string">
      The name of the virtual card provider.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
      "CardToken": "tok_abc123def456",
      "ProviderResponse": {
          "Result": "Success",
          "Message": "Card issued successfully",
          "MaxValue": {
              "Amount": 500.00,
              "CurrencyCode": "USD"
          },
          "VirtualCard": {
              "Number": "411111******1234",
              "ExpirationMonth": 12,
              "ExpirationYear": 2027,
              "SecurityCode": "***"
          },
          "UniqueReference": "booking-98765",
          "CardId": "vcc_provider_id_123",
          "ProviderName": "WEX"
      }
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Virtual card provider with name [InvalidName] not found",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>