Skip to content

Commit 3522240

Browse files
rnediumrnedium
committed
Add Swish Documentation
1 parent 4763567 commit 3522240

File tree

5 files changed

+563
-0
lines changed

5 files changed

+563
-0
lines changed

‎client/components/swishPayments/html/README.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Swish One-Time Payment Integration
2+
3+
This example demonstrates how to integrate Swish payments using PayPal's v6 Web SDK. Swish is Sweden's leading mobile payment method that allows customers to pay directly from their mobile banking app.
4+
5+
## Architecture Overview
6+
7+
This sample demonstrates a complete Swish integration flow:
8+
9+
1. Initialize PayPal Web SDK with the Swish component
10+
2. Check eligibility for Swish payment method
11+
3. Create Swish payment session with required payment fields
12+
4. Validate customer information before initiating payment
13+
5. Process payment through Swish popup flow
14+
6. Handle payment approval, cancellation, and errors
15+
16+
## Features
17+
18+
- Swish one-time payment integration
19+
- Full name field validation
20+
- Popup payment flow
21+
- Eligibility checking for Swish
22+
- Error handling and user feedback
23+
24+
## Prerequisites
25+
26+
Before running this demo, you'll need to set up accounts and configure your development environment.
27+
28+
### 1. PayPal Developer Account Setup
29+
30+
1. **PayPal Developer Account**
31+
- Visit [developer.paypal.com](https://developer.paypal.com)
32+
- Sign up for a developer account or log in with existing credentials
33+
- Navigate to the **Apps & Credentials** section in your dashboard
34+
35+
2. **Create a PayPal Application** (or configure the default application)
36+
- Click **Create App**
37+
- Name your app
38+
- Select **Merchant** under **Type**
39+
- Choose the **Sandbox** account for testing
40+
- Click **Create App** at the bottom of the modal
41+
- Note your **Client ID** and **Secret key** under **API credentials** for later configuration of the `.env` file
42+
43+
3. **Enable Swish Payment**
44+
- Visit [sandbox.paypal.com](https://www.sandbox.paypal.com)
45+
- Log in with your **Sandbox** merchant account credentials
46+
- Navigate to **Account Settings** by clicking the profile icon in the top right corner
47+
- Select **Payment methods** from the left sidebar
48+
- Find **Swish** in the payment methods and enable it
49+
50+
### 2. System Requirements
51+
52+
- Node.js version 20 or higher
53+
- Server running on port 8080 (see `server/node/` directory)
54+
55+
## Running the Demo
56+
57+
### Server Setup
58+
59+
1. **Navigate to the server directory:**
60+
61+
```bash
62+
cd server/node
63+
```
64+
65+
2. **Install dependencies:**
66+
67+
```bash
68+
npm install
69+
```
70+
71+
3. **Configure environment variables:**
72+
Create a `.env` file in the root directory using your client credentials from the previous Create Application step:
73+
74+
```env
75+
PAYPAL_SANDBOX_CLIENT_ID=your_paypal_sandbox_client_id
76+
PAYPAL_SANDBOX_CLIENT_SECRET=your_paypal_sandbox_client_secret
77+
```
78+
79+
4. **Start the server:**
80+
```bash
81+
npm start
82+
```
83+
The server will run on `http://localhost:8080`
84+
85+
### Client Setup
86+
87+
1. **Navigate to the Swish demo directory:**
88+
89+
```bash
90+
cd client/components/swishPayments/html
91+
```
92+
93+
2. **Install dependencies:**
94+
95+
```bash
96+
npm install
97+
```
98+
99+
3. **Start the development server:**
100+
```bash
101+
npm start
102+
```
103+
The demo will be available at `http://localhost:3000`
104+
105+
## How It Works
106+
107+
### Client-Side Flow
108+
109+
1. **SDK Initialization**: Loads PayPal Web SDK with Swish components using a client token fetched from the server's `/paypal-api/auth/browser-safe-client-token` endpoint
110+
2. **Session Creation**: Creates Swish payment session with event callbacks for handling payment lifecycle events
111+
3. **Field Setup**: Mounts the required full name field
112+
4. **Validation**: Validates fields before initiating the payment flow
113+
5. **Payment Flow**: Opens a popup window where customers authorize the payment. The order is created server-side via `/paypal-api/checkout/orders/create` before displaying the popup
114+
6. **Completion**: Processes the payment result by capturing the approved order via `/paypal-api/checkout/orders/:orderId/capture`, or handles cancellation and error scenarios appropriately
115+
116+
### Server-Side Requirements
117+
118+
The integration requires these endpoints (provided by the API server):
119+
120+
- `GET /paypal-api/auth/browser-safe-client-token` - Generate client token
121+
- `POST /paypal-api/checkout/orders/create` - Create order
122+
- `POST /paypal-api/checkout/orders/:orderId/capture` - Capture order
123+
124+
## Key Integration Points
125+
126+
### Currency and Country Requirements
127+
128+
- **Country Code**: Must be `"SE"` (Sweden) - Swish is Sweden-exclusive
129+
- **Currency Code**: Must be `"SEK"` (Swedish Krona)
130+
- **Test Buyer Country**: Must be set to `"SE"`
131+
132+
### Order Payload
133+
134+
The order payload must include:
135+
- `intent`: Set to `"CAPTURE"`
136+
- `currency_code`: Set to `"SEK"`
137+
- `shipping.address.country_code`: Set to `"SE"`
138+
- `payer.name`: Required - payer's name information
139+
140+
Example:
141+
```javascript
142+
const orderPayload = {
143+
intent: "CAPTURE",
144+
payer: {
145+
name: {
146+
given_name: "Carlos",
147+
surname: "Abejundio"
148+
}
149+
},
150+
purchaseUnits: [{
151+
amount: {
152+
currencyCode: "SEK",
153+
value: "1000"
154+
},
155+
shipping: {
156+
address: {
157+
country_code: "SE"
158+
}
159+
}
160+
}]
161+
};
162+
```
163+
164+
## Available Scripts
165+
166+
- `npm start` - Start Vite development server (port 3000)
167+
- `npm run build` - Build for production
168+
- `npm run preview` - Preview production build
169+
- `npm run format` - Format code with Prettier
170+
- `npm run format:check` - Check code formatting
171+
172+
## Troubleshooting
173+
174+
### Swish not eligible
175+
176+
- Verify `testBuyerCountry` is set to "SE"
177+
- Check that Swish is enabled for the merchant in PayPal account settings
178+
- Ensure currency code is "SEK"
179+
- Confirm shipping address country code is "SE"
180+
181+
### Validation fails
182+
183+
- Ensure full name field is properly mounted with javascript
184+
- Check that field has valid input
185+
- Verify field is visible in the DOM
186+
187+
### Payment popup doesn't open
188+
189+
- Check for popup blockers
190+
- Verify order creation returns valid orderId
191+
- Ensure proper event handler setup
192+
- Check browser console for errors
193+
194+
### Order creation fails
195+
196+
- Verify API server is running on port 8080
197+
- Check server logs for errors
198+
- Validate order payload format
199+
- Ensure currency is SEK and country is SE
200+
- Verify payer name is included in payload
201+
202+
## Documentation
203+
204+
- [PayPal Developer Documentation](https://developer.paypal.com/docs/)
205+
- [PayPal Developer Community](https://developer.paypal.com/community/)

‎client/components/swishPayments/html/package.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "v6-web-sdk-sample-integration-client-swish",
3+
"version": "1.0.0",
4+
"private": true,
5+
"type": "module",
6+
"scripts": {
7+
"build": "vite build",
8+
"preview": "vite preview",
9+
"start": "vite",
10+
"format": "prettier . --write",
11+
"format:check": "prettier . --check",
12+
"lint": "echo \"eslint is not set up\""
13+
},
14+
"license": "Apache-2.0",
15+
"devDependencies": {
16+
"prettier": "^3.6.2",
17+
"vite": "^7.0.4"
18+
}
19+
}

0 commit comments

Comments
 (0)