API Reference

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.

For step-by-step examples, see Cards recipes.

How it works

Your business has one card account (type card), and it backs every card. Open it before you issue the first card. See Set up your card account. After that, issuing a card takes two steps:

Apply. Activate the card feature for the customer with POST /v1/risk/features/activate. Send feature_id virtual_cards and your card account as provider_data.account_id. Activation creates the card application. It is the path that works in both sandbox and live. POST /v1/cards/applications/new works in sandbox only. Track the application with GET /v1/cards/applications, which is the only endpoint that returns application_status. See Card KYC and activation.
Issue. Once the application is approved, create the card with POST /v1/cards.

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

Endpoints

Card applications

Endpoint	Description
`POST /v1/cards/applications/new`	Start a card application for a customer (sandbox only)
`GET /v1/cards/applications`	List card applications with filters and pagination
`GET /v1/cards/applications/{application_id}`	Retrieve a single card application (without `application_status`)

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`	Get the card's current spendable balance in USD
`GET /v1/cards/{card_id}/sensitive-details`	Retrieve the encrypted card number (`pan`) 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, and set its daily limit. Always send `limit`
`POST /v1/cards/withdraw`	Withdraw funds from a card to its own account. Not yet available for new cards

Card statuses

Status	Meaning
`active`	The card can be used for transactions
`freeze`	The card is temporarily frozen. Set the status back to `active` to reactivate it
`blocked`	The card is permanently blocked and can't be reactivated
`inactive`	A physical card that is not yet activated. Physical cards are not yet available

Always send both status and limit in a status update. An update without limit saves the daily limit as 0.

The API never returns card numbers, CVVs or PINs in plain text. The sensitive-details endpoint returns values encrypted with an RSA public key that you send in the X-Client-Public-Key header. Send the key as a Base64-encoded PEM, and use a key of 2048 bits or more. Gravv wraps a one-time AES-256-GCM key with your public key, using RSA-OAEP with SHA-256. 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.

Was this page helpful?