@vindhq/sloud-payment-sdk 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +83 -198
  2. package/dist/index.cjs.js +1 -1
  3. package/dist/index.d.ts +12 -2
  4. package/dist/index.esm.js +2 -2
  5. package/dist/index.umd.js +42 -6
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Sloud Payment SDK
2
2
 
3
- A secure, embeddable payment widget built in React, usable in **any JavaScript application** (React, Angular, Vue, or vanilla JS). Ships with **ESM, CJS, and UMD builds** for easy integration in any environment.
3
+ A secure, embeddable payment widget for straightforward customer payments, built in React and usable in **any JavaScript application** (React, Angular, Vue, or vanilla JS). Ships with **ESM, CJS, and UMD builds** for easy integration in any environment.
4
4
 
5
5
  ---
6
6
 
@@ -41,30 +41,30 @@ For direct browser usage without a bundler, use the UMD build which includes Rea
41
41
  ```html
42
42
  <!DOCTYPE html>
43
43
  <html>
44
- <head>
45
- <title>Payment Widget</title>
46
- </head>
47
- <body>
48
- <!-- Load the UMD bundle (includes React) -->
49
- <script src="https://unpkg.com/@vindhq/sloud-payment-sdk@latest/dist/index.umd.js"></script>
50
-
51
- <script>
52
- // Access via PaymentWidget.default for UMD builds
53
- const widget = new PaymentWidget.default({
54
- type: "external",
55
- public_key: "your-public-api-key",
56
- amount: 10000,
57
- customer: {
58
- first_name: "John",
59
- last_name: "Doe",
60
- phone_number: "+2348012345678",
61
- email: "john.doe@example.com",
62
- },
63
- });
64
-
65
- widget.showPopup();
66
- </script>
67
- </body>
44
+ <head>
45
+ <title>Payment Widget</title>
46
+ </head>
47
+ <body>
48
+ <!-- Load the UMD bundle (includes React) -->
49
+ <script src="https://unpkg.com/@vindhq/sloud-payment-sdk@latest/dist/index.umd.js"></script>
50
+
51
+ <script>
52
+ // Access via PaymentWidget.default for UMD builds
53
+ const widget = new PaymentWidget.default({
54
+ type: "external",
55
+ public_key: "your-public-api-key",
56
+ amount: 10000,
57
+ customer: {
58
+ first_name: "John",
59
+ last_name: "Doe",
60
+ phone_number: "+2348012345678",
61
+ email: "john.doe@example.com",
62
+ },
63
+ });
64
+
65
+ widget.showPopup();
66
+ </script>
67
+ </body>
68
68
  </html>
69
69
  ```
70
70
 
@@ -72,16 +72,12 @@ For direct browser usage without a bundler, use the UMD build which includes Rea
72
72
 
73
73
  ## Usage
74
74
 
75
- The payment widget supports three payment types: **external**, **storefront**, and **sloudfront**. Each type has its own set of required fields.
75
+ The payment widget is designed for straightforward payments with customer details.
76
76
 
77
77
  > **Note**: When using the UMD build in the browser (via script tag), access the widget via `PaymentWidget.default`. For npm/ES module imports, use the standard `import PaymentWidget from "sloud-payment-sdk"`.
78
78
 
