Checkout Website

1. Overview

The Online Payment Website is a customer-facing hosted checkout solution that allows a seller's end customers to make payments via a web interface. It provides a secure, PCI-compliant payment form that communicates with our Online Transaction Microservice. Hosted checkout and hosted payment flows are location-scoped; the gateway-hosted surface remains the PCI-friendly integration path.

2. Checkout Flows

2.1 Hosted Checkout Page (Primary)

Merchants redirect their customers to our hosted checkout page. This is the simplest and most PCI-friendly integration.

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Merchant    │     │  Hosted Checkout  │     │  Online Txn     │
│  Website     │     │  (our website)    │     │  Microservice   │
└──────┬───────┘     └───────┬──────────┘     └───────┬─────────┘
       │                     │                        │
       │ 1. Create session   │                        │
       │    (server-to-      │                        │
       │     server via SDK) │                        │
       │────────────────────────────────────────────>│
       │                     │                        │
       │ 2. Receive checkout │                        │
       │    URL + sessionID  │                        │
       │<────────────────────────────────────────────│
       │                     │                        │
       │ 3. Redirect customer│                        │
       │    to checkout URL  │                        │
       │────────────────────>│                        │
       │                     │                        │
       │                     │ 4. Customer enters     │
       │                     │    card details        │
       │                     │                        │
       │                     │ 5. Submit payment      │
       │                     │───────────────────────>│
       │                     │                        │
       │                     │ 6. Process via         │
       │                     │    Processing Service  │
       │                     │                        │
       │                     │ 7. Display result      │
       │                     │<───────────────────────│
       │                     │                        │
       │ 8. Redirect back to │                        │
       │    merchant with    │                        │
       │    result params    │                        │
       │<────────────────────│                        │
       │                     │                        │
       │ 9. Webhook callback │                        │
       │    (server-to-      │                        │
       │     server)         │                        │
       │<────────────────────────────────────────────│

2.2 Hosted Payment Button

A simple, embeddable payment button for sale-only transactions. The online-txn hosted-payment endpoints create a reusable button record and return a JavaScript snippet plus a https://pay.peakgateway.co/b/{buttonId} checkout URL.

Embeddable JavaScript snippet / web component
Sale-only transaction flow (no refund/void through button)
Minimal integration required, merchants add a single <script> tag
Redirects to the hosted button route, which creates a checkout session
Success/failure callback handling

2.3 Hosted checkout

Gateway-hosted card entry uses checkout sessions and the configured hosted payment provider. The checkout submits payment directly; it does not expose a separate browser-callable tokenization API or return reusable payment tokens.

Card data stays within the Gateway-hosted checkout surface
Merchant theming supports logos and colors
The payment form is mobile-responsive
Wallet payment endpoints are available when Apple Pay or Google Pay is enabled for the session and browser/device context

3. Checkout Session

Create Session Request (Server-to-Server)

POST /api/v1/checkout/sessions
Authorization: Bearer <api-key>

{
  "merchantId": "loc_abc123",
  "amount": 2500,
  "currency": "USD",
  "description": "Order #12345",
  "customerEmail": "customer@example.com",
  "successUrl": "https://merchant.com/payment/success",
  "cancelUrl": "https://merchant.com/payment/cancel",
  "webhookUrl": "https://merchant.com/webhooks/payment",
  "metadata": {
    "orderId": "12345",
    "customField": "value"
  },
  "expiresIn": 3600
}

Create Session Response

{
  "sessionId": "cs_live_abc123def456",
  "checkoutUrl": "https://checkout.peakgateway.co/c/cs_live_abc123def456",
  "expiresAt": "2026-03-03T16:00:00Z",
  "status": "pending"
}

Webhook Callback

POST <merchant webhook URL>
Content-Type: application/json
X-Pinpoint-Signature: <hex HMAC-SHA256 signature (no scheme prefix)>

