Retrieve cards

After creating a card, you can use the Get card endpoint to retrieve a single card's details. To retrieve all cards, use the Get cards endpoint.

Retrieve a single card

Use the Get card endpoint to retrieve details of a specific card. Include your API key and the card id in the request:

curl --request GET \
     --url https://api.gravv.xyz/v1/cards/<card id> \
     --header 'Api-Key: <Api Key>'
     --header 'accept: application/json'

You will receive a response with the complete card details:

{
  "data": {
    "id": "dce0192a-9b3d-440b-9500-33dc9ac8dc20",
    "date_created": "2025-10-10T13:04:36.544962+01:00",
    "date_updated": "2025-10-13T17:57:26.56108+01:00",
    "spending_controls": {
      "activated": true,
      "daily_transaction_limit": 50,
      "type": "virtual"
    },
    "name_on_card": "Test User Name",
    "masked_pan": "9351",
    "expiry": "7/2029",
    "status": "active",
    "address": {
      "street": "Palo Alto",
      "city": "Palo Alto",
      "state": "California",
      "postal_code": "01023",
      "country_iso_code": "US"
    },
    "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
    "currency": "USD",
    "network": "visa"
  },
  "error": null
}

Retrieve all cards

Use the Get cards endpoint to retrieve all cards with pagination support. Include your API key in the request:

curl --request GET \
     --url https://api.gravv.xyz/v1/cards \
     --header 'Api-Key: <Api Key>' \
     --header 'accept: application/json'

You will get a response similar to this:

{
  "data": {
    "items": [
      {
        "account_id": "9b40be8d-9d74-4d2a-8897-dea3ef80ad23",
        "address": {
          "city": "New York",
          "country_iso_code": "US",
          "postal_code": "10002",
          "state": "New York",
          "street": "201 Allen St"
        },
        "currency": "USD",
        "customer_id": "1805c3be-abca-4698-9cbd-789fc1d619eb",
        "date_created": "2025-12-05T10:48:18.170061Z",
        "date_updated": "2025-12-06T15:31:40.273281Z",
        "expiry": "8/2029",
        "id": "ac21ddfc-f6ba-432c-abb3-c5e2243e8ef7",
        "masked_pan": "9032",
        "name_on_card": "Ndifreke Jacob",
        "network": "visa",
        "status": "active",
      }
    ],
    "items_per_page": 1,
    "page": 1,
    "total_items": 1,
    "total_pages": 1
  },
  "error": null
}

Get paginated results

You can set the number of results and navigate through pages using pagination parameters. The page parameter specifies which page to retrieve, and items_per_page specifies how many cards appear on each page:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/cards?page=2&items_per_page=20' \
     --header 'Api-Key: <Api Key>'
     --header 'accept: application/json'

Response fields

The response contains the following fields:

Field	Description
id	Unique identifier for the card
date_created	Timestamp when the card was created
date_updated	Timestamp when the card was last updated
spending_controls	Object containing spending limit settings for the card
spending_controls.activated	Shows whether spending controls are active
spending_controls.single_transaction_limit	Maximum amount allowed per transaction in USD
spending_controls.daily_transaction_limit	Maximum total spending allowed per day in USD
spending_controls.type	Card type, either virtual or physical
name_on_card	Name printed on the card
masked_pan	Last 4 digits of the card number
expiry	Card expiration date in MM/YYYY format
status	Current card status: active, freeze, or blocked
address	Object containing the billing address associated with the card
address.street	Street address
address.city	City name
address.state	State or region
address.postal_code	Postal or ZIP code
address.country_iso_code	Two-letter country code
customer_id	ID of the customer who owns the card
currency	Currency of the card
network	Payment network, either Visa or masterMastercardcard

For more information on all card endpoints, see Cards.