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.

📘

Note

You must complete PCI-DSSPCI-DSS - Payment Card Industry Data Security Standards. A set of standards that business entities must fulfill before handling sensitive customer data such as credit-card numbers, CVVs, and expiry dates. 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.

Options

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
  • AOCAOC - Attestation of Compliance. A self-assessment questionnaire that measures an organization's conformity to Payment Card Industry Data Security Standards (PCI-DSS)., 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:

  • Submitter ID

Workflow

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 CADCAD - Card identifier (card_id). A Galileo-generated identifier for a card. This number is used internally and is not presented to customers, merchants, or card networks. You can use the CAD instead of the PAN if you are not PCI compliant. Retrieve the CAD from the RDFs or the responses for Get Account Cards or Get Card. (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 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:

ElementDescription
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 forms

These sample forms are 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 form unless you are on a Galileo AWS instance.

Non-AWS form
<form enctype="application/x-www-form-urlencoded" action="http://secure-agserv.ua.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>
AWS form
<form enctype=\"application/x-www-form-urlencoded\" action=\"https://agserv-[clientname].cv.gpsrv.com/agserv/direct/pin/en_US/" 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>

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.

Success:yourdomain.com/r=0
Failure:yourdomain.com?r=-2&e={"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"}}

6. 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 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.

Galileo setup

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

ParameterDescription
GGDPAEnable direct POST access
GGHDR
(optional)
A set of key/value pairs for additional response headers when using no-redirect mode
GGKEH
(optional)
Number of times a PIN-set token can be used. Default: 5
GGKEX
(optional)
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 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.

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 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 HTML POST 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?