Background

A personal identification number (PIN) is an anti-fraud measure that helps authenticate the cardholder at physical points of sale and ATMs. Spidr recommends routing customers to set a PIN at the time they activate their card. The PIN can also be updated at any time via the Get PIN Change Token and Change PIN endpoints.

You can set a PIN for a Physical-Only and Digital-First cards (see Card Types) or for a Virtual-Only card that is provisioned to a mobile wallet, in the event that the wallet is presented at a physical NFC device that accepts PINs. Please do not set PINs for Virtual-Only cards that are not in mobile wallets.

Overview

Spidr provides a secure direct-render PIN set method that allows the cardholder to enter their PIN via a processor-hosted form. This method does not require PCI compliance on behalf of the program and ensures that data is securely exchanged directly with the underlying processor.

PIN-Set Configuration Items

• Spidr will provide you with a base URL where your program's PIN set form resides. This URL can also be found within the Spidr Dev Portal. For mobile apps, you will embed this form in a WebView. For web apps, you will open it in a popup window or new tab.
  • Example URL: https://[SpidrURL]/agserv/direct/pin/en_US/[submitterID]/

Mobile Apps (WebView)

The WebView approach uses native JavaScript interfaces to receive status codes directly from the processor-hosted PIN form.

WebView Setup

• Add an interface/handler to the WebView to receive the success/failure codes outlined below in Status Code Values.
• For Android, generate and register to the WebView a JavaScriptInterface with the name Android and the method postMessage (int statusCode).
• For iOS, generate and register to the WebView a ScriptMessageHandler with the name IOS.

Staging the PIN

• When a user wants to set or change a PIN, call Get PIN Change Token.

📘

PIN Change Token Validity

The PIN change token is valid for 5 minutes and for 5 attempts. After 5 minutes have elapsed or if 5 attempts are unsuccessful, a new key must be generated.

• Using the base URL configured for your program, you will append the token to the URL for your PIN-set call.
• After the user enters and confirms their PIN, you will receive the status code via your interface/handler. See Status Code Values for codes.
• Depending on the code received, redirect your user to an error/success screen.

Committing the PIN

If a status code of 0 is received from the PIN-set form call, you can proceed with the final step, committing the PIN. Call the Commit PIN Change endpoint to finalize the PIN change. Your user now has a new PIN! 🎉

Web Applications

Web apps cannot use the native WebView JavaScript interfaces (JavaScriptInterface on Android, ScriptMessageHandler on iOS) to receive status codes from the processor-hosted PIN form. Instead, use webhooks to determine when the PIN has been staged and is ready to commit.

Webhook-Based Flow

1. Get a token — Call Get PIN Change Token from your backend.
2. Load the PIN form — Open the processor-hosted PIN set URL in a popup window or new tab, appending the token to the base URL configured for your program.
3. Listen for webhooks — Listen for the account.pinChangeStageSuccess webhook. This fires when the processor confirms that the user successfully entered their PIN via the form. Also listen to account.pinChangeStageFail to handle failures (e.g., mismatched PINs, expired token).
4. Commit the PIN — Upon receiving account.pinChangeStageSuccess, call Commit PIN Change from your backend to finalize the PIN change.

Status Code Values

Consult this table to see an explanation of the status codes returned for the PIN-set form call and which next steps to take, if any. These codes are delivered via the WebView interface/handler (mobile) or indicated by the account.pinChangeStageSuccess / account.pinChangeStageFail webhooks (web).

PIN-Related Webhooks

The following webhooks are relevant to the PIN-setting flow. See the Spidr Webhook Documentation for full payload examples.

Processor-Originated Webhooks

These are sent asynchronously by the processor during or after the PIN-setting process.

API-Originated Webhooks

These are sent when the corresponding Spidr API endpoint is called successfully.

📘

card.pinChanged vs account.pinChange

card.pinChanged fires immediately when your backend calls /commitPinChange. account.pinChange is an asynchronous confirmation from the processor that the PIN was actually updated in their system. Both should be received for a successful PIN change.

Related Endpoints