{
  "event": "payment.completed",
  "sessionId": "cs_live_abc123def456",
  "transactionId": "txn_789xyz",
  "amount": 2500,
  "currency": "USD",
  "status": "COMPLETED",
  "completedAt": "2026-03-03T15:05:23Z",
  "metadata": {
    "orderId": "12345"
  },
  "organizationId": "org_abc123"
}

amount is in minor units (cents). status is COMPLETED for payment.completed and DECLINED for payment.declined (declines also carry amount, currency, and an optional message). metadata echoes the session's metadata when present.

4. Payment Form Features

Hosted Checkout Payment Methods

Method	Current behavior	Notes
Credit card (Visa, MC, Amex, Discover)	Supported	Card entry posts through Gateway checkout processing
Debit card	Supported	Uses the same card payment path
Saved payment method / card on file	Supported	Uses a saved `paymentMethodId` or `tokenId` when the session/customer context allows it
Apple Pay	Supported when the current route and organization capability permit it	Session APIs validate the Apple Pay merchant session and process Apple Pay payment tokens; availability requires an active card-not-present route with Apple-capable adapter support, the organization Apple Pay rollout, and a completed Apple Pay registration
Google Pay	Supported when enabled	Session APIs provide Google Pay config and process Google Pay payment tokens
ACH / bank transfer	Not a hosted-checkout processable method	ACH values are not accepted as the only processable hosted-checkout method today

Form Fields

Card number (with Luhn validation + BIN detection)
Expiration date (MM/YY)
CVV (3 or 4 digits)
Cardholder name
Billing ZIP code (for AVS)
Email (for receipt)
Saved-card selector when a customer has an eligible saved payment method
Apple Pay and Google Pay buttons when the session allows them and the device or browser can render them

UX Requirements

Mobile-responsive design
Real-time card type detection (Visa/MC/Amex icon)
Inline field validation
Loading state during processing
Clear success/failure messaging
Merchant branding (logo, colors) loaded from merchant config
Accessibility (WCAG 2.1 AA)

Security

Merchant servers do not receive PAN; card data is collected by Gateway-hosted checkout, Elements, or iframe surfaces and tokenized or processed by gateway services under PCI scope
CSP headers to prevent XSS
CSRF protection on form submission
Rate limiting on payment attempts
Session expiration (configurable, default 1 hour)
3D Secure integration (if required by card network)

5. Technical Stack

Layer	Technology
Framework	React 19 + Vite 7 (`rolldown-vite`)
Language	TypeScript 6
Styling	Tailwind CSS 4
Build	Bazel (via rules_js)
Testing	Vitest + Playwright (E2E)

6. Pages

Route	Purpose
`/c/{sessionId}`	Checkout page, renders payment form for a session
`/c/{sessionId}/success`	Payment success confirmation
`/c/{sessionId}/cancel`	Payment canceled
`/c/{sessionId}/expired`	Session expired
`/c/{sessionId}/receipt`	Digital receipt (if email receipt enabled)

7. Merchant Customization

Merchants can configure via the Management Portal:

Setting	Description
Logo URL	Displayed on checkout page
Brand color	Primary color for buttons and accents
Business name	Displayed as merchant name on checkout
Receipt email	Whether to send email receipts to customers
Custom success message	Message shown after successful payment

8. Deployment

Hosting: Cloudflare Pages static build from websites/checkout
Checkout domain: checkout.peakgateway.co
Staging checkout domain: staging-checkout.peakgateway.co
Payment API / hosted-button domain: pay.peakgateway.co
Backend APIs: online-txn Cloud Run service behind the public payment API

1. Overview​

2. Checkout Flows​

2.1 Hosted Checkout Page (Primary)​

2.2 Hosted Payment Button​

2.3 Hosted checkout​

3. Checkout Session​

Create Session Request (Server-to-Server)​

Create Session Response​

Webhook Callback​

4. Payment Form Features​

Hosted Checkout Payment Methods​

Form Fields​

UX Requirements​

Security​

5. Technical Stack​

6. Pages​

7. Merchant Customization​

8. Deployment​