---
title: "Create a Card"
method: POST
path: "/pms/api/external/request/virtual-cards/"
tags: ["Issuing"]
---

# Create a Card

`POST /pms/api/external/request/virtual-cards/`

Create a USD virtual card for a customer with full KYC and initial prefund. This operation is asynchronous: the response returns a card in PENDING status, and PayVessel notifies you via a webhook when the card reaches its final status (for example ACTIVE). You may also poll Get a Card until activation completes.

## Headers

- `api-key` string, required
- `api-secret` string, required
- `Content-Type` 'application/json', required

## Request body

- CreateCustomerVirtualCardRequest
  - `first_name` string — Customer first name
  - `last_name` string — Customer last name
  - `email` string, email — Email address
  - `phone` string — Nigerian phone number
  - `bvn` string — 11-digit Bank Verification Number
  - `nin` string — 11-digit National Identification Number
  - `dob` string, date — Date of birth (YYYY-MM-DD)
  - `image` string — Base64-encoded identity document image
  - `state` string — State of residence
  - `lga` string — Local government area
  - `street` string — Street address
  - `postal_code` string — Postal code
  - `brand` 'VISA' | 'MASTERCARD', required — Card network
  - `currency` 'USD', required — Must be USD for customer cards
  - `is_contactless` boolean — Set to true to issue a contactless-enabled card. Defaults to false for a standard virtual card.
  - `prefund_amount` string — Optional initial card balance in USD (minimum 1.00 when provided)
  - `card_name` string — Optional label on card (max 255 characters)

## Response `201`

Virtual card creation started

- VirtualCardResponse
  - `status` boolean, required — Indicates whether the request succeeded
  - `message` string, required — Human-readable result message
  - `data` IssuedCard, required
    - `id` string, uuid — PayVessel card ID
    - `business_id` string, uuid — Owning business
    - `kind` string — customer card
    - `customer_id` string, uuid — Linked customer ID
    - `customer_name` string — Customer display name
    - `card_name` string — Name on card
    - `masked_pan` string — Masked PAN (empty while PENDING)
    - `status` 'PENDING' | 'ACTIVE' | 'FROZEN' | 'TERMINATED' | 'FAILED' — Card lifecycle status
    - `currency` string — USD
    - `brand` string — VISA or MASTERCARD
    - `balance` string — Issuer-synced balance in USD
    - `expiry` string — Card expiry (MM/YY)
    - `card_number` string — Full PAN (GET card only, when ACTIVE/FROZEN)
    - `cvv` string — CVV (GET card only, when ACTIVE/FROZEN)
    - `created_datetime` string, date-time
    - `updated_datetime` string, date-time

## Other responses

- `401` — Unauthorized request
- `403` — Forbidden request
- `404` — Resource not found
- `500` — Internal server error

---

[API](https://skmtc.net/payvessel/apis/payvessel-value-added-services-api.md) · [All operations](https://skmtc.net/payvessel/apis/payvessel-value-added-services-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payvessel/payvessel-value-added-services-api/versions/31040a9358ef/schema)