---
title: "Cards overview"
description: "Issue and manage virtual and physical cards."
---

# Cards overview

Use the Cards API to submit card applications, issue cards, retrieve balances and sensitive details, manage PINs and status, and move funds from cards.

<CardGroup cols={2}>
  <Card title="Browse card endpoints" icon="code" href="/api-reference/cards/post-v1-cards-applications-new">
    Start a card application or browse the operations in this category.
  </Card>
  <Card title="Cards integration guide" icon="book" href="/platform/cards/overview">
    Review card issuance, lifecycle, and security guidance.
  </Card>
</CardGroup>

## How it works

Issuing a card is a two-step process:

1. **Apply** — create a card application for the customer with [`POST /v1/cards/applications/new`](/api-reference/cards/post-v1-cards-applications-new) and wait for it to be approved.
2. **Issue** — once the application is approved, create the card with [`POST /v1/cards`](/api-reference/cards/post-v1-cards).

After issuance you can fund the card, check its balance, manage its PIN, and freeze or block it. Card balances are denominated in USD.

## Endpoints

### Card applications

| Endpoint | Description |
|---|---|
| [`POST /v1/cards/applications/new`](/api-reference/cards/post-v1-cards-applications-new) | Initiate a card application for a customer |
| [`GET /v1/cards/applications`](/api-reference/cards/get-v1-cards-applications) | List card applications with filters and pagination |
| [`GET /v1/cards/applications/{application_id}`](/api-reference/cards/get-v1-cards-applications-application-id) | Retrieve a single card application |

### Cards

| Endpoint | Description |
|---|---|
| [`POST /v1/cards`](/api-reference/cards/post-v1-cards) | Create a card for a customer with an approved application |
| [`GET /v1/cards`](/api-reference/cards/get-v1-cards) | List cards with filters and pagination |
| [`GET /v1/cards/{card_id}`](/api-reference/cards/get-v1-cards-card-id) | Retrieve card details (non-sensitive) |
| [`GET /v1/cards/{card_id}/balance`](/api-reference/cards/get-v1-cards-card-id-balance) | Current spendable balance on the card (USD) |
| [`GET /v1/cards/{card_id}/sensitive-details`](/api-reference/cards/get-v1-cards-card-id-sensitive-details) | Retrieve encrypted `card_number` and `cvv` |
| [`GET /v1/cards/{card_id}/pin`](/api-reference/cards/get-v1-cards-card-id-pin) | Retrieve the encrypted card PIN |
| [`PUT /v1/cards/{card_id}/pin`](/api-reference/cards/put-v1-cards-card-id-pin) | Update the card PIN |
| [`PATCH /v1/cards/{card_id}/update`](/api-reference/cards/patch-v1-cards-card-id-update) | Freeze, unfreeze, or permanently block a card |
| [`POST /v1/cards/withdraw`](/api-reference/cards/post-v1-cards-withdraw) | Withdraw funds from a card back to the customer |

## Card statuses

| Status | Meaning |
|---|---|
| `active` | Card can be used for transactions |
| `freeze` | Card is temporarily frozen — update the status back to `active` to reactivate |
| `blocked` | Card is permanently blocked and can't be reactivated |

## Sensitive details

Card numbers, CVVs, and PINs are never returned in plain text. The sensitive-details endpoint returns values encrypted with an RSA public key that you supply in the `X-Client-Public-Key` header (Base64-encoded PEM, 2048-bit minimum). See the [card sensitive details guide](/platform/cards/view-card-sensitive-details/overview) for end-to-end examples in Go, Python, and JavaScript.

## Authentication

All requests use `https://api.gravv.xyz/v1/` and authenticate with the `Api-Key` header. See [Authentication](/getting-started/authentication) for details.