Create a card

Before you can create a card, you must create a customer and complete KYC verification. The customer's KYC level must be intermediate.

Creating a card involves two steps: submitting an application, then creating the card once the application is approved.

Submit a card application

First, submit a card application using the Create card application endpoint. Include the account ID you saved from step 2 of Card workflow along with the customer details:

Each application request requires the following fields:

Fields	Type	Description
`customer_id`	string	unique identifier for the customer requesting a card
`annual_remuneration`	number	customer’s expected annual inflow in USD
`estimated_monthly_limit`	number	expected monthly card spending in USD
`ip_address`	string	IP address from which the application is submitted

Your request will look like the following:

curl --request POST \
     --url https://api.gravv.xyz/v1/cards/application/new \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
  "annual_remuneration": 120000,
  "estimated_monthly_limit": 200,
  "ip_address": "12.23.31.23"
}
'

You will receive a response confirming that the application was submitted successfully:

{
  "data": {
    "message": "Card application request successful",
    "id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
    "status": true
  },
  "error": null
}

Check application status

After applying, use the Get card application endpoint to check the status. Include the application id in the request:

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

The response includes an application_status field that shows the current state of your application

{
  "data": {
    "id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
    "currency": "USD",
    "network": "visa",
    "application_status": "pending",
    "date_created": "2025-11-14T13:46:43.511134+01:00",
    "date_updated": "2025-11-14T13:46:43.511134+01:00",
    "address": {
      "street": "Palo Alto Line 1",
      "city": "Palo Alto City",
      "state": "California",
      "postal_code": "01023",
      "country_iso_code": "US"
    }
  },
  "error": null
}
```

Application status values

The application_status field defaults to pending and can also have the following values:

Status	Description
pending	application is under review
approved	the application is approved, and you can now create the card
needs_information	additional information is required to process the application
needs_verification	selfie verification is required to complete intermediate KYC
manual_review	application requires manual review by the compliance team
denied	application rejected
locked	application locked due to security concerns
canceled	application canceled

Complete KYC verification

When application_status is needs_verification, the response includes a application_link field. The needs_verification status occurs because the required intermediate KYC level includes selfie verification. Direct the customer to the verification_link to complete their identity verification. Once verification is complete, recheck the application status:

{
  "data": {
    "id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
    "currency": "USD",
    "network": "visa",
    "application_status": "needs_verification",
    "application_link": "https://verify.gravv.xyz/selfie/abc123xyz",
    "date_created": "2025-11-14T13:46:43.511134+01:00",
    "date_updated": "2025-11-14T13:46:43.511134+01:00",
    "address": {
      "street": "Palo Alto Line 1",
      "city": "Palo Alto City",
      "state": "California",
      "postal_code": "01023",
      "country_iso_code": "US"
    }
  },
  "error": null
}
```

Create the card

Once the application is approved, create the card using the Create card endpoint. Include the customer id, card limit, name on card, and the same application details:

curl --request POST \
     --url https://api.gravv.xyz/v1/cards \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
  "card_limit": 50,
  "name_on_card": "Misoma Abayeh",
  "annual_renumeration": 120000,
  "estimated_monthly_limit": 10000,
  "ip_address": "12.23.31.23"
}
'

The endpoint returns a 200 status code when the card is successfully created.

Spending controls

Spending controls help you manage risk and prevent unauthorized or excessive spending. You can only set these controls when creating the card. The following are the available spending controls:

Card limit: Maximum amount allowed per transaction
Estimated monthly limit: Total spending allowed within a calendar month

Card issuance timeframe

Card creation is instant, but you must complete KYC verification first. The overall timeframe depends on how fast you can complete the verification process.