79
- ### External Payment (Simple Payments)
80
-
81
- For straightforward payments with customer details:
82
-
83
79
  ```tsx
84
- import PaymentWidget from "sloud-payment-sdk";
80
+ import PaymentWidget from "@vindhq/sloud-payment-sdk";
85
81
 
86
82
  const widget = new PaymentWidget({
87
83
  type: "external",
@@ -94,94 +90,38 @@ const widget = new PaymentWidget({
94
90
  email: "john.doe@example.com",
95
91
  },
96
92
  isLocalEnv: false, // Optional: set to true for local development
97
- });
98
-
99
- widget.showPopup();
100
- ```
101
-
102
- ### Storefront Payment (E-commerce Orders)
103
-
104
- For e-commerce orders with products and delivery:
105
-
106
- ```tsx
107
- import PaymentWidget from "sloud-payment-sdk";
108
-
109
- const widget = new PaymentWidget({
110
- type: "storefront",
111
- public_key: "your-public-api-key",
112
- slug: "my-store",
113
- amount: 5000, // Additional amount (e.g., shipping fees)
114
- discount: 1000, // Optional discount
115
- channel: "delivery", // "pickup" or "delivery"
116
- customer: {
117
- first_name: "Jane",
118
- last_name: "Smith",
119
- phone_number: "+2348098765432",
120
- email: "jane.smith@example.com",
121
- },
122
- delivery_details: {
123
- street: "123 Main Street",
124
- city: "Lagos",
125
- state: "Lagos",
126
- country: "Nigeria",
127
- note: "Please call on arrival", // Optional
93
+ onSuccess: () => {
94
+ console.log("Payment successful!");
95
+ // Navigate to a confirmation page, update your UI, etc.
128
96
  },
129
- products: [
130
- {
131
- product_id: "prod_123",
132
- quantity: 2,
133
- variation: ["Large", "Blue"], // Optional
134
- },
135
- {
136
- product_id: "prod_456",
137
- quantity: 1,
138
- },
139
- ],
140
97
  });
141
98
 
142
- // Payment method will be selected by the user in the widget UI
143
-
144
99
  widget.showPopup();
145
100
  ```
146
101
 
147
- ### Sloudfront Payment (Manual Orders)
102
+ ### Handling Payment Success
148
103
 
149
- For manual orders with existing transaction/customer/business IDs:
104
+ Use the `onSuccess` callback to be notified when a payment completes successfully:
150
105
 
151
106
  ```tsx
152
- import PaymentWidget from "sloud-payment-sdk";
107
+ import PaymentWidget from "@vindhq/sloud-payment-sdk";
153
108
 
154
109
  const widget = new PaymentWidget({
155
- type: "sloudfront",
110
+ type: "external",
156
111
  public_key: "your-public-api-key",
157
- transaction_id: "txn_abc123",
158
- customer_id: "cust_xyz789",
159
- business_id: "biz_def456",
160
- amount: 5000,
161
- discount: 500,
162
- channel: "pickup", // "pickup" or "delivery"
112
+ amount: 10000,
163
113
  customer: {
164
- first_name: "Alice",
165
- last_name: "Johnson",
166
- phone_number: "+2348011223344",
167
- email: "alice.johnson@example.com",
114
+ first_name: "John",
115
+ last_name: "Doe",
116
+ phone_number: "+2348012345678",
117
+ email: "john.doe@example.com",
168
118
  },
169
- delivery_details: {
170
- street: "456 Oak Avenue",
171
- city: "Abuja",
172
- state: "FCT",
173
- country: "Nigeria",
119
+ onSuccess: () => {
120
+ console.log("Payment successful!");
121
+ // Navigate to a confirmation page, update your UI, etc.
174
122
  },
175
- products: [
176
- {
177
- product_id: "prod_789",
178
- quantity: 1,
179
- },
180
- ],
181
123
  });
182
124
 
183
- // Payment method will be selected by the user in the widget UI
184
-
185
125
  widget.showPopup();
186
126
  ```
187
127
 
@@ -193,54 +133,21 @@ widget.showPopup();
193
133
 
194
134
  Creates a new payment widget instance.
195
135
 
