PIN Issuance Policy

Card products have a PIN issuance policy that enables creating physical cards with the PIN programmed into the card's chip prior to shipment. This allows merchants to verify the PIN at the point of sale even in an offline scenario. The way that the PIN is set prior to shipment is determined by the card product's pin_issuance_policy field. The pin_issuance_policy field has three possible values: NOT_REQUIRED, RANDOM and REQUIRED.

Your physical card product may require offline PIN support. See the offline_pin flag in the card product response. If this flag is set then the PIN issuance policy must be something other than NOT_REQUIRED.

Virtual cards do not have a PIN issuance policy.

Not Required

If the pin_issuance_policy of your card product is NOT_REQUIRED (or there is no pin_issuance_policy) then the card will ship without a PIN. The PIN must still be set but this can happen after the customer receives their card.

Random

If the pin_issuance_policy of your card product is RANDOM then the system will assign a random PIN to the user's card prior to shipment. When you issue a card with this card product, the card will have PENDING status. Within a few minutes the card will transition to UNACTIVATED status. If you have the appropriate webhook subscription set up you will get a CARD.UPDATED webhook when this happens. After the customer receives and activates their card, they can then reveal the PIN using the Reveal PIN widget.

Required

If the pin_issuance_policy of your card product is REQUIRED then the card will be created having PENDING status. While in this state, the physical card will not be created. The card will not transition out of this status until the user sets a PIN for the card using the Set PIN widget. Within a few minutes of the user setting the PIN, the card will transition to UNACTIVATED status. If you have the appropriate webhook subscription set up you will get a CARD.UPDATED webhook when this happens. Once the card is UNACTIVATED, the physical card creation and shipping process will proceed.