> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PINs

> Use the PINs API to create, update, or reveal a personal identification number (PIN) for a card.

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

Use the `/pins` endpoint to create, update, or reveal a personal identification number (PIN) for a card.

<h2 id="post_pins_controltoken">
  Create PIN control token
</h2>

**Action:** `POST`\
**Endpoint:** `/pins/controltoken`

{/* <EndpointCard
title="Creates a new control token for a PIN"
path="/pins/controltoken"
method="post"
/> */}

Creates a control token necessary when creating or updating a card’s personal identification number (PIN).

Creating, updating, or revealing a card’s PIN is a two-step process. You must first create the control token that is required to create the PIN, and then you create, update, or reveal the PIN itself.

The lifespan of the control token in a production environment is either five minutes or one hour from creation, depending on the token type. If multiple tokens are requested for a single card, only the most recent one is valid. Once redeemed, a token cannot be reused.

<h3 id="_request_body">
  Request body
</h3>

| Fields                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token<br /><br />string<br /><br />Required        | The unique identifier of the card for which you want to generate a control token.<br /><br />**Allowable Values:**<br /><br />1–36 chars<br /><br />Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a specific user.                                                                                                                                                        |
| controltoken\_type<br /><br />string<br /><br />Optional | Specifies the type of action completed by this request.<br /><br />**WARNING:** Sending a request to this endpoint with a `REVEAL_PIN` control token requires PCI DSS compliance.<br /><br />The lifespan of the control token depends on the token type:<br /><br />- **SET\_PIN:** 60 minutes<br />- **REVEAL\_PIN:** 5 minutes<br /><br />**Allowable Values:**<br /><br />`SET_PIN`, `REVEAL_PIN` |

<h3 id="_sample_request_body">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "card_token": "my_card_01",
  "controltoken_type": "SET_PIN"
}
```

<h3 id="_response_body">
  Response body
</h3>

| Fields                                               | Description                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| control\_token<br /><br />string<br /><br />Returned | Unique value generated as a result of issuing a `POST` request to the `/pins/controltoken` endpoint. This value cannot be updated.<br /><br />**Allowable Values:**<br /><br />1-36 chars |

<h3 id="_sample_response_body">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "control_token": "b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc"
}
```

<h2 id="put_pins">
  Create or update PIN
</h2>

**Action:** `PUT`\
**Endpoint:** `/pins`

{/* <EndpointCard
title="Updates the PIN control token"
path="/pins"
method="put"
/> */}

Creates or updates a personal identification number (PIN) for an existing card. Although cardholders might choose a four-, five-, or six-digit PIN if they set their PIN at an automated teller machine, they can only set a four-digit PIN using Marqeta’s Set PIN widget or the create or update PIN endpoint (`PUT /pins`). Cardholders can update their PIN through the API regardless of its length, but the new PIN value they choose must contain four digits.

If you want to manage a card’s PIN, first create a new control token for the card by sending a `POST` request to `/pins/controltoken`, and then use that token to update the PIN. You must create a card before you can manage a PIN.

Unless PIN reveal functionality has been enabled for your program, you cannot retrieve a PIN that has previously been created. If the PIN has been forgotten, you must either update the card’s PIN or create a new card and PIN.

If you have enabled PIN reveal functionality for your program, you can send a `POST` request to the `/pins/reveal` endpoint to retrieve an existing PIN. See [Reveal PIN](/core-api/pins/#reveal_pins) on this page for details.

<Danger>
  **Warning**\
  Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
</Danger>

<h3 id="_request_body_2">
  Request body
</h3>

| Fields                                               | Description                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| control\_token<br /><br />string<br /><br />Required | Unique value generated as a result of issuing a `POST` request to the `/pins/controltoken` endpoint. This value cannot be updated.<br /><br />**Allowable Values:**<br /><br />1–36 chars |
| pin<br /><br />string<br /><br />Required            | Four-digit number to associate with the card.<br /><br />**Allowable Values:**<br /><br />4 chars                                                                                         |

<h3 id="_sample_request_body_2">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "control_token": "b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc",
  "pin": "5678"
}
```

<h2 id="reveal_pins">
  Reveal PIN
</h2>

**Action:** `POST`\
**Endpoint:** `/pins/reveal`

{/* <EndpointCard
title="Updates the PIN-reveal control token"
path="/pins/reveal"
method="post"
/> */}

Reveals the personal identification number (PIN) of an existing, active card. Be aware that while a cardholder can only set a four-digit PIN using the Marqeta Set PIN widget or `PUT /pins` API, you may see a four-, five-, or six-digit PIN in cases where your cardholders have set a new PIN at an automated teller machine.

<Danger>
  **Warning**\
  Only use this endpoint to access a PIN in order to reveal it to its cardholder. Do not use this endpoint for the purpose of storing a PIN at any location.
</Danger>

Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.

If you want to update a card’s PIN instead, send a `PUT` request to the `/pins` endpoint. See [Create or Update PIN](/core-api/pins/#put_pins) on this page for details.

Revealing a card’s PIN is a two-step process. You must first create a new control token for the card by sending a `POST` request to `/pins/controltoken`, and then use that token to reveal the PIN.

<h3 id="_request_body_3">
  Request body
</h3>

| Fields                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cardholder\_verification\_method<br /><br />string<br /><br />Required | The supplemental method used to verify the cardholder’s identity before revealing the card’s personal identification number (PIN).<br /><br />The possible cardholder verification methods are:<br /><br />- **BIOMETRIC\_FACE:** In-app authentication via facial recognition<br />- **BIOMETRIC\_FINGERPRINT:** In-app authentication via biometric fingerprint<br />- **EXP\_CVV:** In-app authentication by entering the card’s expiration date and card verification value (CVV)<br />- **LOGIN:** In-app authentication by re-entering the app password<br />- **OTP:** Two-factor authentication involving a one-time password (OTP)<br />- **OTP\_CVV:** Two-factor authentication involving the card’s CVV and an OTP<br />- **OTHER:** Authentication that relies on other secure methods<br /><br />**Allowable Values:**<br /><br />`BIOMETRIC_FACE`, `BIOMETRIC_FINGERPRINT`, `LOGIN`, `EXP_CVV`, `OTP_CVV`, `OTP`, `OTHER` |
| control\_token<br /><br />string<br /><br />Required                   | Unique value generated as a result of issuing a `POST` request to the `/pins/controltoken` endpoint. This value cannot be updated.<br /><br />**Allowable Values:**<br /><br />1–36 chars                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

<h3 id="_sample_request_body_3">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "control_token": "b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc",
  "cardholder_verification_method": "BIOMETRIC_FINGERPRINT"
}
```

<h3 id="_sample_response_body_2">
  Sample response body
</h3>

There is no response for a call made to the `POST /pins/reveal` endpoint, other than a `204 PIN was successfully revealed` message.

```json JSON lines wrap theme={null}
HTTP response code 204
```