PayVessel USD virtual cards let your customers pay online at international merchants. You integrate through the external API using your business API key and secret; PayVessel handles issuer enrollment, card lifecycle, and wallet debits for funding. Use the API reference pages for each endpoint — they include a Try it playground (same pattern as Virtual Accounts), withDocumentation Index
Fetch the complete documentation index at: https://docs.payvessel.com/llms.txt
Use this file to discover all available pages before exploring further.
api-key and api-secret headers and sandbox/production server selection.
Create a Card
Issue with KYC and prefund
Get all Cards
List cards and status
Fund a Card
Load USD from business wallet
Card Fee Quote
Calculate fees before create or fund
Base URL
All virtual card endpoints live under:| Environment | Base URL |
|---|---|
| Production | https://api.payvessel.com |
| Sandbox | https://sandbox.payvessel.com |
POST https://api.payvessel.com/pms/api/external/request/virtual-cards/
Authentication matches other PayVessel external APIs. See Authentication for
api-key and api-secret headers.What you can do (external API)
| Capability | Description |
|---|---|
| Create customer card | Enroll or upgrade customer KYC, issue a USD virtual card, prefund from your business USD wallet |
| List / get card | Track PENDING → ACTIVE, masked PAN, issuer balance |
| Fund card | Debit business USD wallet; credit card balance at issuer |
| Withdraw | Move USD from card back to business wallet (minimum $3) |
| Freeze / unfreeze | Temporarily block or restore card spend |
| Terminate | Close card; remaining balance returns to business wallet (minus fees) |
| Transactions | Card spend, funding, and withdrawal history |
| Simulate transaction | Sandbox-only test spend/credit at the issuer |
| Fee quotes | Calculate charges before create, fund, or withdraw |
Integration flow
Quote creation cost
Use Card Fee Quote to show issuance and funding charges before debiting the wallet.
Create the card
Call Create a Card with customer KYC. Optionally include
prefund_amount (minimum $3 USD when provided).Wait for activation
New cards return
status: PENDING. Poll Get a Card until ACTIVE and card_number is present (usually seconds; allow up to a few minutes).Fund or let customer spend
Use Fund a Card for top-ups. Card spends are handled by the issuer; use Get Card Transactions for history.
Withdraw or terminate
Use Withdraw from a Card to return USD to your wallet, or Terminate Card to close the card.
Customer KYC (external API)
The external API requires full Nigerian KYC on every create request.customer_id is not accepted — existing customers are matched by email.
| Field | Required | Notes |
|---|---|---|
first_name, last_name | Yes | Customer legal name |
email, phone | Yes | Nigerian phone format |
bvn, nin | Yes | 11 digits |
dob | Yes | YYYY-MM-DD |
image | Yes | Base64 identity image |
state, lga, street, postal_code | Yes | Address |
brand, currency | Yes | USD only |
prefund_amount | No | Optional; minimum $3 USD when provided |
Money movement
Business USD wallet ↔ card
Business USD wallet ↔ card
Fund and create-time prefund debit your PayVessel business USD wallet (managed wallet). Withdraw and terminate credit it back (withdrawal fee may apply).
Card balance
Card balance
The issuer holds the spendable card balance. PayVessel syncs
balance on the card object from the issuer after fund, withdraw, and issuer events. Do not assume your local ledger equals issuer balance without calling Get card.Card spend
Card spend
Merchant charges (AUTHORIZATION, SETTLEMENT, etc.) reduce card balance only. They do not debit your business wallet. Query transactions for spend history.
Card statuses
| Status | Meaning |
|---|---|
PENDING | Issuer is creating the card; no PAN yet |
ACTIVE | Card can be funded and used |
FROZEN | Spend blocked; fund/withdraw may still be restricted |
TERMINATED | Closed; balance settled to wallet |
FAILED | Issuer rejected creation |
Fees
Use Card Fee Quote to calculate fees for a given operation (issuance, funding, withdrawal, spend, etc.) before debiting your wallet.
Funding fee tiers:
- Below tier threshold: flat fee in USD
- At or above tier: percentage of fund amount
Error handling
| HTTP | Typical cause |
|---|---|
401 | Missing or invalid api-key / api-secret |
400 | Validation (KYC, minimum amounts, insufficient wallet balance) |
404 | Unknown card_id for your business |
429 | External API rate limit |
{ "status": true|false, "message": "...", "data": ... }. Validation errors may include a errors object.
Best practices
Poll activation
After create, poll Get card until
ACTIVE before showing PAN-dependent UI.Quote before debit
Always show fee quotes before charging your user.
Idempotent UX
Store PayVessel
card_id and transaction id for support — issuer references are not exposed in API responses.Server-side only
Never call the external API from mobile or browser; keep secrets on your backend.
Guides and API reference
Conceptual guides (how it works, use cases) live under Guides → Issuing. Technical schemas, Try it, and cURL samples live under API reference → Issuing.Create a Card
Guide
Create a Card
API reference
Get a Card
API reference