Cartes virtuelles

Émettez des cartes Visa/Mastercard virtuelles, alimentez les soldes, retirez et gérez le cycle de vie. Le client doit d'abord être créé via Customers.

For field names, pending cards, local_id, 402 errors and secure-view : see the Card integration guide (single page).

Utilisez l'id client retourné par POST /customers comme customer_id. Le local_id HeyQo est aussi accepté.

POST /cards

POSThttps://heyqo.cash/business/v1/cards

Requis

customer_id — Id client de POST /customers ou local_id HeyQo
currency — ex. usd
brand — visa ou mastercard

Optionnel

amount — Initial funding on the card. Minimum $1.00. If omitted, $1.00 is applied automatically.
label — Libellé pour votre tableau de bord

Billing at creation: card fee (plan) + initial deposit (≥ $1). Free plan: $4 fee + $1 deposit = $5 debited from your merchant wallet. The $1 deposit stays on the card.

Issue card (automatic $1 deposit)

curl -X POST "https://heyqo.cash/business/v1/cards" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "92ed2f6e-6e66-4868-b259-b64d9bb96f0b",
    "currency": "usd",
    "brand": "visa",
    "label": "Primary card"
  }'

Issue card with higher initial funding

curl -X POST "https://heyqo.cash/business/v1/cards" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "92ed2f6e-6e66-4868-b259-b64d9bb96f0b",
    "currency": "usd",
    "brand": "visa",
    "amount": 25.00
  }'

GET /cards

GEThttps://heyqo.cash/business/v1/cards?customer_id={id}

Liste toutes les cartes virtuelles d'un client. customer_id est requis.

curl "https://heyqo.cash/business/v1/cards?customer_id=CUSTOMER_ID" \
  -H "Authorization: Bearer TOKEN"

GET /cards/{id}

GEThttps://heyqo.cash/business/v1/cards/{id}

Retrieve card details, balance and status. Returns last4 and masked_pan only — never PAN or CVV.

curl "https://heyqo.cash/business/v1/cards/CARD_ID" \
  -H "Authorization: Bearer TOKEN"

POST /cards/{id}/secure-view

POSThttps://heyqo.cash/business/v1/cards/{id}/secure-view

Recommended PCI display. Returns a one-time iframe URL (90 seconds). Partners choose colors and text layout. PAN and CVV render inside the iframe only.

theme — plain (default, transparent, no HeyQo card background), or custom (partner colors/image). heyqo is reserved for the HeyQo merchant portal.
layout — stack, card, compact, free (absolute positions)
align — left, center, right
fields_order — e.g. pan,cvv,expiry,cardholder,brand
positions — per-field top/left/right/bottom as % or px (pan, cvv, expiry, cardholder, brand)
pan_top / pan_left — shortcuts, also cvv_*, expiry_*, cardholder_*, brand_*
text_color — hex, default #ffffff
label_color — hex for labels (Card number, CVV…)
button_color / button_text_color — Copy buttons
background_url — HTTPS image · background_color — hex
brand_label — optional partner name

curl -X POST "https://heyqo.cash/business/v1/cards/CARD_ID/secure-view" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://heyqo.cash/business/v1/cards/CARD_ID/secure-view" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"theme":"plain","layout":"stack","align":"left","text_color":"#ffffff"}'

curl -X POST "https://heyqo.cash/business/v1/cards/CARD_ID/secure-view" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"layout":"free","background_color":"#111827","text_color":"#ffffff","positions":{"pan":{"top":"40%","left":"8%"},"cvv":{"top":"72%","left":"8%"},"expiry":{"top":"72%","left":"40%"},"cardholder":{"top":"84%","left":"8%"},"brand":{"top":"72%","right":"6%"}}}'

<iframe src="IFRAME_URL" width="100%" height="280" style="border:0;background:transparent" allow="clipboard-write"></iframe>

GET /cards/{id}/reveal

GEThttps://heyqo.cash/business/v1/cards/{id}/reveal

Alias of secure-view. Same options via query string: layout, align, pan_position, text_color, label_color, button_color, background_url, background_color, brand_label.

curl "https://heyqo.cash/business/v1/cards/CARD_ID/reveal?theme=plain" \
  -H "Authorization: Bearer TOKEN"

curl "https://heyqo.cash/business/v1/cards/CARD_ID/reveal?background_url=https%3A%2F%2Fyour-cdn.com%2Fcard-bg.png&background_color=%23111827&brand_label=Acme%20Pay" \
  -H "Authorization: Bearer TOKEN"

POST /cards/{id}/deposit

POSThttps://heyqo.cash/business/v1/cards/{id}/deposit

Alimenter une carte virtuelle depuis votre wallet partenaire.

amount — requis, minimum 0,01
currency — optionnel, devise de la carte par défaut
wallet_id — wallet de règlement optionnel

curl -X POST "https://heyqo.cash/business/v1/cards/CARD_ID/deposit" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25.00, "currency": "usd"}'

POST /cards/{id}/withdraw

POSThttps://heyqo.cash/business/v1/cards/{id}/withdraw

Retirer des fonds de la carte vers votre wallet partenaire.

curl -X POST "https://heyqo.cash/business/v1/cards/CARD_ID/withdraw" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10.00, "currency": "usd"}'

PUT /cards/{id}/freeze

PUThttps://heyqo.cash/business/v1/cards/{id}/freeze

Bloquer temporairement les transactions de la carte.

curl -X PUT "https://heyqo.cash/business/v1/cards/CARD_ID/freeze" \
  -H "Authorization: Bearer TOKEN"

PUT /cards/{id}/unfreeze

PUThttps://heyqo.cash/business/v1/cards/{id}/unfreeze

Réactiver une carte gelée.

curl -X PUT "https://heyqo.cash/business/v1/cards/CARD_ID/unfreeze" \
  -H "Authorization: Bearer TOKEN"

PUT /cards/{id}/terminate

PUThttps://heyqo.cash/business/v1/cards/{id}/terminate

Fermer définitivement une carte virtuelle. Action irréversible.

curl -X PUT "https://heyqo.cash/business/v1/cards/CARD_ID/terminate" \
  -H "Authorization: Bearer TOKEN"

Réponse type

{
  "message": { "code": 201, "success": ["Card created successfully"] },
  "data": {
    "id": "card-uuid",
    "local_id": 1,
    "customer_id": "92ed2f6e-6e66-4868-b259-b64d9bb96f0b",
    "card": {
      "id": "card-uuid",
      "status": "active",
      "last4": "4242",
      "masked_pan": "•••• •••• •••• 4242",
      "balance": 25.00
    }
  },
  "type": "success"
}