Direct Render PIN-Set Procedure

This guide describes the direct render procedure for setting PINs, using the Get Card PIN Change Key and Commit Card PIN Change endpoints. This procedure transfers PCI-sensitive information directly from the cardholder’s device to Galileo's system using a PIN-set form that Galileo hosts. You do not need to be PCI compliant to use this method.

Go to PIN-Set Procedures for other methods.

Use this procedure to:

  • Set a cardholder’s PIN for a new card
  • Reset a cardholder's PIN for an existing card

The direct form PIN-change process transfers PIN data from the cardholder directly to Galileo without the data passing through your system, thereby satisfying information security requirements. The process involves the following high-level steps:

  1. You call the Galileo Program API to get a PIN-change access key.
  2. You present the cardholder with an HTML PIN-set form that Galileo hosts.
  3. The cardholder enters the PIN twice and submits the form. Galileo stages the change if the PINs are correct.
  4. Galileo informs you of the success or failure of the PIN validation and form submission via either JavaScript or redirect pages, and Events API webhook messages may also be sent.
  5. If successful, you call the Galileo Program API to commit the PIN change. Galileo may send an Events API webhook to notify that the change was successful.

Options

You will need to decide among various options before using this procedure.

  • PIN-set form presentation:
    • WebView — Wrap the PIN-set form in a WebView.
    • Browser window/pop-up — Present the PIN-set form directly in a browser or pop-up.
    • iFrame — Embed the PIN-set form as an iFrame.
  • PIN-set form styling:
  • Results presentation:
    • Your redirect pages — You can host one page for both results or different pages for success and failure. The pages can be accessed via HTTP or a deep link in your app.
    • Galileo redirect pages — Galileo hosts the success and failure pages.
    • JavaScript — Galileo enables JavaScript callbacks to be called on the error and success pages. JavaScript must be enabled on the PIN-set form.
    • Webhook messages — Galileo sends Events API webhook messages to your server in addition to one of the other methods.
  • Token/key validity:
    • Amount of time — Default is five minutes.
    • Number of attempts — Default is five attempts.

Prior setup

After you have been approved to use the direct render procedure, you must coordinate with Galileo to get set up. You will need to provide:

  • Issuing bank approval.
  • If using the redirect options — A list of base URLs to be used in redirects. When you pass in a redirect URL, the beginning of the URL is matched to the configured URLs in the Galileo system. You may also use custom schemes to intercept redirects within a mobile application.
    • If the success redirect URL is https://pin.foo.com/pin-success, Galileo 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, Galileo must register bar://.
  • Additional header fields and values to be set on the redirect response.
  • Whether to enable mobile callbacks in WebView.
  • Whether to enable JavaScript messages in the parent page for the iFrame.
  • If using the iFrame option — 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, Galileo registers https://pin.bar.com to enable the PIN form site to be in an iFrame.
  • CSS (cascading stylesheet) or SCSS (sassy CSS).

Stylesheets

All stylesheets must be approved by Galileo before they are added to the system. You can provide more than one stylesheet. The filenames for the stylesheets are specified in a comma-delimited list in the GGSAS parameter, with the first filename listed being the default stylesheet. For example, if you create three stylesheets, they would be listed as style-1,style-2,style-3 in the GGSAS parameter. See step 3. Call the PIN-set form for instructions on specifying the stylesheet.

Galileo will provide you with a starting CSS/SCSS file to style the PIN-set form. You then modify the file to add your styling. (There are SCSS plugins available for most major IDEs including Visual Studio Code and Jetbrains IDEs.)

📘

Note

You can provide or update the stylesheet at any point in the process. Galileo can perform initial setup without your stylesheet. When submitting a stylesheet change, you must provide the entire stylesheet.

The top section of the SCSS file has variables used for the form and basic styling. Most styles can be modified by setting the variables in the first section.

