PIN Retrieval Service

Follow this procedure to securely retrieve a PIN and present it to a cardholder as a CAPTCHA image. The actual value of the PIN is not exposed to you—only to the cardholder. For compliance reasons, you must not cache the image in any way on the device or browser, nor can you use a proxy server to retrieve the image for the device or browser.

The CAPTCHA image will resemble this example:

160160

Using the PRS consists of these steps:

  1. Galileo sets the PRSEN parameter for the product or program.
  2. Galileo configures a provider name for the config parameter and gives it to you.
  3. You call the Get Access Token endpoint to retrieve a token for the card.
  4. With the token, the browser or mobile app makes an HTTP call to retrieve the CAPTCHA image of the PIN.
  5. The CAPTCHA image is presented to the cardholder.

Get Access Token call

These parameters are required for the Get Access Token call:

  • accountNo — Galileo recommends using the CAD (card_id) or PAN, but the PRN is valid as long as only one card has ever been associated with the account.
  • type — Pass 0 to retrieve a card-related token.

The response will contain these fields:

  • token — A case-sensitive alphanumeric string, for example, hpSVyayQScHmhJS6_MVXT1WlsFRQoDJrRu_fi_JlX2Jo2dgg5p
  • expires — The date/time the token expires, formatted as YYYY-MM-DD hh:mm:ss

The token has two properties: the expiration (default: 300 seconds) and the maximum times an access token can be used (default: 3). You can change the defaults in your product parameters, as shown in Galileo setup.

HTTP request for the CAPTCHA

With the token, assemble an HTTP request to retrieve the CAPTCHA, as shown in the example. The URL is an AWS instance that Galileo sets up for each client. Request an AWS URL from Galileo if you do not already have one. These examples are for the CV environment. For Production change the cv in the URL to pd.

https://asset-[clientname].cv.gpsrv.com/asset/pin?token=[token]&config=[config]

where:

  • token — The token you retrieved with the Get Access Token call
  • config — Your provider name, as configured by Galileo
  • clientname — Your Galileo system name

The asset application retrieves the CAPTCHA image in response to the HTTP call. If the image is not found, a standard HTTP 404 response is returned. For all other errors, such as an expired token, an HTTP 401 response is returned.

Presenting the CAPTCHA

Embed the URL within a web or mobile app as an HTML image reference, offer the URL as a direct customer-exposed link, or use it in other appropriate contexts. The URL is an AWS instance that Galileo sets up for each client. Request an AWS URL from Galileo if you do not already have one. This example is for the CV environment. For Production change the cv in the URL to pd.

<image src="https://asset-[clientname].cv.gpsrv.com/asset/pin?token=[token]&config=[config]" alt="PIN Image" width="160" height="80" />

The width and height parameters are currently fixed at 160 and 80 pixels.

Galileo setup

These internal parameters are set at Galileo, according to your use case.

ParameterLevelDescription
PRSENProgram or productSet to Y to enroll the cardholders of the program or product in PRS.
TSECVProgram or productMaximum seconds of access-token validity (default: 300).
TUSECProgram or productMaximum times an access token can be used (default: 3).