Issue Card

Creates a new card (virtual or physical) from a wallet. This is an async operation — poll the card status until it becomes active.

Prerequisites

Before issuing a card, you need:

1. An active wallet with sufficient balance → Create Wallet
2. A holder (card owner) → Create Holder
3. A valid BIN for issuance → Wallet Limits

---

Endpoint

POST /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments

Path Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Your organization ID
wallet_id	string	Yes	Wallet to issue the card from

---

Request Body

{
  "name": "Business Travel Card",
  "cardOwnerId": "owner-12345",
  "cardType": "virtual",
  "limits": {
    "daily_limit": "100.00",
    "monthly_limit": "3000.00",
    "transaction_limit": "50.00"
  },
  "cardProviderBinId": "ff246e21-3bda-4e47-83fb-05203939fe5b",
  "currency": "USD"
}

Fields

Field	Type	Required	Description
name	string	Yes	Card label (e.g., "Marketing Q1")
cardOwnerId	string	Yes	Holder ID from Create Holder
cardType	string	Yes	virtual or physical
limits	object	Yes	Spending limits (at least one required)
cardProviderBinId	string	No	Specific BIN for issuance — from Wallet Limits
binCategoryId	string	No	BIN category — system picks best BIN from this category
currency	string	No	ISO 4217 currency code (e.g., USD)

BIN selection

Provide either cardProviderBinId OR binCategoryId — not both. If neither is provided, the wallet's default BIN configuration is used.

Spending Limits (limits object)

Field	Type	Description
daily_limit	string	Max spend per day
weekly_limit	string	Max spend per week
monthly_limit	string	Max spend per month
year_limit	string	Max spend per year
lifetime_limit	string	Max total spend over card lifetime
transaction_limit	string	Max per single transaction

All limit values are strings with dot as decimal delimiter (e.g., "100.00").

Check Wallet Limits for the allowed min/max range for each limit type.

---

Request

curl -X POST "https://api.4pay.cc/api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Travel Card",
    "cardOwnerId": "owner-12345",
    "cardType": "virtual",
    "limits": {
      "daily_limit": "100.00",
      "monthly_limit": "3000.00",
      "transaction_limit": "50.00"
    },
    "cardProviderBinId": "ff246e21-3bda-4e47-83fb-05203939fe5b"
  }'

---

Response

201 Created

{
  "data": {
    "id": "fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d"
  }
}

Now poll the card until status is active:

GET /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d

Once active, you can fund the card and retrieve credentials.