Skip to content

About

Payoneer Cards Component Demo (Web SDK)

Resources

Stars

4 stars

Watchers

4 watching

Forks

Repository files navigation

Payoneer Cards Component Demo

This project demonstrates how to integrate the Payoneer Checkout Web SDK in both embedded and hosted payment experiences. It comes with a full-featured playground that bootstraps list sessions against Payoneer sandbox endpoints, lets you tweak SDK configuration on the fly, and visualizes the behaviour of the rendered payment components.

Key Features

  • Embedded checkout builder with tabs for SDK base settings, advanced callbacks, cart data, customer data, UI theming, and shareable URLs.
  • Hosted checkout flow simulator that walks through environment selection, cart setup, customer address capture, and final review before launching the hosted payment page.
  • Session management powered by Zustand that persists configuration in storage and can optionally mirror state into the URL for easy sharing.
  • Charge flow event logger and demo card numbers to help debug callback timing and test network-specific payment methods.

Getting Started

Prerequisites

  • Node.js 20.19+ or 22.12+ (required by Vite 8). The optional Express HTTPS mode (EXPRESS_HTTPS=true, used for real wallet testing) pulls in vite-plugin-mkcert, which needs Node ≥ 22.19. On older Node you will see an EBADENGINE install warning, and should use plain HTTP (no wallets) or upgrade Node.

  • npm 9+ (ships with current Node LTS releases).

  • Ability to reach the Payoneer sandbox or integration domains (*.oscato.com). Corporate VPN access may be required depending on your network.

Installation

npm install
npm run dev

The dev server runs on http://localhost:3000 (pinned in vite.config.ts). Because the router is configured with the basename /cards-component-demo, open http://localhost:3000/cards-component-demo/ to use the app locally.

Available Scripts

  • npm run dev - start the Vite development server with hot module replacement.

  • npm run build - type-check and bundle the app for production output in dist/.

  • npm run preview - serve the built assets locally to validate the production bundle.

  • npm run lint - run ESLint across the project.

Using the Demo

Flow Selection

The landing page presents two entry points:

  • Embedded Checkout Flow: renders Payoneer Checkout components directly within the demo and lets you experiment with SDK options.
  • Hosted Checkout Flow: guides you through preparing a list session before redirecting to the hosted Payoneer payment page.

Use the header navigation to switch flows or return to the chooser.

Embedded Checkout Builder

  • The configuration panel drives the list session payload and SDK initialization. Tabs expose base SDK options (environment, preload list, refetch behaviour), advanced callback wiring, cart items, customer addresses, and UI styling tokens.

  • Session data is generated through CheckoutApiService.generateListSession, which posts to https://api.{env}.oscato.com/checkout/session. The default environment is sandbox, with an additional checkout.integration division available.

  • Payment methods are mounted dynamically based on the list response. The event logger at the bottom captures SDK callbacks, charge flow events, and metadata to help validate integration behaviour.

  • Toggle URL sharing to persist both checkout and configuration stores into the location hash, enabling copyable deep links that reproduce the current setup.

  • DemoCardNumbers surfaces network-specific test PANs that work with the sandbox to simulate successful charges.

Hosted Checkout Simulator

  • A multi-step wizard backed by useHostedConfigurationStore collects the same cart and customer information, tailored for the hosted integration path.

  • Upon confirmation, the flow builds a hosted-style list request (including callback URLs derived from the running origin), calls the list session endpoint, and finally redirects to https://resources.{env}.oscato.com/paymentpage/v6/responsive.html.

  • Errors encountered while creating the list session or launching the hosted page surface inline with remediation guidance.

Observability and Debugging

  • App.tsx can initialize Honeycomb OpenTelemetry, but it is off by default. This is a public demo, so it never phones home unless you opt in. To enable tracing, set BOTH VITE_ENABLE_TELEMETRY=true and VITE_TELEMETRY_ENDPOINT=<your collector URL> in .env. No collector URL is baked into the source.
  • The charge flow event logger is sticky at the bottom of the embedded flow and can be expanded to inspect event payloads.

Configuration and Environment Notes

  • Environment, division and merchant code mappings are defined in src/features/embeddedCheckout/constants/checkout.ts. To test against an additional Payoneer environment, add it to both Divisions and MerchantCodes there, or override endpoints.

  • Callback URLs for the hosted experience are derived from the current origin in src/features/hostedCheckout/constants/hostedPaymentConfig.ts. Adjust them if you deploy behind a different base path.

  • If your network blocks cross-origin requests to Payoneer domains, the list session calls will fail. Use the browser console to inspect errors and confirm connectivity.

  • The router basename (/cards-component-demo) keeps relative paths working when the build is deployed to GitHub Pages or a similar static host that serves assets from a subdirectory. Update the basename in src/App.tsx if you deploy at root.

Local Development Mode

You can test local changes to checkout-web and checkout-web-stripe in real-time without deploying to remote servers. The app automatically detects local development servers and seamlessly switches between local and CDN sources.

