Cards (Instruments)

A Card (called an Instrument in the API) is a virtual or physical payment card issued from a wallet. Cards are the core product of 4pay.cc.

---

Card Lifecycle

POST /instruments               →  issue card (async)
GET  /instruments/{id}          →  check status & balance
GET  /instruments/{id}/credentials  →  get full card number, CVV
PATCH /instruments/{id}/fund    →  add balance from wallet
PATCH /instruments/{id}/defund  →  return balance to wallet
POST /instruments/{id}/suspend  →  freeze card
POST /instruments/{id}/resume   →  unfreeze card
POST /instruments/{id}/terminate →  permanently close (irreversible)

---

Card Object

{
  "card": {
    "id": "abc123e4-5678-90ab-cdef-1234567890ab",
    "name": "Business Card",
    "status": "active",
    "currency": "USD",
    "availableBalance": "500.00",
    "maskedNumber": "4111******1111",
    "cardType": "virtual",
    "paymentSystem": "Visa",
    "expiredAt": "12.2027",
    "limits": {
      "daily_limit": "100.00",
      "monthly_limit": "3000.00"
    },
    "cardOwner": {
      "cardOwnerId": "owner-12345",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com"
    },
    "createdAt": "2025-06-02T15:38:49+00:00"
  }
}

Card Statuses

Status	Description
creating	Card is being provisioned (async)
creating_failed	Provisioning failed — retry or contact support
active	Card is operational
frozen	Card is temporarily suspended
closed	Card was terminated (irreversible)
expired	Card reached its expiry date

---

In This Section

• Issue Card — create a new virtual or physical card
• List & Get Cards — view cards and their details
• Card Credentials — retrieve full card number, CVV, expiry
• Fund & Defund — move balance to/from cards
• Suspend / Resume / Terminate — manage card lifecycle