If you need more advanced styling, Galileo can provide four sample HTML pages that match the HTML of the PIN-set form:

  • Set Your Pin.html — The initial PIN-set form with no alerts or errors.
  • Set Your Pin-form-errors.html — The initial PIN-set form with form errors and error alerts visible.
  • Set Your Pin-error.html — The error page that the cardholder would see if a token becomes expired or other system error occurs, such that you need to restart the process.
  • Set Your Pin-success.html — The success page that the cardholder would see

You cannot edit the HTML pages — the only styling that is permitted is via the stylesheet. If you are using redirects, the sample error and success pages will not be visible to your cardholder. Galileo will redirect to the URLs that you passed instead of displaying the sample pages.

📘

Note

The stylesheet cannot include references to external resources such as images, fonts, or additional stylesheets. The CSS/SCSS file can contain small base64-encoded images, which must be approved and encoded by Galileo.

Galileo has several fonts available from Google Fonts. (Go to https://fonts.google.com to view font samples.) If you want to use other fonts, you must first obtain a license to use the font, then the font must be approved and go through a project request and change window (at least one month), so additional costs may accrue.

Currently available fonts:

FontURL
Arimoarimo-v13-latin/arimo-v13-latin-regular.[eot, svg, ttf, woff, woff2]
IBM Plex Monoibm-plex-mono-v5-latin/ibm-plex-mono-v5-latin-regular.[eot, svg, ttf, woff, woff2]
Latolato-v16-latin/lato-v16-latin-regular.[eot, svg, ttf, woff, woff2]
Merriweathermerriweather-v21-latin/merriweather-v21-latin-regular.[eot, svg, ttf, woff, woff2]
Merriweather Sansmerriweather-sans-v11-latin/merriweather-sans-v11-latin-regular.[eot, svg, ttf, woff, woff2]
Open Sansopen-sans-v17-latin/open-sans-v17-latin-regular.[eot, svg, ttf, woff, woff2]
Playfair Displayplayfair-display-v15-latin/playfair-display-v15-latin-regular.[eot, svg, ttf, woff, woff2]
PT Monopt-mono-v7-latin/pt-mono-v7-latin-regular.[eot, svg, ttf, woff, woff2]
PT Serifpt-serif-v11-latin/pt-serif-v11-latin-regular.[eot, svg, ttf, woff, woff2]
Robotoroboto-v20-latin/roboto-v20-latin-regular.[eot, svg, ttf, woff, woff2]
Roboto Condensedroboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.[eot, svg, ttf, woff, woff2]
Roboto Monoroboto-mono-v7-latin/roboto-mono-v7-latin-regular.[eot, svg, ttf, woff, woff2]
Roboto Slabroboto-slab-v9-latin/roboto-slab-v9-latin-regular.[eot, svg, ttf, woff, woff2]
Slaboslabo-27px-v6-latin/slabo-27px-v6-latin-regular.[eot, svg, ttf, woff, woff2]
Source Sans Prosource-sans-pro-v13-latin/source-sans-pro-v13-latin-regular.[eot, svg, ttf, woff, woff2]

To use one of these fonts, add the font face to your CSS/SCSS file. For example:

@font-face {
    font-family: 'Roboto Condensed';
    font-style: normal;
    font-weight: 400;
    src: url('/agserv/fonts/roboto-condensed-v18-latin-regular.eot');
    src: local('Roboto Condensed'), local('Roboto Condensed Regular'), 
url('/agserv/fonts/roboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.eot#iefix') format('embedded-opentype'),
url('/agserv/fonts/roboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.woff2') format('woff2'),
url('/agserv/fonts/roboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.woff') format('woff'),
url('/agserv/fonts/roboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.ttf') format('truetype'),
url('/agserv/fonts/roboto-condensed-v18-latin/roboto-condensed-v18-latin-regular.svg#RobotoCondensed') format('svg');
}

Once you have added your styles, Galileo will add the CSS/SCSS file or files to the system. (The stylesheets replace the partner.css file in the sample HTML pages.)

📘

Note

If you submit stylesheet changes but they are not visible after Galileo has updated the CSS file, verify that your submitter_id is correct. CSS files are linked to the submitter_id, so if there is a typo you will most likely see the default CSS.

WebView

If you are wrapping the PIN-set form in a native mobile application WebView, you can add an interface/message handler to receive the code from the error and success pages.

JavaScript must be enabled on the Galileo system. Interfaces are called onLoad if interfaces are found in code on error and success pages.

For Android, generate and register to the WebView a JavaScriptInterface with the name Android and the method postMessage(int statusCode). See Sample code for an example.

For iOS, generate and register to the WebView a ScriptMessageHandler with the name IOS. See Sample code for an example.

Direct render PIN-set workflow

This flowchart illustrates the workflow for the process:

1. Cardholder accesses your interface

The cardholder goes to your interface to set or change a PIN.

2. Send the Get Card PIN Change Key call

Galileo recommends that you pass the CAD (card_id) for accountNo in the Get Card PIN Change Key call.

In the response, Galileo sends a 50-character key in the token field. This key is valid for only a limited time and for only a specified number of uses, which are configured in your provider parameters. Defaults are five minutes and five page requests. The key cannot be reused after a success.

Consult the Get Card PIN Change Key status codes table for an explanation of what each status code means and which next steps to take, if any.

3. Call the PIN-set form

Create a URL using the token, your submitter ID, and locale to call the PIN-set form. The PIN-set form that you call for the customer's initial PIN set will be identical to the customer's subsequent calls to reset the PIN.

These examples contain the URL for the CVCV - Client Validation. A test environment where you can test your implementation before moving it to Production. environment. For ProductionProduction - The live Galileo environment where real transactions are performed. change ua or cv in the URL to pd. Use the non-AWS call unless you are on a Galileo AWS instance.

Non-AWS call
<iframe src="https://secure-agserv.ua.gpsrv.com/agserv/direct/pin/[locale]/[submitter_id]/[token]">
AWS call
<iframe src=\"https://agserv-[clientname].cv.gpsrv.com/agserv/direct/pin/en_US/[submitter id]/[token]">

where:

  • locale — Supported locales are en_US, es_US, fr_US, fr_CA, en_MX, or es_MX, or you can specify the language only, as en, es, or fr.
  • submitter_id — Supplied by Galileo, this number identifies your stylesheet, which will be applied to the PIN-set form. The identifier has the format [provider_id]-9999.
  • token — The 50-character token that you retrieved by calling Get Card PIN Change Key.
  • clientname — Your Galileo system name

Include redirects (optional)

If you are redirecting to pages that you host, 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.

Single-page redirect

This is the format when both success and failure use the same page:

https://[Galileo_URL]/agserv/direct/pin/[locale]/[submitter_id]/[token]?r=[URL-encoded_result_page]

Optional: Include the s parameter to specify which stylesheet to use, such as s=style-2. If you do not pass the s parameter, the first stylesheet listed in the GGSAS parameter is used.

Non-AWS example
https://secure-agserv.ua.gpsrv.com/agserv/direct/pin/en_US/99-9999/888tOkEn777777AaaaaaAtOkEn999999999999999999999999?r=https%3A%2F%2Fmydomain.com%2Fresult%2F
AWS example
https://agserv-[clientname].cv.gpsrv.com/agserv/direct/pin/[locale]/99-9999/888tOkEn777777AaaaaaAtOkEn999999999999999999999999?r=https%3A%2F%2Fmydomain.com%2Fresult%2F
Separate-page redirect

This is the format when success and failure each have their own page:

https://[Galileo_URL]/agserv/direct/pin/[locale]/[submitter_id]/[token]?r=[URL-encoded_success_page]&f=[URL-encoded_failure_page]

Optional: Include the s parameter to specify which stylesheet to use, such as s=style-2. If you do not pass the s parameter, the first stylesheet listed in the GGSAS parameter is used.

Non-AWS example
https://secure-agserv.ua.gpsrv.com/agserv/direct/pin/en_US/99-9999/888tOkEn777777AaaaaaAtOkEn999999999999999999999999?r=https%3A%2F%2Fmydomain.com%2Fresult%2Fsuccess&f=https%3A%2F%2Fmydomain.com%2Fresult%2Ffailure
AWS example
https://agserv-[clientname].cv.gpsrv.com/agserv/direct/pin/en_US/99-9999/888tOkEn777777AaaaaaAtOkEn999999999999999999999999?r=https%3A%2F%2Fmydomain.com%2Fresult%2Fsuccess&f=https%3A%2F%2Fmydomain.com%2Fresult%2Ffailure

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.

Consult the PIN-set form status codes table to see an explanation of the status codes for the PIN-set form call and which next steps to take, if any.

4. Cardholder submits the form

The cardholder enters and re-enters the PIN and submits the data directly to Galileo, without the data traversing your system.

5. Galileo sends the verdict

If submitting the form times out, Galileo sends a failure message. If submitting the form is otherwise unsuccessful, such as the form being incorrectly formatted, Galileo sends a failure message.

If the form submission is successful, Galileo performs two verification checks:

  • The PINs have four digits each
  • The PINs match

Galileo responds with either success or failure, sending that response via redirect or JavaScript.

If the verification checks are successful, Galileo stages the PIN change. According to your arrangements with Galileo, you will also receive the AFPE: agserv_PIN_change_fail or AFPS: agserv_PIN_change_success Account Events webhooks.

6. Send the Commit Card PIN Change call

If you receive a success message, send the Commit Card PIN Change call to commit the change. Use the same accountNo that you used for the Get Card PIN Change Key call.

Consult the Commit Card PIN Change status codes table to see an explanation of what each status code means and which next steps to take, if any.

When the PIN change is successful, Galileo sends the PNCH: system_pin_change event. At this point, the cardholder can use the PIN, and you can retrieve the PIN via the PIN Retrieval Service if you are subscribed to that service.

Sample code

The samples below are provided as a reference on how to consume iFrame messages and mobile callbacks.

👍

Warning

The code samples contain some debugging and logging code that should not be used in the Production environment.

JavaScript

Requires JavaScript and iFrame messaging to be enabled.

if (window.addEventListener) {
    window.addEventListener("message", function (event) {
        // Modify URL to match environment
        if (event.origin !== "https://secure-agserv.ua.gpsrv.com") {
            console.log("Event.origin does not match baseurl");
            return;
        }
        var statusCode = event.data;
        // Do something with the statusCode
        console.log("Received status code: " + statusCode);
        alert("Received message: " + event.data);
    }, false);
}

Android (Kotlin)

Requires JavaScript and mobile callbacks to be enabled.

class MainActivity : AppCompatActivity() { 
    lateinit var webView: WebView
    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        webView = WebView(this)
        setContentView(webView)
        webView.settings.javaScriptEnabled = true
        webView.addJavascriptInterface(WebAppInterface(this), "Android")
        webView.webChromeClient = WebChromeClient()
        webView.webViewClient = WebViewClient()
        webView.loadUrl("https://secure-agserv.ua.gpsrv.com/agserv/direct/pin/en_US/99-9999/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    }
 
    override fun onResume() {
        super.onResume()
    }
 
    class WebAppInterface(private val context:Context) {
 
        @JavascriptInterface
        fun postMessage(code: Int) {
            Toast.makeText(context, "Received code $code", Toast.LENGTH_LONG).show()
        }
    }
}

iOS (Swift)

Requires JavaScript and mobile callbacks to be enabled.

class ViewController: UIViewController, WKScriptMessageHandler, WKNavigationDelegate {
    
    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        print(message.body);
    }
 
    override func viewDidLoad() {
        super.viewDidLoad();
        let preferences = WKPreferences();
        preferences.javaScriptEnabled = true;
        let contentController = WKUserContentController();
        contentController.add(self, name: "IOS");
        let config = WKWebViewConfiguration();
        config.preferences = preferences;
        config.userContentController = contentController;
        let url = URL(string: "https://secure-agserv.ua.gpsrv.com/agserv/direct/pin/en_US/99-9999/KU1kqfr0zrFgwP0KXFfz3JuMrj5ETmGtXn7RH8p5_49oQTeew7");
        let webview = WKWebView(frame:
            self.view.bounds, configuration: config); self.view.addSubview(webview);
        webview.navigationDelegate = self
        webview.load( URLRequest( url: url!) );
    }
    
    func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {
        webView.evaluateJavaScript("document.documentElement.outerHTML.toString()",
                                   completionHandler: { (html: Any?, error: Error?) in
                                    
            print(html!)
        });
    }
 
}

Galileo setup

These internal provider-level parameters must be set at Galileo, according to the form-presentation and results-presentation methods that you are using.

ParameterDescriptionFormResults
GGEJSEnable all JavaScript. Required if using mobile or iFrame postMessage.iFrame
WebView
JavaScript
GGHDR (optional)A set of key/value pairs for additional response headers when using no-redirect mode.iFrame
WebView
Redirect
GGIFDDomains that are allowed to call the iFrame.iFrameRedirect
JavaScript
GGIFMEnable event trigger on error and success pages.iFrameJavaScript
GGKEH
(optional)
Number of times a PIN-set token can be used. Default: 5iFrame
WebView
Redirect
JavaScript
GGKEX
(optional)
Seconds before token expiry. Default: 300iFrame
WebView
Redirect
JavaScript
GGMCBEnable native mobile callbacks.WebViewJavaScript
GGRBUArray of redirect URLs when using a single results page or base redirect URLs when using both success and failure redirect pagesiFrame
WebView
Redirect
GGSASName of the file to use as a stylesheet. In the case of multiple stylesheets, this is a comma-separated list of filenames.iFrame
WebView
Redirect
JavaScript

Get Card PIN Change Key status codes

Consult this table to see an explanation of what each status code means for the Get Card PIN Change Key endpoint and which next steps to take, if any.

Status codeDescriptionNext steps
0SuccessContinue the procedure
2Your API call contained one or more values that were not valid for the parameter.Retry with valid parameters
4System exceptionContact Galileo for troubleshooting
12The value in accountNo is not a valid account number.Retry with valid account number
47Multiple active cards were found for the account.Retry with the CAD (card_id) in accountNo.
-1System failure. Possibly a network or database issue.Consult the response message to see which steps to take.

PIN-set form status codes

Consult this table to see an explanation of the status codes for the PIN-set form call and which next steps to take, if any.

Status codeDescriptionNext steps
0SuccessContinue the procedure
-1Bad submitter ID or no redirect URL providedRetry with valid submitter ID or provide redirect URL
-10Invalid token. Token is either expired or not found.Verify that the token is correct or call the Get Card PIN Change Key endpoint again.
-11Cardholder submitted a form with a token that is no longer valid, because Get Card PIN Change Key was called again, invalidating the previous key.Verify that the form is using the correct key before calling Get Card PIN Change Key again.
-999System errorContact Galileo for troubleshooting
-9999Unknown errorContact Galileo for troubleshooting

Commit Card PIN Change status codes

Consult this table to see an explanation of what each status code means for the Commit Card PIN Change endpoint and which next steps to take, if any.

Status codeDescriptionNext steps
0SuccessNone
2Your API call contained one or more values that were not valid for the parameter.Retry with valid parameters.
4System exceptionContact Galileo for troubleshooting.
12The value in accountNo is not a valid account number.Retry with valid account number.
47Multiple active cards were found for the account.Retry with the CAD (card_id) in accountNo.
537-01No staged PIN change found.Verify that the form submission was successful.
537-02No cards in status: N were found for the account.Verify that the card is in active status, or inform the cardholder that no PIN can be set for this card.
537-03PIN change has not been started.Restart the process, beginning with calling Get Card PIN Change Key.
-1System failure. Possibly a network or database issue.Consult the response message to see which steps to take.

Did this page help you?