Core Concepts

---

Data Model

Organization
└── Wallets (funding accounts)
    ├── Cards / Instruments
    │   └── Operations (transactions)
    └── Operations (wallet transactions)

Holders (card owners)
Deposits (crypto top-ups → wallet balance)

---

Wallets

A Wallet (also called an Account) is a funding pool linked to a card provider. Think of it like a bank account:

• Holds a balance in USD (or other currency)
• Can be topped up via Deposits (crypto)
• Has spending limits and BIN configurations
• Multiple cards can be issued from a single wallet
• Supports balance transfers between wallets

Each wallet is tied to a Provider — one of 4pay.cc's underlying card-issuing partners. You choose the provider when creating a wallet.

---

Cards (Instruments)

A Card (referred to as an Instrument in the API) is a payment card issued from a wallet. Key properties:

• Type: virtual or physical
• Lifecycle statuses: creating → active → frozen / closed / expired
• Balance: Cards have their own balance, funded from the parent wallet
• BIN: The Bank Identification Number determines the card network (Visa/Mastercard), country, and tokenization support (Apple Pay, Google Pay)
• Limits: Daily, weekly, monthly, yearly, lifetime, and per-transaction limits

Async issuance

Card creation is asynchronous. After POST .../instruments, poll GET .../instruments/{id} until status becomes active or creating_failed.

---

Holders

A Holder is the person associated with one or more cards. Required fields:

• cardOwnerId — your internal identifier for the holder
• firstName, lastName
• email — must be unique across your organization

The same holder can be assigned to multiple cards. Create holders once and reuse their cardOwnerId.

---

BINs and BIN Categories

A BIN (Bank Identification Number) is the first 6 digits of a card number. It determines:

• Payment network (Visa, Mastercard)
• Issuing country
• Supported tokenizations (Apple Pay, Google Pay)

BIN Categories group related BINs for specific use cases (e.g., travel, advertising, general). When issuing a card, you can specify either:

• cardProviderBinId — a specific BIN
• binCategoryId — let the system pick the best BIN from a category

---

Deposits

Deposits are how you fund wallets. 4pay.cc accepts crypto:

Currency	Network
USDT	TRON (TRC-20)
USDC	TRON (TRC-20)

When you create a deposit, the API returns a unique payment address. Send crypto to that address, and once confirmed on-chain, the funds are credited to your wallet (minus fee).

---

Operations (Transactions)

There are two types of operations:

Type	Scope	Examples
Instrument Operations	Per-card transactions	Purchase, refund, top-up, withdrawal, fee
Wallet Operations	Account-level movements	Deposit (payin), card issuance fee, transfer

---

Fees

Fees are configured per-wallet and can be:

• Percent — e.g., 2.5% of transaction amount
• Fixed Amount — e.g., $5.00 per card issuance

Fee types:

• cardTransactions — applied to each card transaction (% or fixed)
• cardIssuing — one-time fee per card issued (fixed)
• topUpsAllocation — applied when allocating top-up funds (%)

Some fees are inherited from the provider defaults unless overridden in wallet settings.