Create a Card

curl --request POST \
  --url https://api.payvessel.com/pms/api/external/request/virtual-cards/ \
  --header 'Content-Type: <content-type>' \
  --header 'api-key: <api-key>' \
  --header 'api-secret: <api-secret>' \
  --data '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone": "08031234567",
  "bvn": "22345678901",
  "nin": "12345678901",
  "dob": "1990-05-15",
  "image": "data:image/jpeg;base64,YOUR_BASE64_IDENTITY_IMAGE",
  "state": "Lagos",
  "lga": "Ikeja",
  "street": "12 Admiralty Way, Lekki Phase 1",
  "postal_code": "101233",
  "brand": "VISA",
  "currency": "USD",
  "is_contactless": false,
  "prefund_amount": "10.00",
  "card_name": "Jane Doe"
}
'

{
  "status": true,
  "message": "Virtual card creation started",
  "data": {
    "id": "7f219a25-d968-4894-9a8b-ba83fa0bf6ec",
    "status": "PENDING",
    "masked_pan": "",
    "balance": "10.00",
    "currency": "USD",
    "brand": "VISA"
  }
}

{
  "error": 401,
  "message": "Unauthorized. Please check your API key."
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

POST

pms

api

external

request

virtual-cards

curl --request POST \
  --url https://api.payvessel.com/pms/api/external/request/virtual-cards/ \
  --header 'Content-Type: <content-type>' \
  --header 'api-key: <api-key>' \
  --header 'api-secret: <api-secret>' \
  --data '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone": "08031234567",
  "bvn": "22345678901",
  "nin": "12345678901",
  "dob": "1990-05-15",
  "image": "data:image/jpeg;base64,YOUR_BASE64_IDENTITY_IMAGE",
  "state": "Lagos",
  "lga": "Ikeja",
  "street": "12 Admiralty Way, Lekki Phase 1",
  "postal_code": "101233",
  "brand": "VISA",
  "currency": "USD",
  "is_contactless": false,
  "prefund_amount": "10.00",
  "card_name": "Jane Doe"
}
'

{
  "status": true,
  "message": "Virtual card creation started",
  "data": {
    "id": "7f219a25-d968-4894-9a8b-ba83fa0bf6ec",
    "status": "PENDING",
    "masked_pan": "",
    "balance": "10.00",
    "currency": "USD",
    "brand": "VISA"
  }
}

{
  "error": 401,
  "message": "Unauthorized. Please check your API key."
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

This resource allows you to create a card for a customer. This operation is asynchronous, meaning we notify you via a webhook event on the final status.

Contactless cards

Use the optional boolean field is_contactless on the create payload:

Value	Description
`false`	Standard virtual card (default)
`true`	Contactless-enabled card for tap-to-pay use cases

Contactless cards may have a different issuance fee.

Headers

api-key

string

required

Your Payvessel public API key

api-secret

string

required

Your Payvessel secret

Content-Type

enum<string>

required

Request content type

Available options:

application/json

Body

application/json

brand

enum<string>

required

Card network

Available options:

VISA,

MASTERCARD

currency

enum<string>

required

Must be USD for customer cards

Available options:

USD

first_name

string

Customer first name

last_name

string

Customer last name

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

is_contactless

boolean

default:false

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)

Example:

"10.00"

card_name

string

Optional label on card (max 255 characters)

Response

Virtual card creation started

status

boolean

required

Indicates whether the request succeeded

message

string

required

Human-readable result message

Example:

"Virtual card creation started"

data

object

required

Issued card details

Show child attributes

Getting Started

Transactions

Virtual Accounts

Issuing

Transfer

Wallets

Identity Verification

Value Added Services

Webhook

Contactless cards

Headers

Body

Response

​Contactless cards

Headers

Body

Response

Contactless cards