epic-collection-gateway-sdk 1.0.4 → 1.0.6
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.
- package/README.md +58 -30
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,7 +7,6 @@ A lightweight TypeScript/JavaScript SDK for integrating **Epic Collections Web C
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
9
|
- **`startEpicCollectionPayment`** – Authenticate with the Epic Collections API and get the redirect URL to the hosted payment portal in one call.
|
|
10
|
-
- **`redirectToPortal`** – Build a portal redirect URL manually.
|
|
11
10
|
- Zero dependencies, ESM-only, full TypeScript types included.
|
|
12
11
|
|
|
13
12
|
---
|
|
@@ -41,6 +40,63 @@ window.location.assign(url);
|
|
|
41
40
|
|
|
42
41
|
---
|
|
43
42
|
|
|
43
|
+
## React Integration Example
|
|
44
|
+
|
|
45
|
+
Here is a practical example of integrating the SDK within a React component (e.g., a Header or Checkout button).
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
import { useState } from 'react';
|
|
49
|
+
import { startEpicCollectionPayment } from 'epic-collection-gateway-sdk';
|
|
50
|
+
|
|
51
|
+
const CheckoutButton = ({ cart, total }) => {
|
|
52
|
+
const [paying, setPaying] = useState(false);
|
|
53
|
+
|
|
54
|
+
const handleCheckout = async () => {
|
|
55
|
+
if (cart.length === 0) return;
|
|
56
|
+
try {
|
|
57
|
+
setPaying(true);
|
|
58
|
+
|
|
59
|
+
// Generate a unique session ID
|
|
60
|
+
const sessionId = `${Date.now()}${Math.floor(Math.random() * 1e9)}`;
|
|
61
|
+
|
|
62
|
+
const url = await startEpicCollectionPayment({
|
|
63
|
+
environment: 'production', // or 'sandbox'
|
|
64
|
+
clientId: 'YOUR_CLIENT_ID',
|
|
65
|
+
clientSecret: 'YOUR_CLIENT_SECRET',
|
|
66
|
+
redirectUrl: 'https://your-site.com/checkout-success',
|
|
67
|
+
amount: total,
|
|
68
|
+
sessionId,
|
|
69
|
+
customerDetails: {
|
|
70
|
+
email: 'user@example.com',
|
|
71
|
+
name: 'John Doe'
|
|
72
|
+
},
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
// Redirect the user to the portal
|
|
76
|
+
window.location.assign(url);
|
|
77
|
+
} catch (error) {
|
|
78
|
+
console.error("Payment failed", error);
|
|
79
|
+
} finally {
|
|
80
|
+
setPaying(false);
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
return (
|
|
85
|
+
<button
|
|
86
|
+
onClick={handleCheckout}
|
|
87
|
+
disabled={paying || cart.length === 0}
|
|
88
|
+
className="btn-primary"
|
|
89
|
+
>
|
|
90
|
+
{paying ? 'Processing…' : `Proceed to Pay (₦${total})`}
|
|
91
|
+
</button>
|
|
92
|
+
);
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
export default CheckoutButton;
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
44
100
|
## API Reference
|
|
45
101
|
|
|
46
102
|
### `startEpicCollectionPayment(options)` → `Promise<string>`
|
|
@@ -69,33 +125,6 @@ interface EpicCollectioncustomerDetails {
|
|
|
69
125
|
|
|
70
126
|
---
|
|
71
127
|
|
|
72
|
-
### `redirectToPortal(params)` → `string`
|
|
73
|
-
|
|
74
|
-
Builds and returns the portal URL without making an auth API call.
|
|
75
|
-
|
|
76
|
-
| Param | Type | Required | Description |
|
|
77
|
-
|---|---|---|---|
|
|
78
|
-
| `amount` | `number` | ✅ | Checkout amount. |
|
|
79
|
-
| `sessionId` | `string` | ✅ | Unique checkout session ID. |
|
|
80
|
-
| `redirectUrl` | `string` | — | Overrides the default redirect URL. |
|
|
81
|
-
| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer metadata. |
|
|
82
|
-
| `additionalParams` | `Record<string, string \| number \| boolean>` | — | Any extra query params to append to the URL. |
|
|
83
|
-
|
|
84
|
-
```ts
|
|
85
|
-
import { redirectToPortal } from "epic-collection-gateway-sdk";
|
|
86
|
-
|
|
87
|
-
const url = redirectToPortal({
|
|
88
|
-
amount: 2300,
|
|
89
|
-
sessionId: "sess_123456789",
|
|
90
|
-
redirectUrl: "https://your-site.com/order-result",
|
|
91
|
-
customerDetails: { email: "user@example.com" },
|
|
92
|
-
});
|
|
93
|
-
|
|
94
|
-
window.location.assign(url);
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
128
|
## TypeScript Types
|
|
100
129
|
|
|
101
130
|
All types are exported from the package root:
|
|
@@ -105,7 +134,6 @@ import type {
|
|
|
105
134
|
EpicPayEnvironment,
|
|
106
135
|
StartEpicCollectionPaymentOptions,
|
|
107
136
|
EpicCollectioncustomerDetails,
|
|
108
|
-
RedirectToPortalParams,
|
|
109
137
|
EpicPayConfig,
|
|
110
138
|
PaymentEvent,
|
|
111
139
|
PaymentResult,
|
|
@@ -122,7 +150,7 @@ A convenience object is available as the default export:
|
|
|
122
150
|
```ts
|
|
123
151
|
import EpicCollectionSdk from "epic-collection-gateway-sdk";
|
|
124
152
|
|
|
125
|
-
const { startEpicCollectionPayment
|
|
153
|
+
const { startEpicCollectionPayment } = EpicCollectionSdk;
|
|
126
154
|
```
|
|
127
155
|
|
|
128
156
|
---
|