/
5 minute read
March 24, 2022

PINs

Use the /pins endpoint to create, update, or reveal a personal identification number (PIN) for a card.

Create or update PIN

Action: PUT
Endpoint: /pins

Creates or updates a PIN for an existing card.

If you want to manage a card’s PIN, first create a new control token for the card by sending a POST request to /pins/controltoken, and then use that token to update the PIN. You must create a card before you can manage a PIN.

Unless PIN reveal functionality has been enabled for your program, you cannot retrieve a PIN that has previously been created. If the PIN has been forgotten, you must either update the card’s PIN or create a new card and PIN.

If you have enabled PIN reveal functionality for your program, you can send a POST request to the /pins/reveal endpoint to retrieve an existing PIN. See Reveal PIN on this page for details.

Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
Request body
Fields Description

control_token

string
Required

The unique value generated as a result of issuing a POST request to the /pins/controltoken endpoint. This value cannot be updated.

Allowable Values:

1–36 chars

pin

string
Required

The four-digit number to associate with the card.

Allowable Values:

4 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No

Create PIN control token

Action: POST
Endpoint: /pins/controltoken

Creates a control token necessary when creating or updating a card’s PIN.

Creating, updating, or revealing a card’s PIN is a two-step process. You must first create the control token that is required to create the PIN, and then you create, update, or reveal the PIN itself.

The lifespan of the control token in a production environment is either five minutes or one hour from creation, depending on the token type. If multiple tokens are requested for a single card, only the most recent one is valid. Once redeemed, a token cannot be reused.

Request body
Fields Description

card_token

string
Required

The unique identifier of the card for which you want to generate a control token.

Allowable Values:

1–36 chars

Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.

controltoken_type

string
Optional

Specifies the type of action completed by this request.

WARNING: Sending a request to this endpoint with a REVEAL_PIN control token requires PCI DSS compliance.

The lifespan of the control token depends on the token type:

  • SET_PIN: 60 minutes

  • REVEAL_PIN: 5 minutes

Allowable Values:

SET_PIN, REVEAL_PIN

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

control_token

string
Returned

The unique value generated as a result of issuing a POST request to the /pins/controltoken endpoint. This value cannot be updated.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Reveal PIN

Action: POST
Endpoint: /pins/reveal

Reveals the PIN of an existing, active card.

Warning
Only use this endpoint to access a PIN in order to reveal it to its cardholder. Do not use this endpoint for the purpose of storing a PIN at any location.

Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.

If you want instead to update a card’s PIN, send a PUT request to the /pins endpoint. See Create or Update PIN on this page for details.

Revealing a card’s PIN is a two-step process. You must first create a new control token for the card by sending a POST request to /pins/controltoken, and then use that token to reveal the PIN.

Request body
Fields Description

cardholder_verification_method

string
Required

The supplemental method used to verify the cardholder’s identity before revealing the card’s PIN.

The possible cardholder verification methods are:

  • BIOMETRIC_FACE: In-app authentication via facial recognition

  • BIOMETRIC_FINGERPRINT: In-app authentication via biometric fingerprint

  • LOGIN: In-app authentication by re-entering the app password

  • EXP_CVV: In-app authentication by entering the card’s expiration date and CVV

  • OTP_CVV: Two-factor authentication involving the card’s CVV and an OTP

  • OTP: Two-factor authentication involving a one-time password (OTP)

  • OTHER: Authentication that relies on other secure methods

Allowable Values:

BIOMETRIC_FACE, BIOMETRIC_FINGERPRINT, LOGIN, EXP_CVV, OTP_CVV, OTP, OTHER

control_token

string
Required

The unique value generated as a result of issuing a POST request to the /pins/controltoken endpoint. This value cannot be updated.

Allowable Values:

1–36 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter