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.
Start a card application or browse the operations in this category.
Review card issuance, lifecycle, and security guidance.
How it works
Issuing a card is a two-step process:
- Apply — create a card application for the customer with
POST /v1/cards/applications/newand wait for it to be approved. - Issue — once the application is approved, create the card with
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 |
Initiate a card application for a customer |
GET /v1/cards/applications |
List card applications with filters and pagination |
GET /v1/cards/applications/{application_id} |
Retrieve a single card application |
Cards
| Endpoint | Description |
|---|---|
POST /v1/cards |
Create a card for a customer with an approved application |
GET /v1/cards |
List cards with filters and pagination |
GET /v1/cards/{card_id} |
Retrieve card details (non-sensitive) |
GET /v1/cards/{card_id}/balance |
Current spendable balance on the card (USD) |
GET /v1/cards/{card_id}/sensitive-details |
Retrieve encrypted card_number and cvv |
GET /v1/cards/{card_id}/pin |
Retrieve the encrypted card PIN |
PUT /v1/cards/{card_id}/pin |
Update the card PIN |
PATCH /v1/cards/{card_id}/update |
Freeze, unfreeze, or permanently block a card |
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 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 for details.