Create a card

📘 Coming from accounts? Read this first

Cards aren't created directly the way accounts are. A card needs an approved card application behind it. In production you create that application by activating the card feature, not by calling Create card first. See Create a card application for that flow. This page covers the final step: turning an approved application into a card.

Creating a card is a two-step flow:

1. Create a card application and wait for it to be approved.
2. Create the card, covered below.

Before you start, the customer must exist, have completed intermediate KYC, and have a card application with application_status of approved.

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": "Jane Doe",
  "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": "Jane Doe",
  "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 accepts 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. Retrieve the new card with Get card to share its details with your customer.

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 once the application is approved. The overall timeframe depends on how fast the customer completes KYC and how long application review takes.