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.

📓 Note: Spidr currently supports both iFrame and WebView options for embedding the processor PIN-set form.

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 an iFrame or WebView.
  • Example URL: https://[SpidrURL]/agserv/direct/pin/en_US/[submitterID]/

iFrame & Redirect Setup

• You will work with Spidr to set up the styling (CSS) of the PIN set form and configure the redirect pages for successful and unsuccessful PIN set attempts. Spidr will redirect users upon success or failure to a page that your program hosts or a mobile deep link that you provide.
  • If the success redirect URL is https://pin.foo.com/pin-success, Spidr must register https://pin.foo.com in the system to allow the redirect.
  • If you are using a failure redirect URL and it shares the same base URL (e.g., https://pin.foo.com/pin-failure), no additional base URLs need to be registered.
  • If using a mobile deep link such as bar://pin-success, Spidr must register bar://.
• A list of URLs that will be embedding the iFrame. Because some legacy browsers do not support Content-Security-Policy, the first domain listed will be used for the X-Frame-Options header field.
• If the URL of the site embedding the iFrame is https://pin.bar.com/pin-set, Spidr registers https://pin.bar.com to enable the PIN form site to be in an iFrame.
• Details on these items and an overview of the process can be found via Process Summary below.

iFrame & Redirect Process Summary

iFrame - Staging the PIN

Before a PIN can be set or changed, it must be staged via the process below.

• 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.
• You will also specify the redirects for Spidr to use for successful and unsuccessful attempts in your PIN-set call. You can specify one page for both results or different pages for success and failure.
• You must pass in the URLs with the PIN-set form call, using this format as well as URL encoding:
  • ?r=[URL] — URL is the single redirect page or the success redirect page
  • ?f=[URL] — URL is the failure redirect page

📘

Status Codes

If you add %status_code% to the redirect URL, it will be replaced with the status code; otherwise, status_code=[status_code] will be appended to the redirect URL as a query-string variable. If the redirect URL contains variables, ensure that the variables are URL-encoded before encoding the full URL.

Full URL example with token and redirects:

• Single Page Redirect:

  https://[SpidrURL]/agserv/direct/pin/en_US/[submitterID]/[pinToken]?r=[URL-encoded_result_page]

• Separate-page Redirect:

  https://[SpidrURL]/agserv/direct/pin/en_US/[submitterID]/[pinToken]?r=[URL-encoded_success_page]&f=[URL-encoded_failure_page]

Example form presented after calling PIN-set form:

• After the user enters and confirms their PIN, Spidr will redirect them based on the redirect URLs you passed in. The status code will be appended to the redirect URL as a query-string variable so that you know how to proceed. See Status Code Values below for a list of values and the suggested action for each.

Example redirect page:

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

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.