@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.
- package/CHANGELOG.md +14 -0
- package/CODE_OF_CONDUCT.md +24 -0
- package/CONTRIBUTING.md +149 -0
- package/LICENSE +21 -0
- package/README.md +282 -0
- package/SECURITY.md +53 -0
- package/SUPPORT.md +27 -0
- package/assets/payba3-logo.svg +17 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +24 -0
- package/dist/lib/lib.module.d.ts +2 -0
- package/dist/lib/lib.module.js +37 -0
- package/dist/lib/lib.module.js.map +1 -0
- package/dist/lib/monnify/config/monnify.helper.d.ts +24 -0
- package/dist/lib/monnify/config/monnify.helper.js +234 -0
- package/dist/lib/monnify/config/monnify.helper.js.map +1 -0
- package/dist/lib/monnify/config/monnify.types.d.ts +93 -0
- package/dist/lib/monnify/config/monnify.types.js +3 -0
- package/dist/lib/monnify/config/monnify.types.js.map +1 -0
- package/dist/lib/monnify/monnify.module.d.ts +2 -0
- package/dist/lib/monnify/monnify.module.js +22 -0
- package/dist/lib/monnify/monnify.module.js.map +1 -0
- package/dist/lib/monnify/monnify.service.d.ts +19 -0
- package/dist/lib/monnify/monnify.service.js +113 -0
- package/dist/lib/monnify/monnify.service.js.map +1 -0
- package/dist/lib/mono/config/mono.helper.d.ts +11 -0
- package/dist/lib/mono/config/mono.helper.js +78 -0
- package/dist/lib/mono/config/mono.helper.js.map +1 -0
- package/dist/lib/mono/config/mono.types.d.ts +48 -0
- package/dist/lib/mono/config/mono.types.js +3 -0
- package/dist/lib/mono/config/mono.types.js.map +1 -0
- package/dist/lib/mono/mono.module.d.ts +2 -0
- package/dist/lib/mono/mono.module.js +22 -0
- package/dist/lib/mono/mono.module.js.map +1 -0
- package/dist/lib/mono/mono.service.d.ts +15 -0
- package/dist/lib/mono/mono.service.js +77 -0
- package/dist/lib/mono/mono.service.js.map +1 -0
- package/dist/lib/opay/config/opay.helper.d.ts +17 -0
- package/dist/lib/opay/config/opay.helper.js +175 -0
- package/dist/lib/opay/config/opay.helper.js.map +1 -0
- package/dist/lib/opay/config/opay.types.d.ts +73 -0
- package/dist/lib/opay/config/opay.types.js +3 -0
- package/dist/lib/opay/config/opay.types.js.map +1 -0
- package/dist/lib/opay/opay.module.d.ts +2 -0
- package/dist/lib/opay/opay.module.js +22 -0
- package/dist/lib/opay/opay.module.js.map +1 -0
- package/dist/lib/opay/opay.service.d.ts +17 -0
- package/dist/lib/opay/opay.service.js +104 -0
- package/dist/lib/opay/opay.service.js.map +1 -0
- package/dist/lib/payba3.service.d.ts +16 -0
- package/dist/lib/payba3.service.js +59 -0
- package/dist/lib/payba3.service.js.map +1 -0
- package/dist/lib/payba3.types.d.ts +18 -0
- package/dist/lib/payba3.types.js +13 -0
- package/dist/lib/payba3.types.js.map +1 -0
- package/dist/lib/paystack/config/paystack.helper.d.ts +15 -0
- package/dist/lib/paystack/config/paystack.helper.js +134 -0
- package/dist/lib/paystack/config/paystack.helper.js.map +1 -0
- package/dist/lib/paystack/config/paystack.types.d.ts +92 -0
- package/dist/lib/paystack/config/paystack.types.js +3 -0
- package/dist/lib/paystack/config/paystack.types.js.map +1 -0
- package/dist/lib/paystack/paystack.module.d.ts +2 -0
- package/dist/lib/paystack/paystack.module.js +22 -0
- package/dist/lib/paystack/paystack.module.js.map +1 -0
- package/dist/lib/paystack/paystack.service.d.ts +33 -0
- package/dist/lib/paystack/paystack.service.js +328 -0
- package/dist/lib/paystack/paystack.service.js.map +1 -0
- package/dist/lib/qoreid/config/qoreid.helper.d.ts +19 -0
- package/dist/lib/qoreid/config/qoreid.helper.js +132 -0
- package/dist/lib/qoreid/config/qoreid.helper.js.map +1 -0
- package/dist/lib/qoreid/config/qoreid.types.d.ts +35 -0
- package/dist/lib/qoreid/config/qoreid.types.js +3 -0
- package/dist/lib/qoreid/config/qoreid.types.js.map +1 -0
- package/dist/lib/qoreid/qoreid.module.d.ts +2 -0
- package/dist/lib/qoreid/qoreid.module.js +22 -0
- package/dist/lib/qoreid/qoreid.module.js.map +1 -0
- package/dist/lib/qoreid/qoreid.service.d.ts +10 -0
- package/dist/lib/qoreid/qoreid.service.js +63 -0
- package/dist/lib/qoreid/qoreid.service.js.map +1 -0
- package/dist/lib/safehaven/config/safe.helper.d.ts +16 -0
- package/dist/lib/safehaven/config/safe.helper.js +136 -0
- package/dist/lib/safehaven/config/safe.helper.js.map +1 -0
- package/dist/lib/safehaven/config/safe.types.d.ts +50 -0
- package/dist/lib/safehaven/config/safe.types.js +3 -0
- package/dist/lib/safehaven/config/safe.types.js.map +1 -0
- package/dist/lib/safehaven/safe.module.d.ts +2 -0
- package/dist/lib/safehaven/safe.module.js +22 -0
- package/dist/lib/safehaven/safe.module.js.map +1 -0
- package/dist/lib/safehaven/safe.service.d.ts +14 -0
- package/dist/lib/safehaven/safe.service.js +77 -0
- package/dist/lib/safehaven/safe.service.js.map +1 -0
- package/dist/lib/seerbit/config/seerbit.helper.d.ts +11 -0
- package/dist/lib/seerbit/config/seerbit.helper.js +88 -0
- package/dist/lib/seerbit/config/seerbit.helper.js.map +1 -0
- package/dist/lib/seerbit/config/seerbit.types.d.ts +49 -0
- package/dist/lib/seerbit/config/seerbit.types.js +3 -0
- package/dist/lib/seerbit/config/seerbit.types.js.map +1 -0
- package/dist/lib/seerbit/seerbit.module.d.ts +2 -0
- package/dist/lib/seerbit/seerbit.module.js +22 -0
- package/dist/lib/seerbit/seerbit.module.js.map +1 -0
- package/dist/lib/seerbit/seerbit.service.d.ts +11 -0
- package/dist/lib/seerbit/seerbit.service.js +83 -0
- package/dist/lib/seerbit/seerbit.service.js.map +1 -0
- package/dist/lib/shared/index.d.ts +1 -0
- package/dist/lib/shared/index.js +18 -0
- package/dist/lib/shared/index.js.map +1 -0
- package/dist/lib/shared/response.helper.d.ts +15 -0
- package/dist/lib/shared/response.helper.js +39 -0
- package/dist/lib/shared/response.helper.js.map +1 -0
- package/llms.txt +25 -0
- package/package.json +169 -0
- package/src/lib/monnify/monnify_llm.txt +429 -0
- package/src/lib/mono/mono_llm.txt +372 -0
- package/src/lib/opay/opay_llm.txt +1022 -0
- package/src/lib/paystack/paystack_llm.txt +382 -0
- package/src/lib/qoreid/qoreid_llm.txt +68 -0
- package/src/lib/safehaven/safehaven_llm.txt +77 -0
- 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
|
+
|
package/CONTRIBUTING.md
ADDED
|
@@ -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>
|
package/dist/index.d.ts
ADDED
|
@@ -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,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
|