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:

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:

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:

• Listen for the card webhook events.
• Poll Get card application with the application_id. To list every application for the tenant, use Get card applications.

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:

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.