@grtsnx/payba3 1.0.0

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 (118) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/CODE_OF_CONDUCT.md +24 -0
  3. package/CONTRIBUTING.md +149 -0
  4. package/LICENSE +21 -0
  5. package/README.md +282 -0
  6. package/SECURITY.md +53 -0
  7. package/SUPPORT.md +27 -0
  8. package/assets/payba3-logo.svg +17 -0
  9. package/dist/index.d.ts +18 -0
  10. package/dist/index.js +24 -0
  11. package/dist/lib/lib.module.d.ts +2 -0
  12. package/dist/lib/lib.module.js +37 -0
  13. package/dist/lib/lib.module.js.map +1 -0
  14. package/dist/lib/monnify/config/monnify.helper.d.ts +24 -0
  15. package/dist/lib/monnify/config/monnify.helper.js +234 -0
  16. package/dist/lib/monnify/config/monnify.helper.js.map +1 -0
  17. package/dist/lib/monnify/config/monnify.types.d.ts +93 -0
  18. package/dist/lib/monnify/config/monnify.types.js +3 -0
  19. package/dist/lib/monnify/config/monnify.types.js.map +1 -0
  20. package/dist/lib/monnify/monnify.module.d.ts +2 -0
  21. package/dist/lib/monnify/monnify.module.js +22 -0
  22. package/dist/lib/monnify/monnify.module.js.map +1 -0
  23. package/dist/lib/monnify/monnify.service.d.ts +19 -0
  24. package/dist/lib/monnify/monnify.service.js +113 -0
  25. package/dist/lib/monnify/monnify.service.js.map +1 -0
  26. package/dist/lib/mono/config/mono.helper.d.ts +11 -0
  27. package/dist/lib/mono/config/mono.helper.js +78 -0
  28. package/dist/lib/mono/config/mono.helper.js.map +1 -0
  29. package/dist/lib/mono/config/mono.types.d.ts +48 -0
  30. package/dist/lib/mono/config/mono.types.js +3 -0
  31. package/dist/lib/mono/config/mono.types.js.map +1 -0
  32. package/dist/lib/mono/mono.module.d.ts +2 -0
  33. package/dist/lib/mono/mono.module.js +22 -0
  34. package/dist/lib/mono/mono.module.js.map +1 -0
  35. package/dist/lib/mono/mono.service.d.ts +15 -0
  36. package/dist/lib/mono/mono.service.js +77 -0
  37. package/dist/lib/mono/mono.service.js.map +1 -0
  38. package/dist/lib/opay/config/opay.helper.d.ts +17 -0
  39. package/dist/lib/opay/config/opay.helper.js +175 -0
  40. package/dist/lib/opay/config/opay.helper.js.map +1 -0
  41. package/dist/lib/opay/config/opay.types.d.ts +73 -0
  42. package/dist/lib/opay/config/opay.types.js +3 -0
  43. package/dist/lib/opay/config/opay.types.js.map +1 -0
  44. package/dist/lib/opay/opay.module.d.ts +2 -0
  45. package/dist/lib/opay/opay.module.js +22 -0
  46. package/dist/lib/opay/opay.module.js.map +1 -0
  47. package/dist/lib/opay/opay.service.d.ts +17 -0
  48. package/dist/lib/opay/opay.service.js +104 -0
  49. package/dist/lib/opay/opay.service.js.map +1 -0
  50. package/dist/lib/payba3.service.d.ts +16 -0
  51. package/dist/lib/payba3.service.js +59 -0
  52. package/dist/lib/payba3.service.js.map +1 -0
  53. package/dist/lib/payba3.types.d.ts +18 -0
  54. package/dist/lib/payba3.types.js +13 -0
  55. package/dist/lib/payba3.types.js.map +1 -0
  56. package/dist/lib/paystack/config/paystack.helper.d.ts +15 -0
  57. package/dist/lib/paystack/config/paystack.helper.js +134 -0
  58. package/dist/lib/paystack/config/paystack.helper.js.map +1 -0
  59. package/dist/lib/paystack/config/paystack.types.d.ts +92 -0
  60. package/dist/lib/paystack/config/paystack.types.js +3 -0
  61. package/dist/lib/paystack/config/paystack.types.js.map +1 -0
  62. package/dist/lib/paystack/paystack.module.d.ts +2 -0
  63. package/dist/lib/paystack/paystack.module.js +22 -0
  64. package/dist/lib/paystack/paystack.module.js.map +1 -0
  65. package/dist/lib/paystack/paystack.service.d.ts +33 -0
  66. package/dist/lib/paystack/paystack.service.js +328 -0
  67. package/dist/lib/paystack/paystack.service.js.map +1 -0
  68. package/dist/lib/qoreid/config/qoreid.helper.d.ts +19 -0
  69. package/dist/lib/qoreid/config/qoreid.helper.js +132 -0
  70. package/dist/lib/qoreid/config/qoreid.helper.js.map +1 -0
  71. package/dist/lib/qoreid/config/qoreid.types.d.ts +35 -0
  72. package/dist/lib/qoreid/config/qoreid.types.js +3 -0
  73. package/dist/lib/qoreid/config/qoreid.types.js.map +1 -0
  74. package/dist/lib/qoreid/qoreid.module.d.ts +2 -0
  75. package/dist/lib/qoreid/qoreid.module.js +22 -0
  76. package/dist/lib/qoreid/qoreid.module.js.map +1 -0
  77. package/dist/lib/qoreid/qoreid.service.d.ts +10 -0
  78. package/dist/lib/qoreid/qoreid.service.js +63 -0
  79. package/dist/lib/qoreid/qoreid.service.js.map +1 -0
  80. package/dist/lib/safehaven/config/safe.helper.d.ts +16 -0
  81. package/dist/lib/safehaven/config/safe.helper.js +136 -0
  82. package/dist/lib/safehaven/config/safe.helper.js.map +1 -0
  83. package/dist/lib/safehaven/config/safe.types.d.ts +50 -0
  84. package/dist/lib/safehaven/config/safe.types.js +3 -0
  85. package/dist/lib/safehaven/config/safe.types.js.map +1 -0
  86. package/dist/lib/safehaven/safe.module.d.ts +2 -0
  87. package/dist/lib/safehaven/safe.module.js +22 -0
  88. package/dist/lib/safehaven/safe.module.js.map +1 -0
  89. package/dist/lib/safehaven/safe.service.d.ts +14 -0
  90. package/dist/lib/safehaven/safe.service.js +77 -0
  91. package/dist/lib/safehaven/safe.service.js.map +1 -0
  92. package/dist/lib/seerbit/config/seerbit.helper.d.ts +11 -0
  93. package/dist/lib/seerbit/config/seerbit.helper.js +88 -0
  94. package/dist/lib/seerbit/config/seerbit.helper.js.map +1 -0
  95. package/dist/lib/seerbit/config/seerbit.types.d.ts +49 -0
  96. package/dist/lib/seerbit/config/seerbit.types.js +3 -0
  97. package/dist/lib/seerbit/config/seerbit.types.js.map +1 -0
  98. package/dist/lib/seerbit/seerbit.module.d.ts +2 -0
  99. package/dist/lib/seerbit/seerbit.module.js +22 -0
  100. package/dist/lib/seerbit/seerbit.module.js.map +1 -0
  101. package/dist/lib/seerbit/seerbit.service.d.ts +11 -0
  102. package/dist/lib/seerbit/seerbit.service.js +83 -0
  103. package/dist/lib/seerbit/seerbit.service.js.map +1 -0
  104. package/dist/lib/shared/index.d.ts +1 -0
  105. package/dist/lib/shared/index.js +18 -0
  106. package/dist/lib/shared/index.js.map +1 -0
  107. package/dist/lib/shared/response.helper.d.ts +15 -0
  108. package/dist/lib/shared/response.helper.js +39 -0
  109. package/dist/lib/shared/response.helper.js.map +1 -0
  110. package/llms.txt +25 -0
  111. package/package.json +169 -0
  112. package/src/lib/monnify/monnify_llm.txt +429 -0
  113. package/src/lib/mono/mono_llm.txt +372 -0
  114. package/src/lib/opay/opay_llm.txt +1022 -0
  115. package/src/lib/paystack/paystack_llm.txt +382 -0
  116. package/src/lib/qoreid/qoreid_llm.txt +68 -0
  117. package/src/lib/safehaven/safehaven_llm.txt +77 -0
  118. package/src/lib/seerbit/seerbit_llm.txt +61 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ All notable project changes should be documented here.
