Skip to content

Commit eef68c5

Browse files
samblacklocksamblacklock
committed
feat: add spa-elastic-path-payments base files
feat: rewrite readme feat: declutter App.tsx feat: update readme tree
1 parent 8231a6b commit eef68c5

27 files changed

+3105
-0
lines changed

‎examples/spa-manual-payments/.gitignore

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?

‎examples/spa-manual-payments/README.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Manual Payment Processing SPA Example
2+
3+
This example showcases how to implement **manual payment gateway processing** with **Elastic Path Commerce Cloud** in a Single-Page Application (SPA) written in React. It builds on the `spa-guest-checkout` example, although omits a number of its features.
4+
5+
> **Heads-up:** This project focuses **exclusively** on manual payment processing workflows. It creates minimal test orders solely to demonstrate payment handling—cart management, product catalogs, customer accounts, etc. are kept deliberately simple and are not the focus.
6+
7+
Key capabilities demonstrated:
8+
9+
1. **Test Order Creation** – automatically creates incomplete orders with test products for payment processing demonstration.
10+
2. **Manual Payment Gateway** – processes payments using Elastic Path's manual payment gateway for scenarios like:
11+
• Bank transfers
12+
• Cash payments
13+
• Check payments
14+
• Custom payment workflows
15+
3. **Order State Management** – converts incomplete orders to complete orders after manual payment recording.
16+
4. **Payment Status Tracking** – displays real-time order and payment status updates with proper UI indicators.
17+
18+
> The example purposefully uses simplified order creation and minimal product selection to keep the focus on manual payment mechanics.
19+
20+
---
21+
22+
## Project Structure
23+
24+
```
25+
spa-manual-payments/
26+
├── index.html # Vite entry point
27+
├── src/
28+
│ ├── App.tsx # Main app orchestration & state management
29+
│ ├── components/
30+
│ │ ├── AppHeader.tsx # Authentication status & cart ID display
31+
│ │ ├── StepIndicator.tsx # Multi-step progress indicator
32+
│ │ ├── OrderCreator.tsx # Creates test orders for payment demo
33+
│ │ ├── ManualPayment.tsx # Manual payment processing form
34+
│ │ ├── OrderStatus.tsx # Order & payment status display
35+
│ │ └── OrderCompleteView.tsx # Success screen with reset functionality
36+
│ ├── hooks/
37+
│ │ ├── useAppInitialization.ts # App startup & authentication logic
38+
│ │ └── useOrderCreation.ts # Order creation workflow & state
39+
│ └── auth/
40+
│ ├── CartProvider.tsx # Basic cart initialization
41+
│ └── StorefrontProvider.tsx # Elastic Path client setup
42+
└── README.md # ← you are here
43+
```
44+
45+
## How It Works
46+
47+
### 1. Test Order Creation
48+
49+
`OrderCreator` automatically creates a test scenario:
50+
51+
```tsx
52+
// Creates cart → adds test product → checkout → incomplete order
53+
const createIncompleteOrder = async () => {
54+
const products = await getByContextAllProducts()
55+
const selectedProduct = products.data.find(/* stock logic */)
56+
// ... cart creation, checkout, order creation
57+
}
58+
```
59+
60+
This generates an incomplete order ready for manual payment processing.
61+
62+
### 2. Manual Payment Processing
63+
64+
`ManualPayment` captures payment details and processes them:
65+
66+
```tsx
67+
const paymentData = {
68+
gateway: "manual",
69+
method: "purchase",
70+
// if the user supplies a reference
71+
paymentmethod_meta: {
72+
custom_reference: paymentReference,
73+
name: "Manual Payment",
74+
},
75+
}
76+
77+
await paymentSetup({
78+
path: { orderID: order.id },
79+
body: { data: paymentData },
80+
})
81+
```
82+
83+
### 3. Status Display
84+
85+
`OrderStatus` shows order and payment status.
86+
87+
---
88+
89+
## Running the Example Locally
90+
91+
1. **Install deps** (from the repo root):
92+
93+
```bash
94+
pnpm i # or npm install / yarn
95+
```
96+
97+
2. **Set environment variables** – create a `.env` file in `examples/spa-manual-payments` (or export in your shell):
98+
99+
```
100+
VITE_APP_EPCC_ENDPOINT_URL=https://YOUR_EP_DOMAIN.elasticpath.com
101+
VITE_APP_EPCC_CLIENT_ID=YOUR_CLIENT_ID
102+
```
103+
104+
3. **Start Vite dev server**:
105+
106+
```bash
107+
pnpm --filter spa-manual-payments dev
108+
```
109+
110+
## Learn More
111+
112+
- [Manual Payment Gateway Documentation](https://elasticpath.dev/docs/api/carts/cart-management)
113+
- [Order Management with Elastic Path](https://elasticpath.dev/docs/api/carts/cart-management)
114+
- [Payment Processing APIs](https://elasticpath.dev/docs/api/carts/cart-management)

‎examples/spa-manual-payments/eslint.config.js

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import js from '@eslint/js'
2+
import globals from 'globals'
3+
import reactHooks from 'eslint-plugin-react-hooks'
4+
import reactRefresh from 'eslint-plugin-react-refresh'
5+
import tseslint from 'typescript-eslint'
6+
7+
export default tseslint.config(
8+
{ ignores: ['dist'] },
9+
{
10+
extends: [js.configs.recommended, ...tseslint.configs.recommended],
11+
files: ['**/*.{ts,tsx}'],
12+
languageOptions: {
13+
ecmaVersion: 2020,
14+
globals: globals.browser,
15+
},
16+
plugins: {
17+
'react-hooks': reactHooks,
18+
'react-refresh': reactRefresh,
19+
},
20+
rules: {
21+
...reactHooks.configs.recommended.rules,
22+
'react-refresh/only-export-components': [
23+
'warn',
24+
{ allowConstantExport: true },
25+
],
26+
},
27+
},
28+
)

‎examples/spa-manual-payments/index.html

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!doctype html>
2+
<html lang="en" class="h-full">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>SPA Manual Payments Example - Elastic Path</title>
8+
</head>
9+
<body class="h-full bg-gray-50">
10+
<div id="root" class="h-full"></div>
11+
<script type="module" src="/src/main.tsx"></script>
12+
</body>
13+
</html>

‎examples/spa-manual-payments/package.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "spa-manual-payments",
3+
"private": true,
4+
"version": "0.0.0",
5+
"type": "module",
6+
"scripts": {
7+
"dev": "vite",
8+
"build": "vite build",
9+
"lint": "eslint .",
10+
"preview": "vite preview"
11+
},
12+
"dependencies": {
13+
"@epcc-sdk/sdks-shopper": "workspace:*",
14+
"react": "^18.3.1",
15+
"react-dom": "^18.3.1"
16+
},
17+
"devDependencies": {
18+
"@eslint/js": "^9.9.0",
19+
"@tailwindcss/vite": "^4.1.7",
20+
"@types/react": "^18.3.3",
21+
"@types/react-dom": "^18.3.0",
22+
"@vitejs/plugin-react": "^4.3.1",
23+
"eslint": "^9.9.0",
24+
"eslint-plugin-react-hooks": "^5.1.0-rc.0",
25+
"eslint-plugin-react-refresh": "^0.4.9",
26+
"globals": "^15.9.0",
27+
"tailwindcss": "^4.1.7",
28+
"typescript": "^5.5.3",
29+
"vite": "^5.4.1"
30+
}
31+
}

0 commit comments

Comments
 (0)