Card Operations

Card operations are individual transactions on a specific card — purchases, refunds, top-ups, withdrawals, and fees.

---

List Card Operations

Returns card transactions across all cards in your organization, with rich filtering options.

Endpoint

GET /api/v2/organizations/{org_id}/instruments/operations

Query Parameters

Parameter	Type	Description
page	integer	Page number
quantity	integer	Items per page
ids[]	array	Filter by specific transaction IDs
cardIds[]	array	Filter by card IDs
accountIds[]	array	Filter by wallet IDs
types[]	array	Filter by type (see below)
statuses[]	array	Filter by status (see below)
createdAtFrom	string	ISO 8601 start date
createdAtTo	string	ISO 8601 end date
sortBy	string	createdAt or status
sortType	string	asc or desc

Transaction Types

Type	Description
purchase	Card payment at merchant
refund	Refund from merchant
fee	Service fee charged
top_up	Balance added to card
withdrawal	Balance withdrawn from card

Transaction Statuses

Status	Description
authorized	Transaction authorized, awaiting settlement
completed	Transaction settled
declined	Transaction declined
canceled	Transaction canceled

Request

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

Response

200 OK

{
  "data": [
    {
      "id": "d413a9d7-6c7b-4f89-b47e-c742060a12c7",
      "card": {
        "id": "abc123e4-5678-90ab-cdef-1234567890ab",
        "name": "Business Card",
        "maskedNumber": "4111******1111"
      },
      "amount": "50.00",
      "currency": "USD",
      "type": "purchase",
      "status": "completed",
      "merchantName": "Amazon",
      "merchantCategory": "5411",
      "createdAt": "2025-06-02T15:38:49+00:00"
    }
  ],
  "pagination": {
    "quantity": 25,
    "totalQuantity": 2,
    "currentPage": 1,
    "pages": 1
  }
}

---

Get Card Operation Details

Returns detailed information about a specific card transaction, including fee and settlement amounts.

Endpoint

GET /api/v2/organizations/{org_id}/instruments/operations/{operation_id}

Path Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Your organization ID
operation_id	string	Yes	Transaction UUID

Request

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

Response

200 OK

{
  "data": {
    "id": "d413a9d7-6c7b-4f89-b47e-c742060a12c7",
    "card": {
      "id": "abc123e4-5678-90ab-cdef-1234567890ab",
      "name": "Business Card",
      "maskedNumber": "4111******1111"
    },
    "account": {
      "id": "8f3d0c3d-9f3e-4ef6-8fae-c3169025dfcb",
      "name": "Business Wallet"
    },
    "amount": "50.00",
    "currency": "USD",
    "feeAmount": "0.50",
    "feeCurrency": "USD",
    "settlementAmount": "49.50",
    "settlementCurrency": "USD",
    "type": "purchase",
    "status": "completed",
    "merchantName": "Amazon",
    "merchantCategory": "5411",
    "description": "Online purchase",
    "createdAt": "2025-06-02T15:38:49+00:00",
    "updatedAt": "2025-06-02T15:40:00+00:00"
  }
}

Response Fields

Field	Type	Description
amount	string	Transaction amount in card currency
feeAmount	string	Fee charged for this transaction
settlementAmount	string	Net amount after fee
merchantName	string	Merchant name (for purchases)
merchantCategory	string	MCC code (Merchant Category Code)
description	string	Transaction description