Checkout Website

1. Overview

The Online Payment Website is a customer-facing hosted checkout solution that allows merchants' end customers to make payments via a web interface. It provides a secure, PCI-compliant payment form that communicates with our Online Transaction Microservice.

Rename note: the checkout and hosted-payment APIs still use legacy merchantId field names in parts of the wire contract. On this page, those values should be read as the concrete location id selected by the caller.

1.1 Launch-safe wording

Safe statements:

hosted checkout and hosted payment flows accept a location-scoped identifier through legacy merchantId fields where the current API still uses that name
the gateway-hosted surface remains the PCI-friendly integration path
the rename does not change the customer-facing hosted checkout experience

Unsafe statements:

that hosted flows are blocked on the organization/location rename
that the old merchant-first naming is still the preferred model for new integrations
that any legacy merchantId example on this page represents something other than the concrete selected location

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 (Priority)

A simple, embeddable payment button for sale-only transactions. This has the simplest certification process (Hosted Payment 2.0) and should be the first certified integration.

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 hosted payment page or opens modal
Success/failure callback handling

Certification: Hosted Payment 2.0 (sale only). Described as a "really simple certification process." Fastest path to a certified payment integration.

2.3 Embeddable Payment iFrame (Fast-Tracked)

An iframe-based payment form that merchants embed directly in their website. This is being fast-tracked for speed of implementation.

Implementation order:

First: Hosted Payments iFrame (fast to implement)
Then: Certified backend portal for managing transactions from hosted payments

Card data stays within the hosted iFrame (TSYS domain), reduces PCI scope
Seamless visual integration via merchant theming (logo, colors)
Secure cross-origin communication (postMessage API)
Mobile-responsive payment form

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://pay.pinpointgateway.com/c/cs_live_abc123def456",
  "expiresAt": "2026-03-03T16:00:00Z",
  "status": "pending"
}

3.1 Docs-side closeout checklist

Treat this page as closure-grade from the repo side only if readers can infer that:

the hosted checkout examples are launch-safe as written today
legacy merchantId naming in the request body is wire compatibility only
support can share this page without implying that merchant-first naming is the desired long-term model

Webhook Callback

POST <merchant webhook URL>
Content-Type: application/json
X-Pinpoint-Signature: sha256=<HMAC signature>

{
  "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

Supported Payment Methods

Method	Priority	Notes
Credit card (Visa, MC, Amex, Discover)	P0 (Launch)	Via TransIT
Debit card	P0 (Launch)	Via TransIT
ACH / Bank transfer	P1 (Post-launch)	Via TransIT ACH support
Card on file (tokenized)	P1 (Post-launch)	Using TransIT Guardian tokens
Apple Pay	P2 (Future)	Requires separate CNP certification first
Google Pay	P2 (Future)	Requires separate CNP certification first

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)

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

No card data touches our servers, card fields use tokenization (client-side encryption or TransIT.js if available)
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)

Certification Note: The Hosted Payment Button (sale-only) has the simplest certification process (Hosted Payment 2.0) and should be pursued first. Each new payment method or capability requires its own certification. Adding new features does not extend existing certifications.

5. Technical Stack

Layer	Technology
Framework	Next.js 14+ (App Router, SSR for checkout pages)
Language	TypeScript
Styling	Tailwind CSS
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 cancelled
`/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: Cloud Run (SSR for dynamic checkout pages)
Domain: pay.pinpointgateway.com (TBD)
CDN: Cloud CDN for static assets
TLS: Managed certificate via Cloud Load Balancer

1. Overview​

1.1 Launch-safe wording​

2. Checkout Flows​

2.1 Hosted Checkout Page (Primary)​

2.2 Hosted Payment Button (Priority)​

2.3 Embeddable Payment iFrame (Fast-Tracked)​

3. Checkout Session​

Create Session Request (Server-to-Server)​

Create Session Response​

3.1 Docs-side closeout checklist​

Webhook Callback​

4. Payment Form Features​

Supported Payment Methods​

Form Fields​

UX Requirements​

Security​

5. Technical Stack​

6. Pages​

7. Merchant Customization​

8. Deployment​