Quickstart

1. Create a hosted session (server-side, with your Cognito admin token):

   curl

   curl -X POST https://api.govifi.io/v1/hosted-sessions \
     -H "Authorization: Bearer $GOVIFI_COGNITO_TOKEN" \
     -H "X-Payment-Account-Uid: $GOVIFI_PAYMENT_ACCOUNT_UID" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 14227,
       "currency": "USD",
       "description": "Utility bill — account #4471",
       "success_url": "https://yoursite.example/receipt?session_id={CHECKOUT_SESSION_ID}",
       "cancel_url": "https://yoursite.example/billing"
     }'

   Node.js

   const response = await fetch('https://api.govifi.io/v1/hosted-sessions', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.GOVIFI_COGNITO_TOKEN}`,
       'X-Payment-Account-Uid': process.env.GOVIFI_PAYMENT_ACCOUNT_UID,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       amount: 14227, // cents
       currency: 'USD',
       description: 'Utility bill — account #4471',
       success_url: 'https://yoursite.example/receipt?session_id={CHECKOUT_SESSION_ID}',
       cancel_url: 'https://yoursite.example/billing',
     }),
   });
   const session = await response.json();

   C#

   // client carries the Cognito admin token + the payment-account header:
   //   Authorization: Bearer <cognito-access-token>
   //   X-Payment-Account-Uid: <accountUid>
   var response = await client.PostAsJsonAsync("/v1/hosted-sessions", new
   {
       amount = 14227,
       currency = "USD",
       description = "Utility bill — account #4471",
       success_url = "https://yoursite.example/receipt?session_id={CHECKOUT_SESSION_ID}",
       cancel_url = "https://yoursite.example/billing",
   });
   var session = await response.Content.ReadFromJsonAsync<HostedSessionResponse>();

   The response includes session_id, the session’s client_secret (the browser credential — the component sends it as a Bearer token on every call), hosted_url, and embed_url.

2. Render the checkout. Easiest first: redirect to the hosted page.

   res.redirect(session.hosted_url);

   Or embed the component in your own page:

   <script
     src="https://cdn.govifi.com/v1/govifi-payment.js"
     integrity="sha384-REPLACE_WITH_PUBLISHED_HASH"
     crossorigin="anonymous"
   ></script>
   
   <govifi-payment
     session-id="cs_3oNkLp9aBcDeFgHi"
     client-secret="cs_3oNkLp9aBcDeFgHi_secret_..."
   ></govifi-payment>

   The current integrity hash for each release is published alongside the CDN bundle (govifi-payment.js.sri).

   Configure every attribute visually in the interactive designer and copy the result.

3. Confirm payment server-side with the checkout_session.completed webhook — don’t rely on the browser alone:

   app.post('/webhooks/govifi', (req, res) => {
     const event = verifySignature(req); // see the Webhooks guide
     if (event.event_type === 'checkout_session.completed') {
       fulfillOrder(event.data.session_id, event.data.payment);
     }
     res.json({ received: true });
   });

That’s a complete integration. From here:

• Create a hosted session — every session option
• Embed the component — layouts, frameworks, fields-only mode
• Webhooks — signature verification, retries