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 Embeddable Elements and iFrame

Gateway-hosted card entry can be embedded in merchant sites through the Elements card route or hosted-payment iframe sessions. Session-scoped tokenization posts to /api/v1/checkout/sessions/{sessionId}/tokenize, and the TypeScript and Kotlin SDKs expose this as checkoutSessions.tokenize(...).

• Card data stays within Gateway-hosted checkout, Elements, or iframe surfaces
• Seamless visual integration via merchant theming (logo, colors)
• Secure cross-origin communication (postMessage API)
• Mobile-responsive payment form
• Wallet payment endpoints are available on checkout sessions 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": "succeeded",
  "metadata": {
    "orderId": "12345"
  },
  "completedAt": "2026-03-03T15:05:23Z"
}

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 enabled	Session APIs validate the Apple Pay merchant session and process Apple Pay payment tokens
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