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. You will embed this form in a WebView.
  • Example URL: https://[SpidrURL]/agserv/direct/pin/en_US/[submitterID]/

WebView Setup

• If you are using a WebView to wrap the pin-set form, you can add an interface/handler 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.

WebView Process Summary

WebView - 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.

WebView - 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! 🎉

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.