> For the complete documentation index, see [llms.txt](https://docs.zebec.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zebec.io/developer-docs/partner-api/cards.md).

# Cards

Read Carbon card metadata and transactions with the Zebec Partner API.

The Cards endpoints let a partner read card metadata and transaction history for users under their partner scope.

## Endpoints

### Get card metadata

```http
GET /partner/v1/cards
Authorization: Bearer <accessToken>
```

Returns card summary metadata. PAN and CVV are **not** included in the response.

Example response:

```json
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "last4": "1234",
  "expiryMonth": "07",
  "expiryYear": "2050",
  "cardType": "carbon",
  "cardStatus": "ACTIVE",
  "availableBalance": { "amount": "125.50", "currencyCode": "USD" }
}
```

### List card transactions

```http
GET /partner/v1/cards/transactions?page=1&take=10&status=SUCCESS&chain=SOLANA&startDate=2026-01-01&endDate=2026-01-31
Authorization: Bearer <accessToken>
```

Returns a list of card transactions.

Example response:

```json
{
  "items": [
    {
      "cardNumber": "************1234",
      "authDate": "2026-01-14",
      "postDate": "2026-01-15",
      "description": "Carbon card top-up",
      "amount": "100.00",
      "postAmount": "100.00",
      "issuingCurrency": "USD",
      "merchantName": "Zebec",
      "transactionResult": "Approved",
      "transactionType": "Credit",
      "cardHolderAdjustment": "0.00",
      "code": "00",
      "reference": "TXN-123456",
      "transactionTimestamp": "2026-01-14T10:30:00.000Z",
      "uid": "onbe-transaction-id",
      "merchantCategoryCode": "4829",
      "reversed": "false"
    }
  ],
  "page": 1,
  "take": 10,
  "itemCount": 42
}
```

`page` is 1-indexed and `take` defaults to 10. The partner read endpoint currently applies `startDate` and `endDate` (ISO dates); omit them to use the default 90-day lookback. The legacy `term=allTime|currentMonth|lastSixMonths|lastYear` parameter can supply the date window. `itemCount` is the total number of transactions returned by the upstream card provider in that window, not the number in the current page. Results are returned in the provider's order.

The general card-order DTO also exposes `status`, `cardType`, `chain`, and `order`, but these filters are not applied by `/partner/v1/cards/transactions` today. Do not rely on them for partner reads; filter the returned page in your application or request a future API version that explicitly advertises those filters.

## Errors

All errors are JSON. Typical responses are:

| HTTP | Example                                                  | Meaning                                                             |
| ---- | -------------------------------------------------------- | ------------------------------------------------------------------- |
| 401  | `{ "statusCode": 401, "message": "Unauthorized" }`       | Missing/expired token or invalid partner authentication.            |
| 403  | `{ "statusCode": 403, "message": "Insufficient scope" }` | API key lacks `cards:read`.                                         |
| 404  | `{ "statusCode": 404, "message": "Card not found" }`     | No Carbon card, or a cross-partner resource (intentionally hidden). |
| 429  | `{ "statusCode": 429, "message": "Too Many Requests" }`  | Rate limit exceeded; retry with backoff.                            |

Do not retry a `401` with the same token: refresh it while still valid, or restart OTP authentication after expiry.

## Required scope

Both endpoints require the `cards:read` scope on your partner API key.

## User resolution

The user is derived from the Bearer token returned by `POST /partner/v1/auth/otp/verify`. Do not supply a user identifier in the request path or body.

## Common use cases

* Display a user's card status and balance inside your app.
* Show recent card activity.
* Poll whether a top-up has landed before showing updated balances.

For full schemas and example responses, see the [sandbox Swagger UI](https://dev-super.api.zebec.io/api/partner). Production uses the same routes and schema at `https://api.superapp.zebec.io`; production Swagger is private, so request the versioned OpenAPI file from your Zebec partner engineer.