---
title: "Create card"
description: "Create a new card for a customer."
protocol: rest
method: POST
endpoint: "/v1/cards"
baseUrl: "https://api.gravv.xyz"
group: "Cards"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Create card

<Endpoint method="POST" path="/v1/cards" />

Create a new card for a customer.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  Required for POST requests. Reuse the key only when retrying the same operation with an identical payload.
</ParamField>

## Request Body

<ParamField name="customer_id" body="customer_id" type="string" required>
  ID of the customer to create a card for
</ParamField>

<ParamField name="card_limit" body="card_limit" type="number" required>
  Maximum spending limit on the card
</ParamField>

<ParamField name="name_on_card" body="name_on_card" type="string" required>
  Name to be printed on the card
</ParamField>

<ParamField name="card_type" body="card_type" type="string" required>
  Type of card to create

  Possible values: `virtual`, `physical`
</ParamField>

<ParamField name="shipping_address" body="shipping_address" type="object">
  The shipping address for delivering a physical card. Provide this field only when the card type is physical.

  <Expandable title="properties">
    <ParamField name="address_line1" body="shipping_address.address_line1" type="string" required>
    </ParamField>

    <ParamField name="address_line2" body="shipping_address.address_line2" type="string">
    </ParamField>

    <ParamField name="city" body="shipping_address.city" type="string" required>
    </ParamField>

    <ParamField name="state" body="shipping_address.state" type="string">
    </ParamField>

    <ParamField name="postal_code" body="shipping_address.postal_code" type="string" required>
    </ParamField>

    <ParamField name="country_code" body="shipping_address.country_code" type="string" required>
    </ParamField>

    <ParamField name="phone_number" body="shipping_address.phone_number" type="string" required>
    </ParamField>

    <ParamField name="method" body="shipping_address.method" type="string" required>
      Shipping method

      Possible values: `standard`, `express`, `international`, `apc`, `uspsInternational`, `overnight`
    </ParamField>

  </Expandable>
</ParamField>

### Request Examples

<RequestExample>

```json title="CreateVirtualCard"
{
  "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
  "card_type": "virtual",
  "card_limit": 50,
  "name_on_card": "Jane Doe"
}
```

```json title="CreatePhysicalCard"
{
  "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"
  }
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Card creation request accepted |

### 200 response

<ResponseField name="data" type="object">

  <Expandable title="properties">
    <ResponseField name="message" type="string">
      Status message for the card creation request
    </ResponseField>

    <ResponseField name="status" type="boolean">
      Indicates whether the operation was accepted
    </ResponseField>

    <ResponseField name="id" type="string">
      ID of the newly created card
    </ResponseField>

    <ResponseField name="fee_charged" type="boolean">
      Whether the issuance fee was successfully charged
    </ResponseField>

    <ResponseField name="fee_pending" type="boolean">
      True when the fee charge was attempted but failed (for example, insufficient balance) and is queued for retry. The card is still issued.
    </ResponseField>

    <ResponseField name="fee_id" type="string">
      ID of the fee record, present when a fee was charged
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="null">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "message": "Card creation request is processing",
    "status": true,
    "id": "dce0192a-9b3d-440b-9500-33dc9ac8dc20",
    "fee_charged": true,
    "fee_pending": false,
    "fee_id": "fee_abc123"
  },
  "error": null
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**