--- title: "Set PIN Code" source_url: https://docs.rapyd.net/en/set-pin-code.html lang: en --- # Set PIN Code Set the PIN code for an issued card. This method triggers the [Issued Card PIN Set Webhook](https://docs.rapyd.net/en/issued-card-pin-set-webhook.md "Issued Card PIN Set Webhook"). > **Note:** > > - In the sandbox, you can set any number other than **1111**. > - Clients with [PCI](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_pci "Payment Card Industry") certification can handle personal identifying information for cards, such as card number. > - PINs are relevant to physical cards. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - For information about unauthorized request (401) and other authentication errors, see [Issued Card Errors](https://docs.rapyd.net/en/issued-card-errors.md "Issued Card Errors"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - card - Card number or card ID. - - new_pin - PIN code. Numeric string. ### Response Parameters - - activated_at - Time that the card was activated, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - assigned_at - Time that the card was assigned to a cardholder, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - blocked_reason - Reason for blocking the card. One of the following: - **blocked_reversible** - **canceled** - **compliance** - **locked_incorrect_pin** - **migrated** - **none** - **other** - **reissued** - **suspected_fraud** - - blocked_reason_code - Three letter code for the reason for blocking the card. One of the following values: - **CAN** - Canceled - **COM** - Compliance - **LOC** - Locked due to incorrect PIN - **LOS** - Lost - **MIG** - Migrated - **OTH** - Other - **REI** - Reissued - **SFR** - Suspected fraud - **STO** - Stolen - - blocked_reason_desc - Short description of the blocking reason. - - card_id - ID of the card. String starting with **card_**. - - card_program - ID of the card program. String starting with **cardprog_**. - - card_status_initiator - The initiator that asked for the card status update. One of the following three letter codes: - **CAH** - Cardholder - **COM** -Compliance operation - **DET** - Detect - **IGW** - Issuing gateway - **ISM** - Issuing merchant - **RSK** - Risk operation - **PRO** - Protect - - card_status_initiator_desc - Description of the `card_status_initiator` code. - - card_tracking_id - ID of the card for purposes of tracking. - - country_iso_alpha_2 - The country where the card is issued. Two-letter ISO 3166-1 ALPHA-2 code. - - created_at - Time of creation of the issued card object, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - ewallet_contact - Describes the wallet contact that the card is assigned to. String starting with **cont_**. For details about the fields of the 'contact' object, see [Add Contact to Wallet](https://docs.rapyd.net/en/add-contact-to-wallet.md "Add Contact to Wallet"). - - id - ID of the issued card object. String starting with **ci_**. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - public_details - Status of the card. One of the following: - `bin` - Bank ID number (BIN). - `last4` - Last 4 digits of the card. - `sub_bin` - Sub-BIN. - `expiration` - Expiration date as 4 digits. - - status - Status of the card. One of the following: - **ACT** - Active. - **BLO** - Blocked. - **IMP** - Imported in bulk, but not yet personalized. - **INA** - Inactive. ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { card = "card_f8dd3aa099444e1c80cc5a06de38b165", new_pin = "7777", }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/issuing/cards/pin", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('../../../../Utilities/JS/utilities').makeRequest; async function main() { try { const body = { card: 'card_f8dd3aa099444e1c80cc5a06de38b165', new_pin: '7777' }; const result = await makeRequest('POST', '/v1/issuing/cards/pin', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php "card_f8dd3aa099444e1c80cc5a06de38b165", "new_pin" => "7777" ]; try { $object = make_request('post', '/v1/issuing/cards/pin', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request body = { "card": "card_f8dd3aa099444e1c80cc5a06de38b165", "new_pin": "7777" } results = make_request(method='post', path=f'/v1/issuing/cards/pin', body=body) pprint(results) ``` - /v1/issuing/cards/pin - Set PIN Code by Card ID - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/issuing/cards/pin' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "card": "card_a5429bdb6c529008ed5b409e5929b606", "new_pin": "7788" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "a7a01b7d-5343-4f3e-a4f4-a695646af5a4" }, "data": { "id": "ci_0b164db21d9c513e2b9d2dac77a3014a", "ewallet_contact": { "id": "cont_cb60ec28c2f0bdfc621cfc21270c20ce", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "personal", "phone_number": "+14155551237", "email": "", "identification_type": "", "identification_number": "", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": "2000-12-15", "country": "NG", "nationality": null, "address": { "id": "address_8dc883799f2fcb5adb92bf77b6bc85b7", "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "", "country": "", "zip": "", "phone_number": "", "metadata": {}, "canton": "", "district": "", "created_at": 1755679320 }, "ewallet": "ewallet_3801e782955b29955445586a2405a5db", "created_at": 1612104554, "metadata": {}, "business_details": null, "compliance_profile": 0, "verification_status": "not verified", "send_notifications": false, "mothers_name": "" }, "status": "BLO", "card_id": "card_a5429bdb6c529008ed5b409e5929b606", "assigned_at": 1760012427, "activated_at": 1760012450, "metadata": {}, "country_iso_alpha_2": "BR", "created_at": 1760012427, "blocked_reason": "other", "card_tracking_id": null, "card_program": "cardprog_b027c85a66ebebb2e094bca626d5ae97", "public_details": { "bin": "517413", "last4": "3157", "sub_bin": "76", "expiration": "1028" } } } ``` - Set PIN Code by Card Number - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/issuing/cards/pin' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "card": "5348330641217634", "new_pin": "7788" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "7d438fac-3805-4f90-94a5-e3ea774ba301" }, "data": { "id": "ci_d4fa9d7f43819d92c66125e2a7579fe6", "ewallet_contact": { "id": "cont_cb60ec28c2f0bdfc621cfc21270c20ce", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "personal", "phone_number": "+14155551237", "email": "", "identification_type": "", "identification_number": "", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": "2000-12-15", "country": "NG", "nationality": null, "address": { "id": "address_8dc883799f2fcb5adb92bf77b6bc85b7", "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "", "country": "", "zip": "", "phone_number": "", "metadata": {}, "canton": "", "district": "", "created_at": 1755679320 }, "ewallet": "ewallet_3801e782955b29955445586a2405a5db", "created_at": 1612104554, "metadata": {}, "business_details": null, "compliance_profile": 0, "verification_status": "not verified", "send_notifications": false, "mothers_name": "" }, "status": "ACT", "card_id": "card_0393b8437d759c5fb491d427b0000322", "assigned_at": 1760011681, "activated_at": 1760012238, "metadata": {}, "country_iso_alpha_2": "BR", "created_at": 1760011681, "blocked_reason": "none", "card_tracking_id": null, "card_program": "cardprog_b027c85a66ebebb2e094bca626d5ae97", "public_details": { "bin": "534833", "last4": "7634", "sub_bin": "64", "expiration": "1028" } } } ``` - Bad Request - PIN Not 4 Digits - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/issuing/cards/pin' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "card": "card_0393b8437d759c5fb491d427b0000322", "new_pin": "79889" }' ``` - ```json { "status": { "error_code": "ERROR_ISSUED_CARD_PIN_FORMAT_NOT_VALID", "status": "ERROR", "message": "The request tried to set a PIN for an issued card, but the format of the PIN was not valid. The request was rejected. Corrective action: Set 'new_pin' to a numeric string.", "response_code": "ERROR_ISSUED_CARD_PIN_FORMAT_NOT_VALID", "operation_id": "4a7df207-e562-4fe7-9f18-7c5a11ee1fea" } } ``` - Bad Request - Card Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/issuing/cards/pin' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "card": "card_0393b8437d759c5fb491d427b000032", "new_pin": "7788" }' ``` - ```json { "status": { "error_code": "ERROR_CARD_NOT_FOUND", "status": "ERROR", "message": "The request attempted to retrieve data on a non-existent card or a card that is not linked to your account. The request was rejected. Corrective action: Check the card token and rerun the request with the correct card details.", "response_code": "ERROR_CARD_NOT_FOUND", "operation_id": "fa228af7-d930-4789-bd32-3d58f089e042" } } ```