196
- #### Common Options (All Payment Types)
197
-
198
- | Parameter | Type | Required | Description |
199
- | --------------- | --------- | -------- | -------------------------------------------------- |
200
- | `type` | `PaymentType` | Yes | Payment type: `"external"`, `"storefront"`, or `"sloudfront"` |
201
- | `public_key` | `string` | Yes | Your public API key for secure payments |
202
- | `isLocalEnv` | `boolean` | No | Set to `true` for local development environment |
203
-
204
- #### External Payment Options
205
-
206
- | Parameter | Type | Required | Description |
207
- | ---------- | --------- | -------- | ------------------------------------------ |
208
- | `amount` | `number` | Yes | Payment amount in smallest currency unit |
209
- | `customer` | `Customer` | Yes | Customer information object |
210
-
211
- #### Storefront Payment Options
212
-
213
- | Parameter | Type | Required | Description |
214
- | -------------------- | ------------------ | -------- | ------------------------------------------ |
215
- | `slug` | `string` | Yes | Store identifier |
216
- | `amount` | `number` | Yes | Additional amount (e.g., shipping fees) |
217
- | `discount` | `number` | No | Discount amount |
218
- | `channel` | `ChannelType` | Yes | Delivery channel: `"pickup"` or `"delivery"` |
219
- | `customer` | `Customer` | Yes | Customer information object |
220
- | `delivery_details` | `DeliveryDetails` | Yes | Delivery address and notes |
221
- | `products` | `Product[]` | Yes | Array of products in the order |
136
+ #### Payment Widget Options
222
137
 
223
- **Note:** Payment method is selected by the user within the widget UI based on available payment options.
224
-
225
- #### Sloudfront Payment Options
226
-
227
- | Parameter | Type | Required | Description |
228
- | -------------------- | ------------------ | -------- | ------------------------------------------ |
229
- | `transaction_id` | `string` | Yes | Existing transaction ID |
230
- | `customer_id` | `string` | Yes | Existing customer ID |
231
- | `business_id` | `string` | Yes | Existing business ID |
232
- | `amount` | `number` | Yes | Additional amount |
233
- | `discount` | `number` | No | Discount amount |
234
- | `channel` | `ChannelType` | Yes | Delivery channel: `"pickup"` or `"delivery"` |
235
- | `customer` | `Customer` | Yes | Customer information object |
236
- | `delivery_details` | `DeliveryDetails` | Yes | Delivery address and notes |
237
- | `products` | `Product[]` | Yes | Array of products in the order |
238
-
239
- **Note:** Payment method is selected by the user within the widget UI based on available payment options.
138
+ | Parameter | Type | Required | Description |
139
+ | ------------ | ------------------------------------ | -------- | ----------------------------------------------- |
140
+ | `type` | `"external"` | Yes | Payment type (must be `"external"`) |
141
+ | `public_key` | `string` | Yes | Your public API key for secure payments |
142
+ | `amount` | `number` | Yes | Payment amount in smallest currency unit |
143
+ | `customer` | `Customer` | Yes | Customer information object |
144
+ | `isLocalEnv` | `boolean` | No | Set to `true` for local development environment |
145
+ | `onSuccess` | `(data: PaymentSuccessData) => void` | No | Callback invoked after a successful payment |
240
146
 
241
147
  #### Type Definitions
242
148
 
243
149
  **Customer**
150
+
244
151
  ```ts
245
152
  interface Customer {
246
153
  first_name: string;
@@ -250,36 +157,16 @@ interface Customer {
250
157
  }
251
158
  ```
252
159
 
253
- **DeliveryDetails**
254
- ```ts
255
- interface DeliveryDetails {
256
- street: string;
257
- city: string;
258
- state: string;
259
- country: string;
260
- note?: string;
261
- }
262
- ```
160
+ **PaymentSuccessData**
263
161
 
264
- **Product**
265
162
  ```ts
266
- interface Product {
267
- product_id: string;
268
- quantity: number;
269
- variation?: string[];
163
+ interface PaymentSuccessData {
164
+ reference: string;
165
+ amount: number;
166
+ currency: string;
270
167
  }
271
168
  ```
272
169
 
273
- **PaymentType**
274
- ```ts
275
- type PaymentType = "external" | "storefront" | "sloudfront";
276
- ```
277
-
278
- **ChannelType**
279
- ```ts
280
- type ChannelType = "pickup" | "delivery";
281
- ```
282
-
283
170
  #### Methods
