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:
- You call the Galileo Program API to get a PIN-set access key.
- 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.
- The cardholder submits the form POST and Galileo processes the data.
- An HTTP 302 redirect sends the cardholder's browser to a pre-configured page that you host, for success or failure.
- You parse the response information in the HTTP query string to get the result.
- 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.
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
https://pin.foo.com/pin-success, Galileo must register
https://pin.foo.comin 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 the success redirect URL is
From Galileo you need:
- Submitter ID
Review this flowchart for the workflow:
Either on your web page or mobile app, the cardholder indicates the desire to set or change a PIN.
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 status codes table for an explanation of what each status code means and which next steps to take, if any.
Present an HTML form to the cardholder that is targeted (via the
action attribute) at a Galileo endpoint.
The form must contain these elements:
|The cardholder's desired PIN|
|The re-entered PIN, for validation purposes|
|50-character key (|
|An identifier that Galileo has provided to you, with the format |
|Optional. Unique identifier that you provide, similar to |
|Optional. Timestamp formatted as |
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
<form enctype=\"application/x-www-form-urlencoded\" action=\"https://agserv-[clientname].cv.gpsrv.com/agserv/pin" 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=\"\"> </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.
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.
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_reentryare not populated, the
eelement contains a JSON string that communicates the data validation errors, as shown below.
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.
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.
These internal, provider-level parameters must be set at Galileo.
|GGDPA||Enable 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|
|GGRDR||Full redirect URL when using a single results page|
|GGRBU||Base redirect URL when using both success and failure redirect pages|
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 code||Description||Next steps|
|Success||Continue the procedure|
|Your API call contained one or more values that were not valid for the parameter.||Retry with valid parameters|
|System exception||Contact Galileo for troubleshooting|
|The value in ||Retry with valid account number|
|Multiple active cards were found for the account.||Retry with the CAD (|
|System failure. Possibly a network or database issue.||Consult the response message to see which steps to take.|
These statuses are returned in the HTTP 302 redirect in the
r response code element.
|Success||Continue the procedure.|
|System error||Contact Galileo for troubleshooting.|
|Malformed or missing data||Retry with valid data.|
|Invalid provider||Retry with a valid provider ID.|
|Configuration error||Contact Galileo for troubleshooting.|
|Invalid submitter ID||Retry with a valid submitter ID.|
|Cardholder 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.|
|Token not valid or expired||Retry with a valid token. You may need to call Get Card PIN Change Key again.|
|Entered and re-entered PIN values do not match||Inform the cardholder that the PIN values must match.|
|PIN change request not in correct status||Verify that the PIN change request has been staged but not committed.|
Consult the Commit Card PIN Change endpoint reference for status codes and next steps.
Updated 6 months ago