> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnosispay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Virtual Card

> Create and manage virtual cards for users

Virtual cards are activated immediately after creation and can be used for online purchases right away.

## Card Activation

To create a card for a user, call [`POST /cards/virtual`](/api-reference/cards/create-virtual-card) with a `cardName`. Once successful, you will get a `cardId`.

The card's `status` will first be `provisioning` until our card provider has fully created the card. This is an asynchronous task. We recommend showing this `status` to your users, and polling the `/cards` endpoint regularly until it becomes `active`. The provisioning process should not last more than 10 seconds.

The request accepts an optional `phone` field (E.164 format). The behavior depends on whether the user already has a phone number, and on whether you require phone OTP for your users. See [Phone Number](/guides/phone).

| Scenario | Result |
| - | - |
| User already has a phone number | Card created directly; `phone` is ignored |
| You require phone OTP for your users, and the user has no phone yet | `409 PHONE_VERIFICATION_REQUIRED`. Verify the number with [`POST /phone/verification`](/api-reference/phone/request-phone-verification) then [`POST /phone`](/api-reference/phone/set-phone-number) first |
| You do not require phone OTP, no phone on the user, and no `phone` in the request | `422 PHONE_REQUIRED` |
| You do not require phone OTP, no phone on the user, valid `phone` in the request | Phone is set, then the card is created |

<Tabs>
  <Tab title="Sandbox">
    ```bash theme={null}
    curl --request POST \
      --url https://core.sandbox.gnosispay.in/user-api/cards/virtual \
      --header 'Content-Type: application/json' \
      --data '{
        "cardName": "<string>",
        "phone": "<string>"
      }'
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    curl --request POST \
      --url https://core.prod.gnosispay.com/user-api/cards/virtual \
      --header 'Content-Type: application/json' \
      --data '{
        "cardName": "<string>",
        "phone": "<string>"
      }'
    ```
  </Tab>
</Tabs>

## Card transactions and enrichment

A user's card transactions are returned as `card_transaction` entries via [`GET /user/statement`](/api-reference/user-movements/get-account-statement). Each entry includes both the raw transaction data from the card network and an `enrichment` object with matched merchant, category, and location data which lets developers build a clean, recognizable transaction feed instead of showing raw network descriptors.

<Info>
  See [Transaction Enrichment](/concepts/card/transaction-enrichment) for why this matters and how matching works conceptually.
</Info>

```json theme={null}
{
  "data": [
    {
      "type": "card_transaction",
      "id": "<string>",
      "status": "pending",
      "amount": "<string>",
      "currency": "<string>",
      "decimals": 123,
      "originalAmount": "<string>",
      "originalCurrency": "<string>",
      "originalDecimals": 123,
      "isCredit": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "description": "<string>",
      "authorizationId": 123,
      "mcc": "<string>",
      "authorizationCode": "<string>",
      "merchant": {
        "name": "<string>",
        "city": "<string>",
        "country": "<string>",
        "categoryCode": "<string>"
      },
      "entryMode": "<string>",
      "billing": {
        "billingAmount": "<string>",
        "billingCurrency": {
          "symbol": "<string>",
          "code": "<string>",
          "decimals": 123,
          "name": "<string>"
        }
      },
      "transactionCurrency": {
        "symbol": "<string>",
        "code": "<string>",
        "decimals": 123,
        "name": "<string>"
      },
      "cardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "cardToken": "<string>",
      "clearedAt": "2023-11-07T05:31:56Z",
      "isPending": true,
      "kind": "Payment",
      "transactions": [
        {
          "status": "<string>",
          "to": "<string>",
          "value": "<string>",
          "data": "<string>",
          "hash": "<string>"
        }
      ],
      "declineReason": {
        "code": "<string>",
        "message": "<string>"
      },
      "wallet": {
        "provider": "apple_pay",
        "deviceBrand": "<string>",
        "deviceModel": "<string>",
        "deviceType": "<string>",
        "deviceName": "<string>"
      },
      "enrichment": {
        "status": "matched",
        "merchant": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "logoUrl": "<string>"
        },
        "shop": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "<string>",
          "category": {
            "name": "<string>",
            "logoUrl": "<string>"
          },
          "tags": ["<string>"],
          "address": {
            "street": "<string>",
            "city": "<string>",
            "zip": "<string>",
            "country": "<string>",
            "areas": [
              {
                "name": "<string>",
                "value": "<string>"
              }
            ]
          },
          "coordinates": {
            "latitude": 123,
            "longitude": 123,
            "accuracy": "<string>",
            "zoom": 123
          },
          "url": "<string>",
          "googlePlaceId": "<string>",
          "phoneNumber": "<string>"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>",
    "hasNext": true
  }
}
```


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