Quick Start

  1. Start local servers (optional - run one or both):

    # In checkout-web directory
    npm run dev  # Runs on port 8700
    
    # In checkout-web-stripe directory
    npm run dev  # Runs on port 8991
  2. Start this demo app:

    npm run dev  # Runs on port 3000
  3. Check local mode status:

    • Open the demo at http://localhost:3000/cards-component-demo/
    • Look for the Local Development Mode card (only visible on localhost)
    • Server status indicators show which local servers are detected
    • Click Refresh Servers if you start a server after loading the page

How It Works

  • Auto-detection: The app checks if local servers are running on ports 8700 and 8991 using health checks
  • Mixed mode support: Run just one local server or both - the app independently uses local versions when available and falls back to CDN for the rest
    • Example: Test checkout-web-stripe changes with production checkout-web
    • Example: Test checkout-web changes with production stripe integration
  • Vite proxy: Requests to /local-checkout-web and /local-checkout-web-stripe are proxied through the dev server to avoid CORS issues
  • Meta-info rewriting: Script URLs in meta-info.json files are automatically rewritten to point to local proxy paths
  • Fetch override: When local stripe is available, a global fetch override redirects stripe meta-info requests to the local server (works even with CDN checkout-web)

Troubleshooting

Local servers not detected?

  • Verify servers are running: curl http://localhost:8700/build/meta-info.json and curl http://localhost:8991/meta-info.json
  • Click the Refresh Servers button
  • Check browser console for errors

Changes not reflecting?

  • Hard refresh the browser (Cmd+Shift+R / Ctrl+Shift+R)
  • The dev servers auto-rebuild, but browser cache may need clearing

Switching between local and CDN checkout-web?

  • When you start/stop the checkout-web dev server (port 8700), you'll need to refresh the page to reload the SDK script
  • Switching stripe (port 8991) works dynamically without page refresh thanks to the fetch override

Stripe components not loading locally?

  • Verify checkout-web-stripe is running on port 8991
  • Check Network tab for requests to /local-checkout-web-stripe/

Express Checkout Demo

Open http://localhost:3000/cards-component-demo/express to test the Express Checkout flow. It is the "PageTurner" storefront: a listing, product detail, cart, a unified checkout page (customer details + order summary alongside stacked payment methods: the real Express wallet element plus the real Payoneer card drop-in), and success/failure result views. A default public merchant-application token (the same one used by the checkout-web-stripe express.html BE integration sample) is baked in, so the flow works out of the box. To use a different token, create a .env file and set VITE_EXPRESS_CLIENT_ID, or override it live in the config sheet. The backend validates clientId server-side, so this value is not a secret. Set the country in the config sheet; it defaults to US. The sheet also lets you switch the environment between checkout.integration (the default) and sandbox; both the card LIST and the express token run on the selected env. checkout-web derives the express GET /pci/v1/express host from env and injects the result into the element (the host supplies no URL), and the browser cannot call that OPG host directly from https://localhost (no CORS), so the demo's dev-only fetch shim reroutes the cross-origin call through OPG_PROXY_TARGET server-to-server. This requires running the local checkout-web + checkout-web-stripe (see LOCAL_DEVELOPMENT.md), since the published CDN builds predate the SDK-owned express fetch and the per-account Stripe cache.

Wallets refuse to render over plain HTTP, and Google Pay's canMakePayment() also refuses over an untrusted certificate. Chrome flags a self-signed cert as "DANGEROUS" and disables the Payment Request API, so the Express element renders no wallet button even though the card form still shows a Google Pay tab. For real-device wallet testing, start the demo with EXPRESS_HTTPS=true npm run dev (this enables vite-plugin-mkcert, which serves https://localhost:3000 with a browser-trusted cert; the first run installs a local CA and may prompt for your password), then open https://localhost:3000/cards-component-demo/express. Google Pay works on trusted https://localhost in Chrome without domain registration. Apple Pay also requires a Stripe-registered HTTPS domain. Front the dev server with a tunnel such as ngrok http 3000, then register the tunnel domain with Stripe.

The browser cannot call the OPG host directly from https://localhost because of CORS. The /opg-proxy development route forwards those requests server-to-server. To target another environment, start the demo with a custom target, for example OPG_PROXY_TARGET=https://api.sandbox.oscato.com npm run dev.

Express Checkout works with the existing local development mode. Run checkout-web on port 8700 and checkout-web-stripe on port 8991 as described above.

Use the ⚙ button in the bottom-right corner to change walletMode, each Apple Pay and Google Pay setting in expressWallets (auto, always, or never), expressOperationType (defaults to charge), and the Express capture via expressDeferral (Immediate leaves it unset; Deferred needs preset). These settings are applied when the Express Checkout Element is created, so each change remounts the element.

'Fraunces' (the storefront serif) is loaded from Google Fonts. 'Avenir Next World' is a licensed Payoneer brand font that is not bundled here, so the sans falls back to the system stack. This affects appearance only.

Tech Stack

  • React 19 with React Router 7 for routing.
  • TypeScript throughout the application.
  • Vite 8 for build tooling and local development.
  • Tailwind CSS 4 (Vite plugin) for utility-first styling.
  • Zustand for state management with persistence helpers.
  • Honeycomb OpenTelemetry SDK for client instrumentation.

About

Payoneer Cards Component Demo (Web SDK)

Resources

Stars

4 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages