Create a card

Before you can create a card, you must create a customer and complete Know Your Customer (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. Each card creation request requires the following fields:

Field	Type	Description
customer_id	string	unique identifier for the customer
card_limit	number	maximum spending limit on the card in USD
name_on_card	string	name to be printed on the card
card_type	string	type of card to create: `virtual` or `physical`

Create a virtual card

To create a virtual card, your request body should look like this:

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",
  "card_type": "virtual"
}
'

Create a physical card

Physical cards require a shipping address. Include the shipping_address field with the customer's delivery 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_type": "physical",
  "card_limit": 50,
  "name_on_card": "Ndifreke Jacob",
  "shipping_address": {
    "address_line1": "201 Allen St",
    "city": "New York",
    "state": "New York",
    "postal_code": "10002",
    "country_code": "US",
    "phone_number": "12125550123",
    "method": "standard"
  }
}
'

The shipping_address object requires the following fields:

Field	Type	Description
address_line1	string	street address
address_line2	string	apartment, suite, or unit number (optional)
city	string	city name
state	string	state or region (optional)
postal_code	string	postal or ZIP code
country_code	string	two-letter country code
phone_number	string	contact phone number
method	string	shipping method

For more information on the countries supported for physical card shipping and the available shipping methods, see Physical card shipping.

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

Note: You must verify the validity of every address used for physical card delivery before submitting the request. Invalid addresses will result in failed deliveries and additional costs.

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.

For more information on all card endpoints, see Cards.