4
+
5
+ This project follows a human-readable changelog style. Add new entries under `Unreleased` until a version is cut.
6
+
7
+ ## Unreleased
8
+
9
+ - Added payba3 provider facade.
10
+ - Added OPay, Mono, and Monnify channel scaffolding.
11
+ - Added provider LLM reference files.
12
+ - Added contribution, security, support, and conduct documentation.
13
+ - Added payba3 logo assets.
14
+
@@ -0,0 +1,24 @@
1
+ # Code Of Conduct
2
+
3
+ payba3 follows a simple standard: be respectful, direct, and useful.
4
+
5
+ ## Expected Behavior
6
+
7
+ - Be welcoming to new contributors.
8
+ - Assume good intent while staying clear about technical concerns.
9
+ - Give actionable feedback.
10
+ - Respect different levels of experience.
11
+ - Keep discussions focused on the project and its users.
12
+
13
+ ## Unacceptable Behavior
14
+
15
+ - Harassment, threats, or personal attacks.
16
+ - Discriminatory language or behavior.
17
+ - Publishing private information without consent.
18
+ - Posting secrets, credentials, or customer data.
19
+ - Repeatedly derailing project discussions.
20
+
21
+ ## Enforcement
22
+
23
+ Maintainers may remove comments, close issues, reject pull requests, or block users who violate this code of conduct.
24
+
@@ -0,0 +1,149 @@
1
+ # Contributing To payba3
2
+
3
+ Thanks for helping improve payba3. This project is for developers who want one clean payment integration surface across many providers.
4
+
5
+ ## Ways To Contribute
6
+
7
+ - Add a new provider.
8
+ - Expand method coverage for an existing provider.
9
+ - Improve provider types.
10
+ - Add tests for helpers, token refresh, signing, and provider payloads.
11
+ - Improve examples and documentation.
12
+ - Report bugs with clear reproduction steps.
13
+ - Review pull requests.
14
+
15
+ ## Before You Start
16
+
17
+ Open an issue first for large changes, new provider additions, public APIs, or breaking behavior. Small fixes, docs improvements, and tests can go straight to a pull request.
18
+
19
+ ## Development Setup
20
+
21
+ ```bash
22
+ bun install --frozen-lockfile
23
+ ```
24
+
25
+ Run checks before opening a pull request:
26
+
27
+ ```bash
28
+ bun run lint
29
+ bun run test
30
+ bun run test:providers
31
+ bun run test:e2e
32
+ bun run build
33
+ bun run pack:dry
34
+ bun run test:package
35
+ bun run test:package:bun
36
+ bun audit
37
+ ```
38
+
39
+ ## Project Layout
40
+
41
+ payba3 keeps source code, tests, documentation, and provider reference material separated so contributors can find the right place quickly.
42
+
43
+ ```text
44
+ payba3/
45
+ ├── .github/
46
+ │ ├── workflows/
47
+ │ │ ├── ci.yml # CI map: audit, test, build, smoke, summary
48
+ │ │ └── release.yml # Release package workflow
49
+ │ ├── ISSUE_TEMPLATE/ # Bug and feature request templates
50
+ │ ├── PULL_REQUEST_TEMPLATE.md # Pull request checklist
51
+ │ └── repository-metadata.yml # Maintainer reference for GitHub about/topics
52
+ ├── assets/
53
+ │ ├── payba3-logo.svg # Full README/project logo
54
+ │ └── payba3-mark.svg # Compact icon/mark
55
+ ├── scripts/
56
+ │ ├── package-release.sh # Release archive builder
57
+ │ └── package-smoke-test.mjs # Clean install/import package smoke test
58
+ ├── src/
59
+ │ ├── app/ # Minimal app shell and health endpoint
60
+ │ ├── lib/ # payba3 provider integrations
61
+ │ │ ├── payba3.service.ts # One entry point for selecting a provider
62
+ │ │ ├── payba3.types.ts # Shared payba3 channel types
63
+ │ │ ├── lib.module.ts # Provider registration module
64
+ │ │ ├── shared/ # Provider-safe shared helpers
65
+ │ │ ├── paystack/ # Paystack channel
66
+ │ │ ├── safehaven/ # Safehaven channel
67
+ │ │ ├── seerbit/ # SeerBit channel
68
+ │ │ ├── opay/ # OPay channel
69
+ │ │ ├── mono/ # Mono channel
70
+ │ │ ├── monnify/ # Monnify channel
71
+ │ │ └── qoreid/ # QoreID channel
72
+ │ ├── middleware/ # App filters and env validation for local app use
73
+ │ ├── index.ts # Public package exports
74
+ │ └── main.ts # Local app bootstrap
75
+ ├── test/
76
+ │ ├── unit/ # Unit tests mirrored by feature/provider
77
+ │ ├── app.e2e-spec.ts # E2E smoke route test
78
+ │ └── jest-e2e.json # E2E Jest config
79
+ ├── README.md # User-facing usage guide
80
+ ├── llms.txt # Agent/LLM index for provider references
81
+ ├── SECURITY.md # Vulnerability reporting policy
82
+ ├── SUPPORT.md # Support guidance
83
+ ├── CODE_OF_CONDUCT.md # Community behavior expectations
84
+ ├── CHANGELOG.md # Human-readable change log
85
+ ├── CONTRIBUTING.md # This contributor guide
86
+ ├── LICENSE # MIT license
87
+ ├── package.json # Package metadata and scripts
88
+ └── bun.lock # Dependency lockfile
89
+ ```
90
+
91
+ ## Provider Folder Shape
92
+
93
+ Each provider should follow the same layout where possible.
94
+
95
+ ```text
96
+ src/lib/<provider>/
97
+ ├── config/
98
+ │ ├── <provider>.helper.ts # Auth, signing, token refresh, fetch, parsing
99
+ │ └── <provider>.types.ts # Provider payloads, responses, request context
100
+ ├── <provider>.module.ts # Provider registration
101
+ ├── <provider>.service.ts # Developer-facing provider actions
102
+ └── <provider>_llm.txt # Provider docs for agents/LLMs
103
+ ```
104
+
105
+ Tests for that provider belong in `test/unit`, not beside source files:
106
+
107
+ ```text
108
+ test/unit/lib/<provider>/
109
+ └── config/<provider>.helper.spec.ts
110
+ ```
111
+
112
+ ## Provider Contribution Checklist
113
+
114
+ When adding or expanding a provider:
115
+
116
+ - Add provider config keys to the environment validation schema.
117
+ - Keep credentials and secrets out of source code.
118
+ - Put provider request signing, token refresh, parsing, and low-level HTTP behavior in helpers.
119
+ - Put provider payload and response contracts in types.
120
+ - Keep service methods focused on developer-facing actions.
121
+ - Add unit tests under `test/unit` for auth, signing, token refresh, and request payload shape.
122
+ - Add or update provider LLM reference material when available.
123
+ - Update the README provider table.
124
+
125
+ ## Coding Guidelines
126
+
127
+ - Prefer explicit provider names and clear method names.
128
+ - Avoid hidden global state.
129
+ - Validate credentials when a provider is used, not when an unused provider is merely registered.
130
+ - Keep secret-bearing data out of logs and error messages.
131
+ - Add tests for new behavior.
132
+
133
+ ## Pull Request Checklist
134
+
135
+ - The PR explains the user/developer problem it solves.
136
+ - The PR includes tests or explains why tests are not applicable.
137
+ - The README or docs are updated when public usage changes.
138
+ - All local checks pass.
139
+ - No secrets, API keys, tokens, private assertions, or real customer data are committed.
140
+
141
+ ## Commit Style
142
+
143
+ Use clear, plain commit messages:
144
+
145
+ ```text
146
+ add monnify reserved account helper
147
+ fix safehaven token refresh window
148
+ docs: add opay signup link
149
+ ```
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 payba3 contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,282 @@
1
+ <p align="center">
2
+ <img src="./assets/payba3-logo.svg" alt="payba3" width="220" />
3
+ </p>
4
+
5
+ <p align="center">
6
+ One payment integration surface for many payment channels.
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="./LICENSE">License</a>
11
+ ·
12
+ <a href="./CONTRIBUTING.md">Contributing</a>
13
+ ·
14
+ <a href="./SECURITY.md">Security</a>
15
+ ·
16
+ <a href="./SUPPORT.md">Support</a>
17
+ </p>
18
+
19
+ # payba3
20
+
21
+ payba3 is an open-source collection of payment-channel integrations built for developers, teams, codebases, automations, and AI agents that need a simple way to plug into different payment providers.
22
+
23
+ Configure the provider you want, select it through payba3, and call the channel.
24
+
25
+ ```ts
26
+ const paystack = payba3.use('paystack');
27
+
28
+ await paystack.initializeOneTimeCheckout({
29
+ email: 'customer@example.com',
30
+ amountInKobo: 500000,
31
+ currency: 'NGN',
32
+ });
33
+ ```
34
+
35
+ payba3 is growing. More providers, methods, adapters, and examples will be added over time.
36
+
37
+ ## About
38
+
39
+ Modern products rarely stay tied to one payment provider forever. A team may start with one checkout provider, add virtual accounts later, route a payout through another provider, run identity checks with a verification API, and still need a clean way for application code, scripts, background jobs, and AI agents to call those channels without learning every provider from scratch.
40
+
41
+ payba3 is a developer-friendly payment integration layer for that reality. It gives each provider a named channel, keeps provider credentials in configuration, and exposes direct methods for common actions such as checkout, virtual accounts, transfers, subaccounts, account linking, and identity checks.
42
+
43
+ Use payba3 when you want:
44
+
45
+ - One dependency for multiple payment and verification providers.
46
+ - A simple provider selector: `payba3.use('provider')`.
47
+ - Provider-specific methods without rewriting authentication and token-refresh logic.
48
+ - A project that can be used by normal application code, workflow automations, scripts, and AI agents.
49
+ - A growing open-source base where more providers can be added over time.
50
+
51
+ ## Supported Channels
52
+
53
+ | Channel | Common use cases | Provider signup | Provider docs |
54
+ | --- | --- | --- | --- |
55
+ | Paystack | Checkout, subscriptions, transfers, dedicated accounts | [Create account](https://paystack.com/developers) | [Docs](https://paystack.com/docs/api/) |
56
+ | Safehaven | Virtual accounts, subaccounts, banking APIs | [Sandbox](https://online.sandbox.safehavenmfb.com) | [Docs](https://safehavenmfb.readme.io/reference/introduction) |
57
+ | SeerBit | Collections, virtual accounts, online payments | [Create account](https://www.seerbit.com/developers) | [Docs](https://doc.seerbit.com/) |
58
+ | OPay | Checkout, signed payment APIs, refunds | [Merchant dashboard](https://merchant.opaycheckout.com) | [Docs](https://doc.opaycheckout.com/payment-authentication) |
59
+ | Mono | Open banking, account linking, DirectPay, lookup | [Create account](https://mono.co/signup) | [Docs](https://docs.mono.co/docs/quickstart) |
60
+ | Monnify | Checkout, reserved accounts, transfers, wallets | [Create account](https://app.monnify.com/create-account) | [Docs](https://developers.monnify.com/docs/collections/quickstart) |
61
+ | QoreID | KYC, CAC lookup, identity verification | [Create account](https://dashboard.qoreid.com/dashboard) | [Docs](https://docs.qoreid.com/) |
62
+
63
+ ## Installation
64
+
65
+ ```bash
66
+ npm install @grtsnx/payba3
67
+ ```
68
+
69
+ ```bash
70
+ yarn add @grtsnx/payba3
71
+ ```
72
+
73
+ ```bash
74
+ pnpm add @grtsnx/payba3
75
+ ```
76
+
77
+ ```bash
78
+ bun add @grtsnx/payba3
79
+ ```
80
+
81
+ payba3 ships compiled JavaScript, TypeScript declarations, and an npm exports map. It is tested with npm and Bun install smoke checks in CI. Yarn and pnpm can consume the same npm package metadata.
82
+
83
+ payba3 declares the core Nest packages as peer dependencies so your application keeps one Nest runtime. If your package manager does not auto-install peer dependencies, install these alongside payba3:
84
+
85
+ ```bash
86
+ npm install @nestjs/common @nestjs/core @nestjs/config reflect-metadata rxjs
87
+ ```
88
+
89
+ If you are using the repository directly:
90
+
91
+ ```bash
92
+ bun install
93
+ ```
94
+
95
+ ## Quick Usage
96
+
97
+ Register payba3 in your application, then use `Payba3Service` to select a channel.
98
+
99
+ ```ts
100
+ import { Payba3Service } from '@grtsnx/payba3';
101
+
102
+ export class Payments {
103
+ constructor(private readonly payba3: Payba3Service) {}
104
+
105
+ async collectWithPaystack() {
106
+ return this.payba3.use('paystack').initializeOneTimeCheckout({
107
+ email: 'customer@example.com',
108
+ amountInKobo: 250000,
109
+ currency: 'NGN',
110
+ reference: 'order_123',
111
+ });
112
+ }
113
+
114
+ async createSafehavenSubAccount() {
115
+ return this.payba3.use('safehaven').createSubAccount({
116
+ phoneNumber: '08000000000',
117
+ identityType: 'vID',
118
+ identityId: 'identity-id',
119
+ emailAddress: 'customer@example.com',
120
+ externalReference: 'customer_123',
121
+ });
122
+ }
123
+ }
124
+ ```
125
+
126
+ You can also use a channel directly when you want provider-specific methods:
127
+
128
+ ```ts
129
+ await monnify.createReservedAccount({
130
+ accountReference: 'customer_123',
131
+ accountName: 'Jane Doe',
132
+ customerName: 'Jane Doe',
133
+ customerEmail: 'jane@example.com',
134
+ bvn: '00000000000',
135
+ });
136
+ ```
137
+
138
+ ## Configuration
139
+
140
+ Only configure the providers you use. Missing credentials for unused providers should not block your application from starting.
141
+
142
+ ### Paystack
143
+
144
+ ```bash
145
+ PAYSTACK_ENVIRONMENT=sandbox
146
+ PAYSTACK_SECRET_KEY=
147
+ PAYSTACK_SECRET_KEY_LIVE=
148
+ ```
149
+
150
+ ### Safehaven
151
+
152
+ ```bash
153
+ SAFEHAVEN_ENVIRONMENT=sandbox
154
+ SAFEHAVEN_CLIENT_ID=
155
+ SAFEHAVEN_CLIENT_ASSERTION=
156
+ SAFEHAVEN_TIMEOUT_MS=10000
157
+ ```
158
+
159
+ Switch to production:
160
+
161
+ ```bash
162
+ SAFEHAVEN_ENVIRONMENT=live
163
+ ```
164
+
165
+ ### SeerBit
166
+
167
+ ```bash
168
+ SEERBIT_ENVIRONMENT=sandbox
169
+ SEERBIT_BASE_URL=
170
+ SEERBIT_PUBLIC_KEY=
171
+ SEERBIT_SECRET_KEY=
172
+ SEERBIT_LIVE_PUBLIC_KEY=
173
+ SEERBIT_LIVE_SECRET_KEY=
174
+ ```
175
+
176
+ ### OPay
177
+
178
+ ```bash
179
+ OPAY_ENVIRONMENT=sandbox
180
+ OPAY_MERCHANT_ID=
181
+ OPAY_PUBLIC_KEY=
182
+ OPAY_SECRET_KEY=
183
+ OPAY_LIVE_MERCHANT_ID=
184
+ OPAY_LIVE_PUBLIC_KEY=
185
+ OPAY_LIVE_SECRET_KEY=
186
+ ```
187
+
188
+ ### Mono
189
+
190
+ ```bash
191
+ MONO_ENVIRONMENT=sandbox
192
+ MONO_SECRET_KEY=
193
+ MONO_LIVE_SECRET_KEY=
194
+ ```
195
+
196
+ ### Monnify
197
+
198
+ ```bash
199
+ MONNIFY_ENVIRONMENT=sandbox
200
+ MONNIFY_API_KEY=
201
+ MONNIFY_SECRET_KEY=
202
+ MONNIFY_CONTRACT_CODE=
203
+ MONNIFY_LIVE_API_KEY=
204
+ MONNIFY_LIVE_SECRET_KEY=
205
+ MONNIFY_LIVE_CONTRACT_CODE=
206
+ ```
207
+
208
+ ### QoreID
209
+
210
+ ```bash
211
+ QOREID_ENVIRONMENT=sandbox
212
+ QOREID_BASE_URL=
213
+ QOREID_CLIENT=
214
+ QOREID_SECRET=
215
+ QOREID_LIVE_CLIENT=
216
+ QOREID_LIVE_SECRET=
217
+ ```
218
+
219
+ ## Provider Selection
220
+
221
+ ```ts
222
+ payba3.use('paystack');
223
+ payba3.use('safehaven');
224
+ payba3.use('seerbit');
225
+ payba3.use('opay');
226
+ payba3.use('mono');
227
+ payba3.use('monnify');
228
+ payba3.use('qoreid');
229
+ ```
230
+
231
+ Unsupported providers throw a clear error.
232
+
233
+ ```ts
234
+ payba3.use('unknown'); // throws Unsupported payment channel
235
+ ```
236
+
237
+ ## Token Handling
238
+
239
+ payba3 refreshes expiring provider tokens before they become stale.
240
+
241
+ - Safehaven uses `expires_in` from the token response.
242
+ - Safehaven stores `ibs_client_id` from the token response for account-call `ClientID` headers.
243
+ - QoreID accepts `expiresIn` or `expires_in` from the token response.
244
+ - Monnify derives expiry from the JWT `exp` claim when available.
245
+
246
+ ## For AI Agents And Automation
247
+
248
+ payba3 is intended to be easy for agents and automation workflows to reason about:
249
+
250
+ - Provider names are explicit.
251
+ - Configuration is environment based.
252
+ - Request signing and token refresh are handled by payba3.
253
+ - Provider-specific actions remain discoverable through named channels.
254
+
255
+ ## Contributor Checks
256
+
257
+ ```bash
258
+ bun install --frozen-lockfile
259
+ bun run lint
260
+ bun run test
261
+ bun run test:providers
262
+ bun run test:e2e
263
+ bun run build
264
+ bun run pack:dry
265
+ bun run test:package
266
+ bun run test:package:bun
267
+ bun audit
268
+ ```
269
+
270
+ ## Contributing
271
+
272
+ payba3 welcomes provider additions, method coverage, docs, tests, examples, and security hardening.
273
+
274
+ Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
275
+
276
+ ## Security
277
+
278
+ Do not open public issues for vulnerabilities. Read [SECURITY.md](./SECURITY.md) for supported reporting channels and safe disclosure guidance.
279
+
280
+ ## License
281
+
282
+ MIT. See [LICENSE](./LICENSE).
package/SECURITY.md ADDED
@@ -0,0 +1,53 @@
1
+ # Security Policy
2
+
3
+ payba3 deals with payment and identity provider integrations, so security reports are taken seriously.
4
+
5
+ ## Reporting A Vulnerability
6
+
7
+ Do not open a public GitHub issue for vulnerabilities.
8
+
9
+ Report privately through the repository owner's preferred security contact or GitHub private vulnerability reporting when enabled.
10
+
11
+ Include:
12
+
13
+ - A clear description of the issue.
14
+ - Affected provider or module.
15
+ - Steps to reproduce.
16
+ - Impact and possible abuse path.
17
+ - Suggested fix, if known.
18
+
19
+ ## What To Avoid Sharing Publicly
20
+
21
+ Do not post:
22
+
23
+ - API keys.
24
+ - OAuth client assertions.
25
+ - Access tokens.
26
+ - Refresh tokens.
27
+ - Webhook secrets.
28
+ - Real customer identity data.
29
+ - Real bank account, BVN, NIN, card, or transaction data.
30
+
31
+ ## Supported Versions
32
+
33
+ Until the project reaches a stable `1.0.0`, security fixes are applied to the latest mainline version.
34
+
35
+ ## Security Expectations For Contributions
36
+
37
+ - Keep all provider secrets in environment variables or secret managers.
38
+ - Never log raw authorization headers, cookies, access tokens, refresh tokens, or client assertions.
39
+ - Verify webhook signatures before trusting provider callbacks.
40
+ - Refresh expiring access tokens before they become stale.
41
+ - Use sandbox credentials for examples and tests.
42
+ - Do not add real customer data to tests, docs, fixtures, or LLM files.
43
+
44
+ ## Dependency Security
45
+
46
+ Run:
47
+
48
+ ```bash
49
+ bun audit
50
+ ```
51
+
52
+ Security-related dependency overrides should include a short explanation in the pull request.
53
+
package/SUPPORT.md ADDED
@@ -0,0 +1,27 @@
1
+ # Support
2
+
3
+ Use the right channel for the type of help you need.
4
+
5
+ ## Questions
6
+
7
+ Open a discussion or issue with:
8
+
9
+ - The provider you are using.
10
+ - The method you are calling.
11
+ - Sanitized config names, not secret values.
12
+ - Expected behavior.
13
+ - Actual behavior.
14
+ - Relevant error response with sensitive fields removed.
15
+
16
+ ## Bugs
17
+
18
+ Open a bug report with a minimal reproduction. Do not include live keys, access tokens, customer identity data, or real financial data.
19
+
20
+ ## Security Issues
21
+
22
+ Do not open a public issue. Read [SECURITY.md](./SECURITY.md).
23
+
24
+ ## Provider Account Issues
25
+
26
+ payba3 cannot approve merchant accounts, unlock dashboards, or issue provider credentials. Contact the payment provider directly for account approval, live keys, settlement, compliance, or dashboard access.
27
+
@@ -0,0 +1,17 @@
1
+ <svg width="760" height="220" viewBox="0 0 760 220" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
2
+ <title id="title">payba3 logo</title>
3
+ <desc id="desc">A minimalist payba3 wordmark with three payment rails merging into one channel.</desc>
4
+ <rect width="760" height="220" rx="28" fill="#FFFFFF"/>
5
+ <g transform="translate(54 46)">
6
+ <path d="M18 28C18 12.536 30.536 0 46 0H130C145.464 0 158 12.536 158 28V112C158 127.464 145.464 140 130 140H46C30.536 140 18 127.464 18 112V28Z" fill="#111827"/>
7
+ <path d="M58 42H100" stroke="#FFFFFF" stroke-width="14" stroke-linecap="round"/>
8
+ <path d="M58 70H118" stroke="#A78BFA" stroke-width="14" stroke-linecap="round"/>
9
+ <path d="M58 98H92" stroke="#F59E0B" stroke-width="14" stroke-linecap="round"/>
10
+ <path d="M136 42L168 70L136 98" stroke="#06B6D4" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/>
11
+ <circle cx="38" cy="42" r="7" fill="#FFFFFF"/>
12
+ <circle cx="38" cy="70" r="7" fill="#A78BFA"/>
13
+ <circle cx="38" cy="98" r="7" fill="#F59E0B"/>
14
+ </g>
15
+ <text x="258" y="124" fill="#111827" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="78" font-weight="850" letter-spacing="0">payba3</text>
16
+ <text x="262" y="160" fill="#4B5563" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="22" font-weight="500" letter-spacing="0">plug in any payment rail</text>
17
+ </svg>
@@ -0,0 +1,18 @@
1
+ export { LibModule } from './lib/lib.module';
2
+ export { Payba3Service } from './lib/payba3.service';
3
+ export { PAYBA3_CHANNELS } from './lib/payba3.types';
4
+ export type { Payba3ChannelMap, Payba3ChannelName } from './lib/payba3.types';
5
+ export { MonoService } from './lib/mono/mono.service';
6
+ export type * from './lib/mono/config/mono.types';
7
+ export { MonnifyService } from './lib/monnify/monnify.service';
8
+ export type * from './lib/monnify/config/monnify.types';
9
+ export { OPayService } from './lib/opay/opay.service';
10
+ export type * from './lib/opay/config/opay.types';
11
+ export { PaystackService } from './lib/paystack/paystack.service';
12
+ export type * from './lib/paystack/config/paystack.types';
13
+ export { QoreIDService } from './lib/qoreid/qoreid.service';
14
+ export type * from './lib/qoreid/config/qoreid.types';
15
+ export { SafehavenService } from './lib/safehaven/safe.service';
16
+ export type * from './lib/safehaven/config/safe.types';
17
+ export { SeerbitService } from './lib/seerbit/seerbit.service';
18
+ export type * from './lib/seerbit/config/seerbit.types';
package/dist/index.js ADDED
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SeerbitService = exports.SafehavenService = exports.QoreIDService = exports.PaystackService = exports.OPayService = exports.MonnifyService = exports.MonoService = exports.PAYBA3_CHANNELS = exports.Payba3Service = exports.LibModule = void 0;
4
+ var lib_module_1 = require("./lib/lib.module");
5
+ Object.defineProperty(exports, "LibModule", { enumerable: true, get: function () { return lib_module_1.LibModule; } });
6
+ var payba3_service_1 = require("./lib/payba3.service");
7
+ Object.defineProperty(exports, "Payba3Service", { enumerable: true, get: function () { return payba3_service_1.Payba3Service; } });
8
+ var payba3_types_1 = require("./lib/payba3.types");
9
+ Object.defineProperty(exports, "PAYBA3_CHANNELS", { enumerable: true, get: function () { return payba3_types_1.PAYBA3_CHANNELS; } });
10
+ var mono_service_1 = require("./lib/mono/mono.service");
11
+ Object.defineProperty(exports, "MonoService", { enumerable: true, get: function () { return mono_service_1.MonoService; } });
12
+ var monnify_service_1 = require("./lib/monnify/monnify.service");
13
+ Object.defineProperty(exports, "MonnifyService", { enumerable: true, get: function () { return monnify_service_1.MonnifyService; } });
14
+ var opay_service_1 = require("./lib/opay/opay.service");
15
+ Object.defineProperty(exports, "OPayService", { enumerable: true, get: function () { return opay_service_1.OPayService; } });
16
+ var paystack_service_1 = require("./lib/paystack/paystack.service");
17
+ Object.defineProperty(exports, "PaystackService", { enumerable: true, get: function () { return paystack_service_1.PaystackService; } });
18
+ var qoreid_service_1 = require("./lib/qoreid/qoreid.service");
19
+ Object.defineProperty(exports, "QoreIDService", { enumerable: true, get: function () { return qoreid_service_1.QoreIDService; } });
20
+ var safe_service_1 = require("./lib/safehaven/safe.service");
21
+ Object.defineProperty(exports, "SafehavenService", { enumerable: true, get: function () { return safe_service_1.SafehavenService; } });
22
+ var seerbit_service_1 = require("./lib/seerbit/seerbit.service");
23
+ Object.defineProperty(exports, "SeerbitService", { enumerable: true, get: function () { return seerbit_service_1.SeerbitService; } });
24
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,2 @@
1
+ export declare class LibModule {
2
+ }
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
3
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
4
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
5
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
6
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
7
+ };
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.LibModule = void 0;
10
+ const common_1 = require("@nestjs/common");
11
+ const mono_module_1 = require("./mono/mono.module");
12
+ const monnify_module_1 = require("./monnify/monnify.module");
13
+ const opay_module_1 = require("./opay/opay.module");
14
+ const paystack_module_1 = require("./paystack/paystack.module");
15
+ const qoreid_module_1 = require("./qoreid/qoreid.module");
16
+ const safe_module_1 = require("./safehaven/safe.module");
17
+ const seerbit_module_1 = require("./seerbit/seerbit.module");
18
+ const payba3_service_1 = require("./payba3.service");
19
+ let LibModule = class LibModule {
20
+ };
21
+ exports.LibModule = LibModule;
22
+ exports.LibModule = LibModule = __decorate([
23
+ (0, common_1.Module)({
24
+ imports: [
25
+ mono_module_1.MonoModule,
26
+ monnify_module_1.MonnifyModule,
27
+ opay_module_1.OPayModule,
28
+ paystack_module_1.PaystackModule,
29
+ qoreid_module_1.QoreIDModule,
30
+ safe_module_1.SafehavenModule,
31
+ seerbit_module_1.SeerbitModule,
32
+ ],
33
+ providers: [payba3_service_1.Payba3Service],
34
+ exports: [payba3_service_1.Payba3Service],
35
+ })
36
+ ], LibModule);
37
+ //# sourceMappingURL=lib.module.js.map