> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/pin-management/es/integrar-la-api-d1/referencia-de-la-api-d1/api-saliente-desde-d1/api-de-gestion-de-pin.md).
# API de gestión de PIN
[Descargar D1-Public-OUT-v1-PIN-Management.yaml](https://openapi.gitbook.com/o/fwy1mtbRONGA2YDKDBr0/spec/D1-Public-OUT-v1-PIN-Management.yaml)
## Get Card PIN
> This request is used by D1 to retrieve the PIN value of a physical card.
```json
{"openapi":"3.0.0","info":{"title":"Outbound PIN Management API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"},{"url":"https://YOUR_DOMAIN_NAME","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"GetPinResponseBody":{"description":"The response body to get PIN to be displayed. This value is encrypted using the JWE encryption\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getPinBlock"}}}},"BadRequestOutbound":{"description":"Bad Request, Invalid request URI or header, or unsupported non-standard parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"UnauthorizedOutbound":{"description":"The provided Authorization header is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"ForbiddenForPhysicalCardOutbound":{"description":"Forbidden action, check the state of the linked end user (consumer) or account or card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"NotFoundForPhysicalCardOutbound":{"description":"Resource not found, Unknown issuerId or consumerId or accountId or card id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"InternalServerErrorOutbound":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}}},"schemas":{"getPinBlock":{"required":["type","encryptedPinBlock"],"properties":{"type":{"type":"string","description":"The type of the PIN Block.","enum":["ISO0"]},"encryptedPinBlock":{"type":"string","maxLength":8192,"description":"The value is the encrypted json (cf http://www.json.org/ ) representation of the PIN Block.\n
This value is encrypted using the JWE encryption (please refer to the **[Sensitive Information Encryption](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)\n|Schemas of the PIN Block once decrypted|\n|-------|\n|[PIN Block ISO0](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESISO0)|\n"}},"title":"Get PIN Block","discriminator":{"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/pinblock3DESISO0"}]},"pinblock3DESISO0":{"title":"PIN 3DES ISO0","type":"object","properties":{"pinValue":{"type":"string","maxLength":8192,"description":"The PIN in format ISO0 encrypted under 3DES Key.\n"},"kid":{"type":"string","maxLength":128,"description":"The key label or identifier of the 3DES key used to encrypt the PIN Block.\n"}}},"errorGenericOutbound":{"type":"object","description":"Generic error returned by the APIs.","properties":{"error":{"type":"string","description":"Description of the error."}}}}},"paths":{"/cms/api/v1/issuers/{issuerId}/cards/{cardId}/pin":{"get":{"summary":"Get Card PIN","operationId":"getPIN","responses":{"200":{"$ref":"#/components/responses/GetPinResponseBody"},"400":{"$ref":"#/components/responses/BadRequestOutbound"},"401":{"$ref":"#/components/responses/UnauthorizedOutbound"},"403":{"$ref":"#/components/responses/ForbiddenForPhysicalCardOutbound"},"404":{"$ref":"#/components/responses/NotFoundForPhysicalCardOutbound"},"500":{"$ref":"#/components/responses/InternalServerErrorOutbound"}},"description":"This request is used by D1 to retrieve the PIN value of a physical card."}}}}
```
## Set Card PIN
> This request is used by D1 to push securelly in core banking system the PIN value for a physical card.
```json
{"openapi":"3.0.0","info":{"title":"Outbound PIN Management API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"},{"url":"https://YOUR_DOMAIN_NAME","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"requestBodies":{"SetPinRequestBody":{"description":"Request body for setting the card PIN","content":{"application/json":{"schema":{"type":"object","allOf":[{"$ref":"#/components/schemas/setPinBlock"}]}}}}},"schemas":{"setPinBlock":{"required":["type","encryptedPinBlock"],"properties":{"type":{"type":"string","description":"The type of the PIN Block.","enum":["ISO0","3DES_SECCOS"]},"encryptedPinBlock":{"type":"string","maxLength":8192,"description":"The value is the encrypted json (cf http://www.json.org/ ) representation of the PIN Block.\n
This value is encrypted using the JWE encryption (please refer to the **[Sensitive Information Encryption](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)\n|Schemas of the PIN Block once decrypted|\n|-------|\n|[PIN Block ISO0](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESISO0)|\n|[PIN Block 3DES Seccos](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESSECCOS)|\n"}},"title":"Set PIN Block","discriminator":{"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/pinblock3DESISO0"},{"$ref":"#/components/schemas/pinblock3DESSECCOS"}]},"pinblock3DESISO0":{"title":"PIN 3DES ISO0","type":"object","properties":{"pinValue":{"type":"string","maxLength":8192,"description":"The PIN in format ISO0 encrypted under 3DES Key.\n"},"kid":{"type":"string","maxLength":128,"description":"The key label or identifier of the 3DES key used to encrypt the PIN Block.\n"}}},"pinblock3DESSECCOS":{"title":"PIN 3DES SECCOS","type":"object","properties":{"intdatag":{"type":"string","minLength":20,"maxLength":20,"description":"Identifier used to correlate the call to get Pin Change Counter and the call to set Pin.\n"},"prwDataSet":{"type":"string","pattern":"[0-9A-F]{246}","description":"The data used to compute the PIN Reference Value (PRW) without sensitive data (pan replaced by 00...00).\n"},"prwValue":{"type":"string","maxLength":64,"description":"The PIN Reference Value (PRW).\n"},"prwKid":{"type":"string","maxLength":128,"description":"The key label or identifier of the key used to compute the PIN Reference value\n"},"macValue":{"type":"string","maxLength":16,"description":"The PRW Mac value.\n"},"macKid":{"type":"string","maxLength":128,"description":"The index of the key used to compute the MAC\n"}}},"errorGenericOutbound":{"type":"object","description":"Generic error returned by the APIs.","properties":{"error":{"type":"string","description":"Description of the error."}}}},"responses":{"BadRequestOutbound":{"description":"Bad Request, Invalid request URI or header, or unsupported non-standard parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"UnauthorizedOutbound":{"description":"The provided Authorization header is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"ForbiddenForPhysicalCardOutbound":{"description":"Forbidden action, check the state of the linked end user (consumer) or account or card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"NotFoundForPhysicalCardOutbound":{"description":"Resource not found, Unknown issuerId or consumerId or accountId or card id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"InternalServerErrorOutbound":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}}}},"paths":{"/cms/api/v1/issuers/{issuerId}/cards/{cardId}/pin":{"put":{"summary":"Set Card PIN","operationId":"SetPIN","requestBody":{"$ref":"#/components/requestBodies/SetPinRequestBody"},"responses":{"204":{"description":"PIN set successfuly"},"400":{"$ref":"#/components/responses/BadRequestOutbound"},"401":{"$ref":"#/components/responses/UnauthorizedOutbound"},"403":{"$ref":"#/components/responses/ForbiddenForPhysicalCardOutbound"},"404":{"$ref":"#/components/responses/NotFoundForPhysicalCardOutbound"},"500":{"$ref":"#/components/responses/InternalServerErrorOutbound"}},"description":"This request is used by D1 to push securelly in core banking system the PIN value for a physical card."}}}}
```
## Get PIN Change Counter
> API used by D1 retreive from Issuer Backend the PIN Change Counter for a given card.\
> \
The PIN Change counter is used to compute PRW and MAC
```json
{"openapi":"3.0.0","info":{"title":"Outbound PIN Management API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"},{"url":"https://YOUR_DOMAIN_NAME","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"BadRequestOutbound":{"description":"Bad Request, Invalid request URI or header, or unsupported non-standard parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"UnauthorizedOutbound":{"description":"The provided Authorization header is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"ForbiddenForGetPinChangeCounter":{"description":"Forbidden action, check the state of the linked consumer or account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorCodeWithError"}}}},"NotFoundForPhysicalCardOutbound":{"description":"Resource not found, Unknown issuerId or consumerId or accountId or card id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}},"InternalServerErrorOutbound":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorGenericOutbound"}}}}},"schemas":{"errorGenericOutbound":{"type":"object","description":"Generic error returned by the APIs.","properties":{"error":{"type":"string","description":"Description of the error."}}},"errorCodeWithError":{"type":"object","description":"The error code and message corresponding to reason of failure.","properties":{"errorCode":{"type":"string","enum":["PIN_CHANGE_FORBIDDEN","CARD_NOT_ACTIVE"]},"error":{"type":"string","description":"Description of the error."}}}}},"paths":{"/cms/api/v1/issuers/{issuerId}/cards/{cardId}/pin/changeCounter":{"get":{"summary":"Get PIN Change Counter","operationId":"getPINChangeCounter","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"object","properties":{"pcc":{"type":"string","description":"The PIN Change Counter value.","pattern":"^[0-9]{4}$"},"intdatag":{"type":"string","description":"Identifier used to correlate the call to get Pin Change Counter and the call to set Pin.\n","minLength":20,"maxLength":20}},"required":["pcc","intdatag"]}}}},"400":{"$ref":"#/components/responses/BadRequestOutbound"},"401":{"$ref":"#/components/responses/UnauthorizedOutbound"},"403":{"$ref":"#/components/responses/ForbiddenForGetPinChangeCounter"},"404":{"$ref":"#/components/responses/NotFoundForPhysicalCardOutbound"},"500":{"$ref":"#/components/responses/InternalServerErrorOutbound"}},"description":"API used by D1 retreive from Issuer Backend the PIN Change Counter for a given card.\n
The PIN Change counter is used to compute PRW and MAC\n","parameters":[]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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://docs.payments.thalescloud.io/pin-management/es/integrar-la-api-d1/referencia-de-la-api-d1/api-saliente-desde-d1/api-de-gestion-de-pin.md?ask=
```
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.