# Core Write Methods

#### createCard

Issues a new virtual or physical card. The payload includes cardholder KYC data, spend controls, and optional metadata used for internal correlation. The exact KYC fields accepted may vary by provider, but the SDK normalizes the top-level shape.

```
const card = await cardClient.createCard({
  cardType: "virtual",
  customerType: "Consumer",
  preferredCardName: "ALICE TEST",
  spendLimit: 1000,
  expiryDate: "2029-12-31",
  kyc: {
    firstName: "Alice",
    lastName: "Test",
    dob: "1990-01-01",
    residentialAddress: "1 Main St, San Francisco, CA",
    idDocumentType: "passport",
    idDocumentNumber: "X1234567",
  },
  meta: {
    clientId: "user-123",
    email: "alice@example.com",
    otpPhoneNumber: {
      dialCode: "1",
      phoneNumber: "4155550000",
    },
  },
});
```

The returned `card` object contains the provider-assigned card ID, masked PAN, status, and the metadata you supplied.

***

#### setFreeze

Toggles the frozen state of an issued card. When frozen, all authorization attempts on the card are declined. Pass `true` to freeze and `false` to unfreeze.

```
// Freeze
await cardClient.setFreeze("card-id", true);

// Unfreeze
await cardClient.setFreeze("card-id", false);
```

**Note:** Freeze state changes are typically reflected immediately at the network level, but propagation timing is provider-dependent.

***

#### revealCard

Returns the full card PAN, CVV, and expiry for display in a secure UI. The security model around reveal differs by provider — some require an additional OTP step or a short-lived reveal token.

```
const revealed = await cardClient.revealCard("card-id");
// revealed includes: pan, cvv, expiryMonth, expiryYear
```

**Note:** Because this method returns raw card credentials, it must only be called from your backend and the response should be transmitted to the client over a secure, ephemeral channel. Never cache or log the returned values.

***

#### replaceCard

Requests a replacement for a compromised, damaged, or expiring card. The `renewOption` field controls whether the replacement retains the existing card number or issues a new one.

```
await cardClient.replaceCard("card-id", {
  renewOption: "NEW_CARD_NUMBER_WITH_NEW_EXPIRY_DATE",
});
```

Once a replacement is issued, the original card is terminated and will decline all future authorizations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://city-protocol.gitbook.io/docs/software-development-kit/card/core-write-methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.