> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grogov.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted checkout

> Send the payer to a GroGov checkout page instead of collecting card details yourself.

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

| Use | When |
| - | - |
| Hosted checkout | You want GroGov to collect the card, for example from a website or an email link. You hear about the result when the payer returns to your site |
| [Payments API](/guides/quickstart) | Your backend already collects card details or card tokens, and you need to refund, void, or list payments through the API |

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

<Steps>
  <Step title="Redirect">
    You [start a checkout](/guides/hosted-checkout/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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receipt">
    The payer sees the receipt. When they press **Done**, they go to your `return_url` with the signed result.
  </Step>
</Steps>

See [Results and signatures](/guides/hosted-checkout/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](/guides/hosted-checkout/results-and-signatures#verifying-the-signature).
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](/guides/sandbox-keys-and-portals) at the same time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.