Skip to main content
With hosted checkout, you send the payer’s browser to a checkout page that GroGov hosts. The payer enters their card on that page, and the result comes back to your site in the browser. You never handle card data, and you need no API key.

​
When to use hosted checkout

A hosted checkout is not a payment until the payer pays. It records your line items, your reference, and where to send the payer afterwards.

​
What the payer sees

1

Redirect

You start a checkout with a form post or a launch link. GroGov answers with a redirect, and the payer’s browser lands on the checkout page.
2

Confirm

The payer sees your reference_id, their name if you sent one, each line item, and the total. They can continue, or cancel and go back to your cancel_url if you set one.
3

Pay

The payer enters their card. The portal’s service fee, if it has one, is shown and added to the total. If the card is declined, the payer can try again on the same page.
4

Receipt

The payer sees the receipt. When they press Done, they go to your return_url with the signed result.
See Results and signatures for what comes back to you.

​
Limits

  • Amount. The agency can set a maximum for the portal. A checkout whose total, before the service fee, is above it fails with amount_exceeds_cap.
  • Link lifetime. A checkout link lasts 24 hours unless the agency set a different lifetime for the portal. You can ask for a shorter one with expires_at. A longer expires_at is shortened to the portal’s lifetime, not refused.
  • One payment per checkout. A link stops working once it has been paid, or when it expires. Opening a paid link shows Invalid or expired portal link, so start a new checkout if the payer needs to pay again.
  • Items. 1 to 100 line items. Each metadata is at most 8 KB.

​
Onboarding

Hosted checkout is available to every partner. GroGov configures it on the portal, so ask the agency you work with, or email support@grogov.us, for:
  1. Hosted checkout turned on for the portal. Until then, every request fails with portal_disabled.
  2. Your return and cancel addresses on the portal’s allowlist. GroGov only redirects to addresses on the list. You can also ask for a default return and cancel address, used when a request leaves them out.
  3. A signing secret, so you can verify the results.
  4. Your site’s origin, if you will show the checkout in an iframe.
Every address must use https. An http address is refused with invalid_return_url. GroGov gives you the portal_id to use. Ask for a sandbox portal at the same time.