List & Get Cards

---

List Cards

Returns all cards (instruments) for a wallet with optional filtering and pagination.

Endpoint

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

Query Parameters

Parameter	Type	Description
statuses[]	array	Filter by status: creating, creating_failed, active, frozen, closed, expired
page	integer	Page number
quantity	integer	Items per page
createdAtFrom	string	ISO 8601 date filter (from)
createdAtTo	string	ISO 8601 date filter (to)
sortBy	string	Sort field: createdAt, name, status
sortType	string	Sort direction: asc or desc

Request

curl "https://api.4pay.cc/api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments?statuses[]=active&sortBy=createdAt&sortType=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

{
  "data": [
    {
      "cardId": "abc123e4-5678-90ab-cdef-1234567890ab",
      "name": "Business Card",
      "currency": "USD",
      "availableBalance": "500.00",
      "holder": "John Doe",
      "cardType": "virtual",
      "maskedNumber": "4111******1111",
      "paymentSystem": "Visa",
      "expiredAt": "12.2027",
      "cardStatus": "active"
    }
  ],
  "pagination": {
    "quantity": 25,
    "totalQuantity": 1,
    "currentPage": 1,
    "pages": 1
  }
}

---

Get Card Details

Returns detailed information about a specific card, including limits and owner info.

Endpoint

GET /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/{instrument_id}

Path Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Your organization ID
wallet_id	string	Yes	Wallet UUID
instrument_id	string	Yes	Card UUID

Request

curl "https://api.4pay.cc/api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/{instrument_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

{
  "data": {
    "account": {
      "id": "8f3d0c3d-9f3e-4ef6-8fae-c3169025dfcb",
      "name": "Business Wallet"
    },
    "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"
    }
  }
}

Response Fields

Field	Type	Description
card.id	string	Card UUID
card.name	string	Card label
card.status	string	Current status
card.availableBalance	string	Card balance available for spending
card.maskedNumber	string	Masked card number (first 4 + last 4)
card.cardType	string	virtual or physical
card.paymentSystem	string	Visa or Mastercard
card.expiredAt	string	Expiry in MM.YYYY format
card.limits	object	Current spending limits
card.cardOwner	object	Holder information

---

Update Card

Update a card's name or spending limits. Async operation.

Endpoint

PATCH /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/{instrument_id}

Request Body

{
  "name": "Corporate Card",
  "limits": {
    "daily_limit": "200.00",
    "monthly_limit": "5000.00"
  }
}

Request

curl -X PATCH "https://api.4pay.cc/api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/{instrument_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Card",
    "limits": {
      "daily_limit": "200.00",
      "monthly_limit": "5000.00"
    }
  }'