284
171
 
285
172
  ##### `showPopup()`
@@ -302,14 +189,14 @@ widget.hidePopup();
302
189
 
303
190
  ## Validation and Error Handling
304
191
 
305
- The SDK includes built-in validation for all payment types:
192
+ The SDK includes built-in validation:
306
193
 
307
194
  ```ts
308
195
  import {
309
196
  PaymentWidget,
310
197
  validatePaymentWidgetOptions,
311
198
  PaymentWidgetValidationError,
312
- } from "sloud-payment-sdk";
199
+ } from "@vindhq/sloud-payment-sdk";
313
200
 
314
201
  try {
315
202
  const options = {
@@ -338,25 +225,24 @@ try {
338
225
 
339
226
  ## Advanced Usage
340
227
 
341
- ### Extensible Payload Builders
228
+ ### Payload Builders
342
229
 
343
- The SDK uses a builder pattern for payment payloads and can be extended with custom payment types:
230
+ The SDK uses a builder pattern for payment payloads:
344
231
 
345
232
  ```ts
346
- import {
347
- buildPaymentInstrumentPayload,
348
- registerPayloadBuilder,
349
- getRegisteredPaymentTypes,
350
- } from "sloud-payment-sdk";
351
-
352
- // Get all registered payment types
353
- const types = getRegisteredPaymentTypes();
354
- console.log(types); // ["external", "storefront", "sloudfront"]
233
+ import { buildPaymentInstrumentPayload } from "@vindhq/sloud-payment-sdk";
355
234
 
356
235
  // Build payload from options
357
236
  const payload = buildPaymentInstrumentPayload({
358
237
  type: "external",
359
- // ... other options
238
+ public_key: "pk_test_123",
239
+ amount: 10000,
240
+ customer: {
241
+ first_name: "John",
242
+ last_name: "Doe",
243
+ phone_number: "+2348012345678",
244
+ email: "john.doe@example.com",
245
+ },
360
246
  });
361
247
  ```
362
248
 
@@ -367,22 +253,21 @@ The SDK is written in TypeScript and provides full type definitions:
367
253
  ```ts
368
254
  import type {
369
255
  PaymentWidgetOptions,
370
- ExternalPaymentWidgetOptions,
371
- StorefrontPaymentWidgetOptions,
372
- SloudfrontPaymentWidgetOptions,
373
- PaymentType,
374
- ChannelType,
256
+ PaymentSuccessData,
375
257
  Customer,
376
- DeliveryDetails,
377
- Product,
378
- } from "sloud-payment-sdk";
258
+ } from "@vindhq/sloud-payment-sdk";
379
259
 
380
- // TypeScript will enforce correct fields based on payment type
381
- const options: StorefrontPaymentWidgetOptions = {
382
- type: "storefront",
260
+ // TypeScript will enforce correct fields
261
+ const options: PaymentWidgetOptions = {
262
+ type: "external",
383
263
  public_key: "pk_test_123",
384
- slug: "my-store",
385
- // ... TypeScript ensures all required fields are present
264
+ amount: 10000,
265
+ customer: {
266
+ first_name: "John",
267
+ last_name: "Doe",
268
+ phone_number: "+2348012345678",
269
+ email: "john.doe@example.com",
270
+ },
386
271
  };
387
272
  ```
388
273
 
@@ -444,7 +329,7 @@ Payment-Widget/
444
329
  ### Output Files
445
330
 
446
331
  - **`dist/index.esm.js`** - ES Module build (externalizes React)
447
- - **`dist/index.cjs.js`** - CommonJS build (externalizes React)
332
+ - **`dist/index.cjs.js`** - CommonJS build (externalizes React)
448
333
  - **`dist/index.umd.js`** - UMD build for browsers (bundles React, ~2MB)
449
334
  - **`dist/index.d.ts`** - TypeScript type definitions
450
335