---
title: Set PIN
slug: apis/cards/apis/set-pin
description: Set a card's initial PIN using PUT /cardmanagement/v1/cards/{id}/pin, required before ATM or PIN-based transactions.
icon: {"apiMethod":"PUT"}
docTags: 
createdAt: 2025-05-07T06:20:49.222Z
---

## Relevant webhooks

For this endpoint be sure you have [registered](docId\:BN5XtgkJogBe-CtwomCbS) for this webhook:

- [Cards.Card.Pin.Set](docId\:paDKAtuyIo5w0YsAexxwl) 

## API reference

Set an initial debit card Personal Identification Number (PIN) for withdrawing funds from an ATM and other uses. To initially set a card PIN, the card must be created, but does not need to be activated. The card's `isPinSet` has a value of `false`. Once the PIN has been created, this API can also be called to update the PIN.

:::ApiMethodV2
```json
{
  "name": "Endpoint: /cardmanagement/v1/cards/{id}/pin",
  "method": "PUT",
  "url": "https://sandbox.crbcos.com/cardmanagement/v1/cards/{id}/pin",
  "description": "",
  "tab": "examples",
  "examples": {
    "languages": [
      {
        "id": "hIyb6HxBZBiF03IHcJXah",
        "language": "curl",
        "code": "curl --location --globoff --request PUT 'https://sandbox.crbcos.com/cardmanagement/v1/cards/{id}/pin?id=8c6a53e0-83ad-4b76-b446-b300006a3e6a' \\\n--data '{\n  \"pin\": \"1534\"\n}",
        "customLabel": ""
      },
      {
        "id": "x_MG1v6sKtmoDOR0tOu8n",
        "language": "nodejs",
        "code": "var https = require('follow-redirects').https;\nvar fs = require('fs');\n\nvar options = {\n  'method': 'PUT',\n  'hostname': 'sandbox.crbcos.com',\n  'path': '/cardmanagement/v1/cards/{id}/pin?id=8c6a53e0-83ad-4b76-b446-b300006a3e6a',\n  'headers': {\n  },\n  'maxRedirects': 20\n};\n\nvar req = https.request(options, function (res) {\n  var chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function (chunk) {\n    var body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n\n  res.on(\"error\", function (error) {\n    console.error(error);\n  });\n});\n\nvar postData =  \"{\\r\\n  \\\"pin\\\": \\\"1534\\\"\\r\\n}\\r\\n\\r\\n\";\n\nreq.write(postData);\n\nreq.end();",
        "customLabel": ""
      },
      {
        "id": "BjNj18w3ge1Dp8xYETFNQ",
        "language": "python",
        "code": "import requests\n\nurl = \"https://sandbox.crbcos.com/cardmanagement/v1/cards/{id}/pin?id=8c6a53e0-83ad-4b76-b446-b300006a3e6a\"\n\npayload = \"{\\r\\n  \\\"pin\\\": \\\"1534\\\"\\r\\n}\\r\\n\\r\\n\"\nheaders = {\n\n}\n\nresponse = requests.request(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
        "customLabel": ""
      },
      {
        "id": "7vCzq4QiptwpYN3fJ5pbc",
        "language": "ruby",
        "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://sandbox.crbcos.com/cardmanagement/v1/cards/{id}/pin?id=8c6a53e0-83ad-4b76-b446-b300006a3e6a\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Put.new(url)\nrequest.body = \"{\\r\\n  \\\"pin\\\": \\\"1534\\\"\\r\\n}\\r\\n\\r\\n\"\n\nresponse = https.request(request)\nputs response.read_body\n",
        "customLabel": ""
      },
      {
        "id": "r8rtjGLzdnx9k067fg8SY",
        "language": "go",
        "code": "package main\n\nimport (\n  \"fmt\"\n  \"strings\"\n  \"net/http\"\n  \"io\"\n)\n\nfunc main() {\n\n  url := \"https://sandbox.crbcos.com/cardmanagement/v1/cards/{id}/pin?id=8c6a53e0-83ad-4b76-b446-b300006a3e6a\"\n  method := \"PUT\"\n\n  payload := strings.NewReader(`{`+\"\n\"+`\n  \"pin\": \"1534\"`+\"\n\"+`\n}`+\"\n\"+`\n`+\"\n\"+`\n`)\n\n  client := &http.Client {\n  }\n  req, err := http.NewRequest(method, url, payload)\n\n  if err != nil {\n    fmt.Println(err)\n    return\n  }\n  res, err := client.Do(req)\n  if err != nil {\n    fmt.Println(err)\n    return\n  }\n  defer res.Body.Close()\n\n  body, err := io.ReadAll(res.Body)\n  if err != nil {\n    fmt.Println(err)\n    return\n  }\n  fmt.Println(string(body))\n}",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "hIyb6HxBZBiF03IHcJXah"
  },
  "results": {
    "languages": [
      {
        "id": "kcRcUaYhEpL8DHVEgmP34",
        "language": "200",
        "code": "{\n    \"id\": \"8c6a53e0-83ad-4b76-b446-b300006a3e6a\",\n    \"productId\": \"57146944-b145-4326-884d-b2f700ecf688\",\n    \"partnerId\": \"19222b81-0e1e-452d-a842-b2f1011c16f3\",\n    \"processorCardId\": \"827277613081398\",\n    \"accountNumber\": \"158560897007\",\n    \"status\": \"Active\",\n    \"statusReasonCode\": \"NotSet\",\n    \"processorCardStatus\": \"B\",\n    \"firstName\": \"Daly\",\n    \"lastName\": \"Khol\",\n    \"shippingAddress\": {\n        \"street1\": \"1 Roshar Ave\",\n        \"city\": \"Roshar\",\n        \"state\": \"NY\",\n        \"postalCode\": \"10001\",\n        \"countryCode\": \"US\"\n    },\n    \"billingAddress\": {\n        \"street1\": \"1 Roshar Ave\",\n        \"city\": \"Roshar\",\n        \"state\": \"NY\",\n        \"postalCode\": \"10001\",\n        \"countryCode\": \"US\"\n    },\n    \"phone\": {\n        \"phoneType\": \"Home\",\n        \"phoneNumber\": \"7185551234\"\n    },\n    \"emailAddress\": \"dkhol@gmail.com\",\n    \"nameOnCard\": \"Daly Khol\",\n    \"panLastFour\": \"4558\",\n    \"isPinSet\": true,\n    \"expirationDate\": \"2028-06-18\",\n    \"adminBlocked\": false,\n    \"fraudSuspect\": false,\n    \"configurationId\": \"b2251a28-c218-4e2e-a787-b2f700ef0ecd\",\n    \"category\": \"Debit\",\n    \"paymentInstrument\": \"PhysicalCombo\",\n    \"processor\": \"P1\",\n    \"shippingType\": \"Normal\",\n    \"orderStatus\": \"Completed\",\n    \"replacementStatus\": \"NotApplicable\",\n    \"customerId\": \"e2599a17-d1e2-476c-9672-b2ff008fa575\",\n    \"clientIdentifier\": \"b06ab5cc-553a-4fe4-ad78-751b5ff81f00\",\n    \"processorCustomerId\": \"0CIF7L2973U98WT4E652\",\n    \"createdAt\": \"2025-06-18T02:26:49.617-04:00\",\n    \"initialActivation\": \"2025-06-18T00:00:00-04:00\",\n    \"activatedAt\": \"2025-06-18T02:27:58.813-04:00\",\n    \"lastModifiedAt\": \"2025-06-18T06:18:02.7043417-04:00\"\n}",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "kcRcUaYhEpL8DHVEgmP34"
  },
  "request": {
    "pathParameters": [
      {
        "name": "id",
        "kind": "required",
        "type": "string",
        "description": "GUID format card ID in the Cross River system, which is the id attribute value of the response to Create a card. This is not the number that appears on the card.",
        "": "required"
      }
    ],
    "queryParameters": [],
    "headerParameters": [],
    "bodyDataParameters": [
      {
        "name": "pin",
        "kind": "required",
        "type": "string",
        "description": "4-digit personal identification number associated with the card for verification purposes during purchase or cash withdrawal transactions.",
        "": "pin"
      }
    ],
    "formDataParameters": []
  },
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  },
  "response": [
    {
      "name": "id",
      "kind": "optional",
      "type": "string",
      "description": "GUID format card ID in the Cross River system, which is the id attribute value of the response to Create a card. This is not the number that appears on the card."
    },
    {
      "name": "productId",
      "kind": "optional",
      "type": "string",
      "description": "Product ID of the cardholder deposit account. This ID is in the GUID format.",
      "children": []
    },
    {
      "name": "partnerId",
      "kind": "optional",
      "type": "string",
      "description": "Your unique ID in the Cross River system. This ID is in GUID format.",
      "children": []
    },
    {
      "name": "processorCardId",
      "kind": "optional",
      "type": "string",
      "description": "Card processor's unique identifier",
      "children": []
    },
    {
      "name": "accountNumber",
      "kind": "optional",
      "type": "string",
      "description": "Deposit account number associated with the card",
      "children": []
    },
    {
      "name": "status",
      "kind": "optional",
      "type": "string",
      "description": "Card activation status:\n- Unactivated\n- Active\n- Suspended\n- Closed",
      "children": []
    },
    {
      "name": "statusReasonCode",
      "kind": "optional",
      "type": "string",
      "description": "Reason for the card status:\n- NotSet\n- Damaged\n- Expired\n- Lost\n- FraudCompromised\n- Return\n- NewEnrollment\n- Stolen\n- AdminBlocked",
      "children": []
    },
    {
      "name": "processorCardStatus",
      "kind": "optional",
      "type": "string",
      "description": "Status of the card in the processor's system",
      "children": []
    },
    {
      "name": "firstName",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder first name",
      "children": []
    },
    {
      "name": "middleName",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder middle name",
      "children": []
    },
    {
      "name": "lastName",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder last name",
      "children": []
    },
    {
      "name": "suffix",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder name suffix",
      "children": []
    },
    {
      "name": "birthDate",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder birthdate",
      "children": []
    },
    {
      "name": "shippingAddress",
      "kind": "optional",
      "type": "Object",
      "description": "Address where a physical card is sent",
      "children": [
        {
          "name": "street1",
          "kind": "optional",
          "type": "string",
          "description": "Primary location details of cardholder. This needs to be a street name and house or building number. Do not enter a PO box. Do not use any punctuation. 60 characters maximum."
        },
        {
          "name": "street2",
          "kind": "optional",
          "type": "string",
          "description": "Additional field for address information"
        },
        {
          "name": "city ",
          "kind": "optional",
          "type": "string",
          "description": "Name of the cardholder's city"
        },
        {
          "name": "state",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder's 2-character state code"
        },
        {
          "name": "postalCode",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder's US postal (ZIP) code"
        },
        {
          "name": "countryCode",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder 2-character ISO country code"
        }
      ]
    },
    {
      "name": "billingAddress",
      "kind": "optional",
      "type": "Object",
      "description": "Address where the credit card bills are sent",
      "children": [
        {
          "name": "street1",
          "kind": "optional",
          "type": "string",
          "description": "Primary location details of cardholder. This needs to be a street name and house or building number. Do not enter a PO box. Do not use any punctuation. 60 characters maximum."
        },
        {
          "name": "street2",
          "kind": "optional",
          "type": "string",
          "description": "Additional field for address information"
        },
        {
          "name": "city",
          "kind": "optional",
          "type": "string",
          "description": "Name of the cardholder's city"
        },
        {
          "name": "state",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder's 2-character state code"
        },
        {
          "name": "postalCode",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder's US postal (ZIP) code"
        },
        {
          "name": "countryCode",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder 2-character ISO country code"
        }
      ]
    },
    {
      "name": "phone",
      "kind": "optional",
      "type": "Object",
      "description": "Information about the cardholder's phone (type and number)",
      "children": [
        {
          "name": "phoneType",
          "kind": "optional",
          "type": "string",
          "description": "Phone number is for:\n- Home\n- Mobile\n- Work"
        },
        {
          "name": "phoneNumber",
          "kind": "optional",
          "type": "string",
          "description": "Cardholder phone number. 10-15 digits, no spaces or other characters."
        }
      ]
    },
    {
      "name": "emailAddress",
      "kind": "optional",
      "type": "string",
      "description": "Cardholder email address",
      "children": []
    },
    {
      "name": "nameOnCard",
      "kind": "optional",
      "type": "string",
      "description": "Full cardholder name as written on card",
      "children": []
    },
    {
      "name": "companyNameOnCard",
      "kind": "optional",
      "type": "string",
      "description": "If defined, the name of the cardholder company",
      "children": []
    },
    {
      "name": "panLastFour",
      "kind": "optional",
      "type": "string",
      "description": "Last 4 digits of the PAN, the primary account number, which appears on the physical card",
      "children": []
    },
    {
      "name": "previousCardId",
      "kind": "optional",
      "type": "string",
      "description": "ID of the previous card if the current card is a replacement",
      "children": []
    },
    {
      "name": "isPinSet",
      "kind": "optional",
      "type": "Boolean",
      "description": "True if the PIN number is set for the card, otherwise false.",
      "children": []
    },
    {
      "name": "expirationDate",
      "kind": "optional",
      "type": "string",
      "description": "Card expiration date. Format: YYYY-MM-DD",
      "children": []
    },
    {
      "name": "adminBlocked",
      "kind": "optional",
      "type": "Boolean",
      "description": "True if the card has been blocked by the administrator, otherwise false. This block cannot be removed.",
      "children": []
    },
    {
      "name": "fraudSuspect",
      "kind": "optional",
      "type": "Boolean",
      "description": "True, if the card was blocked by the processor due to potential fraud, otherwise false.",
      "children": []
    },
    {
      "name": "configurationId",
      "kind": "optional",
      "type": "string",
      "description": "Unique ID for the card configuration profile the card is based on. You get this ID from Cross River. This ID is in GUID format.",
      "children": []
    },
    {
      "name": "category",
      "kind": "optional",
      "type": "string",
      "description": "Type of card:\n- Debit\n- Credit\n- Prepaid",
      "children": []
    },
    {
      "name": "paymentInstrument",
      "kind": "optional",
      "type": "string",
      "description": "Card payment instrument type:\n- PhysicalMSR\n- PhysicalICC\n- PhysicalContactless\n- PhysicalCombo\n- VirtualPan",
      "children": []
    },
    {
      "name": "processor",
      "kind": "optional",
      "type": "string",
      "description": "The name of the card processor:\n- i2c\n- P1",
      "children": []
    },
    {
      "name": "shippingType",
      "kind": "optional",
      "type": "string",
      "description": "How the card is shipped:\n- Normal\n- Expedited",
      "children": []
    },
    {
      "name": "orderStatus",
      "kind": "optional",
      "type": "string",
      "description": "Status of the card order:\n- OrderPending (0)\n- Completed (1)\n- Failed (2)\n- Authorizing (3)\n- AuthorizationFailed (4)\n- AuthorizationCompleted (5)",
      "children": []
    },
    {
      "name": "replacementStatus",
      "kind": "optional",
      "type": "string",
      "description": "Indicates whether the card is a replacement card and the status of the replacement:\n- NotApplicable\n- Pending\n- Completed\n- Failed",
      "children": []
    },
    {
      "name": "customerId",
      "kind": "optional",
      "type": "string",
      "description": "The unique Cross River ID assigned to a customer when the customer record is created. You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.\nThe ID is in GUID format.",
      "children": []
    },
    {
      "name": "clientIdentifier",
      "kind": "optional",
      "type": "string",
      "description": "Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.",
      "children": []
    },
    {
      "name": "processorCustomerId",
      "kind": "optional",
      "type": "string",
      "description": "Processor's Unique ID for the cardholder",
      "children": []
    },
    {
      "name": "createdAt",
      "kind": "optional",
      "type": "string",
      "description": "Date and time when the card was created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]",
      "children": []
    },
    {
      "name": "suspendedAt",
      "kind": "optional",
      "type": "string",
      "description": "Date and time when the card was suspended. If not suspended, null. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]",
      "children": []
    },
    {
      "name": "closedAt",
      "kind": "optional",
      "type": "string",
      "description": "Date and time the card was closed. If not closed, null. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]",
      "children": []
    },
    {
      "name": "initialActivation",
      "kind": "optional",
      "type": "string",
      "description": "Date the card was activated. The time is set to midnight at the start of that day.",
      "children": []
    },
    {
      "name": "activatedAt",
      "kind": "optional",
      "type": "string",
      "description": "Exact date and time the card was activated. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]",
      "children": []
    },
    {
      "name": "openedAt",
      "kind": "optional",
      "type": "string",
      "description": "Null",
      "children": []
    },
    {
      "name": "lastModifiedAt",
      "kind": "optional",
      "type": "string",
      "description": "Internal Cross River value. Date and time the database entry was last modified. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]",
      "children": []
    }
  ],
  "hasTryItOut": false,
  "autoGeneratedAnchorSlug": "endpoint-cardmanagementv1cardsidpin",
  "legacyHash": "x--SPHGtvjW6sA3Mdft10"
}
```
:::