Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Create a card application

Cards don't work the way accounts do. With an account you can create the account directly. With a card you can't: every card needs an approved card application behind it first. The application is where Gravv runs the customer's risk and compliance checks before any card is issued.

📘 Do I create the card directly, or apply first?

You apply first. There's no direct "create card" shortcut like there is for accounts. In production you don't call the card application endpoint yourself either. You activate the card feature, and that creates the application for you. Once the application is approved, you call Create a card.

How an application gets created

There are two ways to create a card application, and which one you use depends on the environment:

Environment How to create the application
Live Activate the card feature with Activate feature. Activating virtual_cards creates the application.
Sandbox Activating the feature works here too, and is the recommended path. A standalone Create card application endpoint also exists for testing. It is not supported in Live, so build your integration around feature activation.

Activating the feature is the one path that works in both environments, so use it everywhere.

Before you start

The customer must already exist and have completed intermediate KYC. Intermediate KYC includes a selfie (liveness) check, which the card application depends on.

Then confirm the customer is ready with Check feature eligibility for virtual_cards. Eligibility returns eligible: true only when KYC is completed and you supply the required provider data shown below.

Step 1: Activate the card feature

Call Activate feature with feature_id set to virtual_cards. For cards, the provider_data object is required:

Field Type Required Description
annual_remuneration number yes Customer's expected annual inflow in USD
estimated_monthly_limit number yes Expected monthly card spend in USD. Must be lower than annual_remuneration
ip_address string yes IP address the request comes from
account_id string no The card account that backs the card. Gravv derives it from your tenant's card account if you leave it out 
curl --request POST \
     --url https://api.gravv.xyz/v1/risk/features/activate \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: activate_cards_001' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
  "feature_id": "virtual_cards",
  "provider_data": {
    "annual_remuneration": 120000,
    "estimated_monthly_limit": 5000,
    "ip_address": "12.23.31.23"
  }
}
'

On success, the response confirms the feature is active and returns the application_id of the card application that was created:

{
  "data": {
    "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
    "feature_id": "virtual_cards",
    "status": "active",
    "activated_at": "2026-01-09T10:29:16.000Z",
    "data": {
      "application_id": "a14ec356-f33d-4384-ba68-4d9bfa19765b"
    }
  },
  "error": null
}

Save the application_id. You'll use it to track the application and, later, to confirm the card can be created.

If liveness isn't complete yet

If the customer hasn't completed their selfie (liveness) check, activation can't finish. The response comes back with a websdk_url instead:

{
  "data": {
    "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
    "feature_id": "virtual_cards",
    "status": "pending_liveness",
    "websdk_url": "https://verify.gravv.xyz/liveness/abc123xyz"
  },
  "error": null
}

Redirect the customer to the websdk_url to finish verification, then call Activate feature again. Activation is idempotent, so retrying after the check is done returns the existing application rather than creating a second one.

Step 2: Track the application status

A new application starts as pending while Gravv reviews it. Track it one of two ways:

curl --request GET \
     --url https://api.gravv.xyz/v1/cards/applications/{application_id} \
     --header 'Api-Key: <API_KEY>'

The application_status field tells you where the application stands:

Status What it means What to do
pending Under review Wait
approved Cleared. You can create the card Call Create a card
needs_information More detail is needed to process the application Supply the missing details and re-check
needs_verification Selfie verification is still required for intermediate KYC Send the customer to the application_link in the response, then re-check
manual_review A reviewer is checking the application Wait
denied The application was rejected Stop. The customer can't be issued a card
locked The application is locked for a security concern Contact support
canceled The application was canceled Start a new application if still needed

When application_status is needs_verification, the response includes an application_link. Direct the customer there to finish their selfie verification, then poll again.

Next step

Once application_status is approved, move on to Create a card.

Was this page helpful?