Pay.gov
On this page
This topic explains how to configure Pay.gov, the U.S. Treasury’s collection service, as a payment provider in StoreConnect. Shoppers are redirected from your store to Pay.gov’s hosted page to pay by card, then return to your store. To take PayPal instead of card, set payment_type to PAYPAL (see API Options). ACH bank debit will follow in a later release.
What you need
- A Pay.gov Hosted Collection Pages cash flow application, set up by Pay.gov. Pay.gov supplies the TCS application ID.
- The TCS client certificate and the matching private key, issued through Pay.gov.
- Your store’s outbound IP addresses, whitelisted by Pay.gov. StoreConnect support can provide these addresses.
Make all requests to Pay.gov through your agency’s Pay.gov Agency Implementation liaison.
Configure Pay.gov in StoreConnect
- Open StoreConnect and go to Settings > Payments > Payment providers. If Pay.gov is not listed under Provider after a StoreConnect upgrade, open the Console, run the picklist manager, and apply the missing value for Payment Provider > Provider first. The value to apply has the API name
PayGovand the label Pay.gov. -
Select New. Complete the fields as follows, then Save:
StoreConnect field Select or enter Name Pay.gov Provider Select Pay.gov from the list API Mode sandbox(Pay.gov’s QA environment, qa.pay.gov) orproduction(www.pay.gov)API Key Not used by Pay.gov, but required by StoreConnect. Enter x.API Secret Not used by Pay.gov, but required by StoreConnect. Enter x.API Options See API Options.
API Options
The API Options field uses YAML format. Each option goes on its own line.
| Option | Required | Value |
|---|---|---|
tcs_app_id |
Yes | The Pay.gov TCS application ID for your Hosted Collection Pages cash flow application, supplied by your Pay.gov liaison. |
client_certificate |
Yes | The PEM text of the TCS client certificate issued through Pay.gov (Treasury’s certificate authority). |
client_private_key |
Yes | The PEM text of the private key for that certificate. |
payment_type |
No | The one payment type Pay.gov offers the shopper: PLASTIC_CARD (card, the default) or PAYPAL. Leave it out to take card payments. ACH is not supported yet and shows an error at checkout. |
language |
No | The Pay.gov payment page language code. The default is en. |
Example:
```yaml
tcs_app_id: YOUR_TCS_APP_ID client_certificate: |- —–BEGIN CERTIFICATE—– (paste contents of your TCS certificate .pem here) —–END CERTIFICATE—– client_private_key: |- —–BEGIN PRIVATE KEY—– (paste contents of your TCS private key .pem here) —–END PRIVATE KEY—– payment_type: PLASTIC_CARD language: en ```
Omit payment_type and language if you do not use them.
:::tip When pasting multi-line certificate content into the API Options field, every line of the certificate must be indented consistently beneath the key name. Prepare the YAML in a text editor before pasting. :::
Keep the certificate and private key confidential. Never share them in email, tickets or screenshots.
After you save the provider, Pay.gov appears as a payment option at checkout.
What shoppers see
- At checkout, the shopper chooses Pay.gov and selects Pay Now. StoreConnect starts the Pay.gov payment and puts the cart into payment processing, so the items in it cannot change while the shopper is away.
- The shopper pays on Pay.gov’s page.
- The shopper returns to your store and sees a processing page while StoreConnect completes the payment with Pay.gov and creates the order.
- The shopper sees your store’s order confirmation.
Pay.gov takes the money only when StoreConnect completes the payment in step 3. Refreshing the processing page, or going back to it, does not complete the payment a second time. If the shopper selects Pay Now again before paying, they return to the same Pay.gov payment rather than starting a new one.
The Payment record on the order stores the Pay.gov Tracking ID, which matches the transaction in Transaction Search on Pay.gov’s Agency Collections site.
If the payment does not go through, the shopper returns to the payment step with a message, and the cart is released so they can pay again or choose another payment method:
| What happened | Message the shopper sees |
|---|---|
| Pay.gov declined the card | “Your card was declined by Pay.gov. Please try another payment method.” |
| The shopper cancelled on Pay.gov’s page | “The payment was cancelled on Pay.gov.” |
If the shopper leaves Pay.gov’s page without paying or cancelling, nothing is charged. StoreConnect releases the cart three hours after the Pay.gov payment started, once Pay.gov can no longer complete it.
When a payment’s outcome is unclear
Sometimes StoreConnect asks Pay.gov to complete a payment but never gets the answer, for example when the request times out. Pay.gov may have taken the money, so StoreConnect does not tell the shopper the payment failed. StoreConnect holds the payment as unresolved instead:
- The shopper sees “We’re still checking whether your payment went through, so please don’t pay again. Check your email or your orders page for an update, or contact us if you don’t hear back.”
- The cart stays in payment processing, so the items in it cannot be changed.
- Another Pay.gov payment under the same order number is refused with the same message until the first is settled.
StoreConnect cannot ask Pay.gov what happened to the payment, so an unresolved Pay.gov payment stays that way until StoreConnect Support settles it. If a shopper reports the “still checking” message:
- Open Transaction Search on Pay.gov’s Agency Collections site.
- Search for the payment, and note whether Pay.gov collected the money.
- Raise a support case. Include the order number and what Transaction Search shows.
Support then records the payment as paid, or releases the cart so the shopper can pay again.
Production mode
Set API Mode to production to take live payments at checkout. Payments for an existing order, such as an order balance paid through a Salesforce order payment link, are not available in production yet. In production mode, those payments show “Pay.gov production payments are only available for checkout payments.” Use a different payment provider for them.
Limits
- Pay.gov is available for USD stores only.
- Refunds and cancellations are not available through StoreConnect for Pay.gov. Process them in Transaction Search on Pay.gov.
- Card payments complete immediately. ACH debit support is coming in a later release.
- Recurring and subscription payments are not available through Pay.gov.
- Pay.gov’s regular maintenance window is Sunday 2:00 to 8:00 AM Eastern. Payments may fail during this time.
Testing
- Set API Mode to
sandbox. - Use Pay.gov’s “Agency Guide to Application Testing” for test card numbers and the amounts that trigger specific outcomes. For example, $3.00 approves and $3.01 declines.
:::warning Never enter real card or bank details in sandbox mode. Pay.gov reports this to Treasury as a security incident. :::
See testing orders for more on testing your store and checkout experience. When you are ready, change API Mode to production and use your production credentials. See Production mode for what production supports.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.