Issue a Virtual Card
Learn how to issue virtual debit cards, configure spending limits, and manage card lifecycle states. Cards are issued through our partner network and provisioned in real-time.
Card Types
Choose between virtual and physical cards based on your use case.
VIRTUALDigital-only cards for online purchases
- Instant issuance
- Apple Pay / Google Pay ready
- Perfect for subscriptions
- No physical card needed
PHYSICALPlastic cards for in-person payments
- Chip and contactless
- PIN-protected
- ATM withdrawals
- Delivered within 5-7 days
Issue a Card
Create a new virtual card linked to an account. The card is provisioned instantly and ready for use.
1import { Hyperscale } from '@hyperscale/sdk';23const hyperscale = new Hyperscale({4 apiKey: process.env.HYPERSCALE_API_KEY,5});67// Issue a virtual debit card8const card = await hyperscale.cards.issue({9 accountId: 'acc_01HXK4N...',10 type: 'VIRTUAL',11 brand: 'VISA',12 currency: 'SAR',13});1415console.log('Card ID:', card.id);16console.log('Last 4:', card.last4);17console.log('Status:', card.status);Retrieve Card Details
Access the full card number, CVV, and expiry for display in your app. Sensitive fields are encrypted and require your decryption key.
1// Retrieve full card details (PCI-DSS compliant)2const cardDetails = await hyperscale.cards.getSecure(card.id, {3 // Include sensitive fields4 include: ['number', 'cvv', 'expiry'],5});67// These fields are returned encrypted8// and must be decrypted on the client9console.log('Encrypted number:', cardDetails.encryptedNumber);10console.log('Expiry:', cardDetails.expiryMonth + '/' + cardDetails.expiryYear);PCI-DSS Compliance: Card details are encrypted using your public key. Never store or log decrypted card data on your servers.
Card Lifecycle
Cards transition through different states during their lifecycle.
| State | Description |
|---|---|
PENDING | Card is being provisioned |
ACTIVE | Card is ready for transactions |
FROZEN | Temporarily blocked, can be unfrozen |
BLOCKED | Permanently blocked, cannot be reactivated |
EXPIRED | Past expiry date, replacement needed |
Set Spending Limits
Configure daily, monthly, and per-transaction limits to control spending.
1// Configure spending controls2await hyperscale.cards.setLimits(card.id, {3 daily: {4 amount: 5000,5 currency: 'SAR',6 },7 monthly: {8 amount: 50000,9 currency: 'SAR',10 },11 perTransaction: {12 amount: 2000,13 currency: 'SAR',14 },15});Freeze & Unfreeze
Allow users to temporarily freeze their card without cancelling it.
1// Temporarily freeze the card2await hyperscale.cards.freeze(card.id, {3 reason: 'USER_REQUESTED',4});56// Later, unfreeze the card7await hyperscale.cards.unfreeze(card.id);