Direct POST PIN-Set Procedure

This guide describes the direct POST procedure for setting PINs using the Get Card PIN Change Key and Commit Card PIN Change endpoints. This procedure involves transferring PCI-sensitive information directly from the cardholder's device to Galileo's system using an HTML PIN-set form that you host.

Go to PIN-Set Procedures for other methods.



You must complete PCI-DSS Self-Assessment Questionnaire A-EP (191 of 250 PCI requirements) to use this procedure. See Prior setup for details.

Use this procedure to:

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

The direct-POST PIN-set 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-set access key.
  2. You present the cardholder with an HTML PIN-set form that you host, including fields for the new PIN value and hidden fields that include the access key. The HTML form is targeted at Galileo servers.
  3. The cardholder submits the form POST and Galileo processes the data.
  4. An HTTP 302 redirect sends the cardholder's browser to a pre-configured page that you host, for success or failure.
  5. You parse the response information in the HTTP query string to get the result.
  6. If successful, you make a call to the Galileo Program API to commit the PIN change.


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

  • Token/key validity:
    • Amount of time — Default is five minutes.
    • Number of attempts — Default is five attempts.
  • Whether to use one or two results pages for success and failure.

Prior setup

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

  • Issuing bank approval
  • AOC, to be reviewed by Galileo Information Security Team
  • The URLs for your success and failure pages, which Galileo will use in the HTTP 302 redirects.
    • If the success redirect URL is, Galileo must register in the system to allow the redirect.
    • If you are using a failure redirect URL and it shares the same base URL (e.g., no additional base URLs need to be registered.

From Galileo you need:

  • Submitter ID


Review this flowchart for the workflow:

1. Cardholder accesses the PIN-change form

Either on your web page or mobile app, the cardholder indicates the desire 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. You can retrieve the CAD with the Get Card endpoint.

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

Consult the Get Card PIN Change Key endpoint for status codes and next steps, if any.

3. Generate the HTML interface

Present an HTML form to the cardholder that is targeted (via the action attribute) at a Galileo endpoint.

The form must contain these elements:

pinThe cardholder's desired PIN
pin_reentryThe re-entered PIN, for validation purposes
pin_change_key50-character key (token) that was returned by the Get Card PIN Change Key endpoint
submitter_idAn identifier that Galileo has provided to you, with the format [provider_id]-9999
submit_uniqueOptional. Unique identifier that you provide, similar to transactionId in the Program API
submit_dtOptional. Timestamp formatted as YYYY-MM-DD hh:ii:ss

Sample HTTP form

The URL in the example 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 sample form is for the CV environment. For Production change cv in the URL to pd.

<form enctype=\"application/x-www-form-urlencoded\" action=\"https://agserv-[clientname]" method=\"post\">
  <input type=\"hidden\" name=\"submitter_id\" value=\"222-2222\" id=\"submitter_id\">
  <input type=\"hidden\" name=\"submit_unique\" value=\"3333-3333-3333\" id=\"submit_unique\">
  <input type=\"hidden\" name=\"submit_dt\" value=\"2020-11-23 17:03:12\" id=\"submit_dt\">
  <input type=\"hidden\" name=\"pin_change_key\" id=\"pin_change_key\" value=\"888tOkEn777777AaaaaaAtOkEn999999999999999999999999\">
  <input type=\"text\" name=\"pin\" id=\"pin\" value=\"\">
  <input type=\"text\" name=\"pin_reentry\" id=\"pin_reentry\" value=\"\">

4. Cardholder submits the form

The cardholder enters and re-enters the PIN and submits the data via a form POST directly to Galileo, without traversing your system. 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

If the verification checks are successful, Galileo stages the PIN change.

5. Galileo sends the redirect

Galileo processes the PIN-set form POST and responds via an HTTP 302 redirect to your pre-defined URLs: either the success or failure page. According to your arrangements with Galileo, you will also receive the ADPE: agserv_PIN_change_fail or ADPS: agserv_PIN_change_success Account Events webhooks.

6. Send the Commit Card PIN Change call

The HTTP 302 redirect contains two query string elements that indicate success or failure conditions:

  • r — The response code element contains the success or failure state of the cardholder form POST, in URL encoding. See the HTTP 302 redirect codes table for a description of these response codes.
  • e — The error element is populated only when there is a data-validation error. For example: if pin or pin_reentry are not populated, the e element contains a JSON string that communicates the data validation errors, as shown below.

HTTP 302 redirect examples

These are examples of the redirect messages that Galileo will send in response to the direct POST: success or failure. Notice that in the second example the e element provides text for each of three fields that might have failed.{"pin":{"isEmpty":"Value%20is%20required%20and%20can%27t%20be%20empty"},"pin_reentry":{"isEmpty":"Value%20is%20required%20and%20can%27t%20be%20empty"},"pin_change_key":{"isEmpty":"%27pin_change_key%27%20is%20required%20and%20cannot%20be%20empty"}}

7. Send the Commit Card PIN Change call

If you receive a Success message in the HTTP 302 redirect, 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 endpoint reference for status codes and next steps.

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.

Galileo setup

These internal, provider-level parameters must be set at Galileo.

GGDPAEnable direct POST access
A set of key/value pairs for additional response headers when using no-redirect mode
Number of times a PIN-set token can be used. Default: 5
Seconds before token expiry. Default: 300
GGRDRFull redirect URL when using a single results page
GGRBUBase redirect URL when using both success and failure redirect pages

Get Card PIN Change Key status codes

Consult the Get Card PIN Change Key endpoint for status codes and next steps, if any.

HTTP 302 redirect codes

These statuses are returned in the HTTP 302 redirect in the r response code element.

CodeDescriptionNext steps
0SuccessContinue the procedure.
-1System errorContact Galileo for troubleshooting.
-2Malformed or missing dataRetry with valid data.
-5Invalid providerRetry with a valid provider ID.
-6Configuration errorContact Galileo for troubleshooting.
-7Invalid submitter IDRetry with a valid submitter ID.
-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.
-100Token not valid or expiredRetry with a valid token. You may need to call Get Card PIN Change Key again.
-101Entered and re-entered PIN values do not matchInform the cardholder that the PIN values must match.
-102PIN change request not in correct statusVerify that the PIN change request has been staged but not committed.

Commit Card PIN Change status codes

Consult the Commit Card PIN Change endpoint reference for status codes and next steps.