This guide describes the direct POST procedure for setting PINs using the <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> and <a href="ref:post_commitcardpinchange" target="_blank">Commit Card PIN Change</a> endpoints. This procedure involves transferring <a href="doc:pci-sensitive-data" target="_blank">PCI-sensitive</a> 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 <<glossary: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.
**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
<<glossary: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.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.
From Galileo you need:
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 <<glossary:CAD>> (`
card_id`) for `
accountNo` in the <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> call. You can retrieve the CAD with the <a href="ref:post_getcard" target="_blank">Get Card</a> 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 status codes](🔗) table for an explanation of what each status code means and which next steps to take, 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:
|`||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 `|
#### 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 <<glossary:CV>> environment. For <<glossary:Production>> change `
cv` in the URL to `
<!--In case anyone needs it, the on-prem URL is http://secure-agserv.ua.gpsrv.com/agserv/pin Change ua to pd for production. Don't publish this URL, just give it out internally. -->
### 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 <a href="ref:api-reference-events-api-agserv-pin-change-fail" target="_blank">`
ADPE: agserv_PIN_change_fail`</a> or <a href="ref:api-reference-events-api-agserv-pin-change-success" target="_blank">`
ADPS: agserv_PIN_change_success`</a> 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.
### 7. Send the Commit Card PIN Change call
If you receive a Success message in the HTTP 302 redirect, send the <a href="ref:post_commitcardpinchange" target="_blank">Commit Card PIN Change</a> call to commit the change. Use the same `
accountNo` that you used for the <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> 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 <a href="ref:api-reference-events-api-system-pin-change" target="_blank">`
PNCH: system_pin_change`</a> event. At this point, the cardholder can use the PIN, and you can retrieve the PIN via the <a href="doc:pin-retrieval-service" target="_blank">PIN Retrieval Service</a> if you are subscribed to that service.
## Galileo setup
These internal, provider-level parameters must be set at Galileo.
|GGDPA||Enable direct POST access|
|GGHDR<br>(optional)||A set of key/value pairs for additional response headers when using no-redirect mode|
|GGKEH<br>(optional)||Number of times a PIN-set token can be used. Default: 5|
|GGKEX<br>(optional)||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|
## Get Card PIN Change Key status codes
Consult this table to see an explanation of what each status code means for the <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> 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.|
## HTTP 302 redirect codes
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 <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> again.|
|`||Token not valid or expired||Retry with a valid token. You may need to call <a href="ref:post_getcardpinchangekey" target="_blank">Get Card PIN Change Key</a> 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.|
## Commit Card PIN Change status codes
Consult the <a href="ref:post_commitcardpinchange" target="_blank">Commit Card PIN Change</a> endpoint reference for status codes and next steps.