Skip to main content

Set a PIN

POST 
/v1/cards/:card_id/pin

Sets the PIN of a physical card from a PIN you have encrypted. It is a server-to-server call: there is no page to open. The same call sets a first PIN and resets a forgotten one.

  1. Get a key with POST /v1/cards/{card_id}/pin-key.
  2. Encrypt the PIN, as its digits, to that key with RSA-OAEP using SHA-256, and encode the result as base64.
  3. Send key_id and the encrypted PIN here.

Encrypt on the cardholder's device. The PIN is ciphertext while it passes through your systems, and it stays out of PCI DSS scope only while your servers never see it in the clear. A server that handles the PIN unencrypted is in scope.

We check only what a PIN needs to be usable: digits, in the length the key response gives as pin_length. Anything else is your policy, such as whether to refuse repeated digits or sequences, and is yours to validate before you encrypt. A PIN that isn't digits of that length is refused with pin_invalid. A key that is unknown, already used or expired is refused with invalid_parameter; get a new one.

Only a physical card that is active has a PIN to set. Any other card is refused with card_invalid_state, and a closed card with card_closed.

Never write the PIN, encrypted or not, to a log, an analytics event, web storage or a support ticket.

Requires the cards:secrets scope.

Request​

Responses​

The PIN is set. Nothing is returned.