{"id":51156064,"url":"https://github.com/grtsnx/payba3","last_synced_at":"2026-06-26T10:30:48.310Z","repository":{"id":366464308,"uuid":"1276393966","full_name":"grtsnx/payba3","owner":"grtsnx","description":"One payment integration surface for many payment channels.","archived":false,"fork":false,"pushed_at":"2026-06-22T02:14:42.000Z","size":339,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T02:19:42.396Z","etag":null,"topics":["ai-agents","fintech","monnify","mono","opay","open-banking","payment-gateway","payment-integration","payments","paystack","qoreid","safehaven","seerbit","virtual-accounts"],"latest_commit_sha":null,"homepage":"https://github.com/grtsnx/payba3","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grtsnx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T23:35:36.000Z","updated_at":"2026-06-22T02:14:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grtsnx/payba3","commit_stats":null,"previous_names":["grtsnx/payba3"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/grtsnx/payba3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grtsnx%2Fpayba3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grtsnx%2Fpayba3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grtsnx%2Fpayba3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grtsnx%2Fpayba3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grtsnx","download_url":"https://codeload.github.com/grtsnx/payba3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grtsnx%2Fpayba3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34813782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","fintech","monnify","mono","opay","open-banking","payment-gateway","payment-integration","payments","paystack","qoreid","safehaven","seerbit","virtual-accounts"],"created_at":"2026-06-26T10:30:47.608Z","updated_at":"2026-06-26T10:30:48.306Z","avatar_url":"https://github.com/grtsnx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/payba3-logo.svg\" alt=\"payba3\" width=\"220\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Framework-neutral payment integration surface for many payment channels.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./LICENSE\"\u003eLicense\u003c/a\u003e\n  ·\n  \u003ca href=\"./docs/introduction.mdx\"\u003eDocs\u003c/a\u003e\n  ·\n  \u003ca href=\"./CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n  ·\n  \u003ca href=\"./SECURITY.md\"\u003eSecurity\u003c/a\u003e\n  ·\n  \u003ca href=\"./SUPPORT.md\"\u003eSupport\u003c/a\u003e\n\u003c/p\u003e\n\n# payba3\n\npayba3 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 from server-side TypeScript or JavaScript.\n\nConfigure the provider you want, select it through payba3, and call the channel.\n\n```ts\nconst paystack = payba3.use('paystack');\n\nawait paystack.initializeOneTimeCheckout({\n  email: 'customer@example.com',\n  amountInKobo: 500000,\n  currency: 'NGN',\n});\n```\n\npayba3 is growing. More providers, methods, adapters, and examples will be added over time.\n\n## Documentation\n\nDetailed Mintlify documentation lives in `docs/` with the site map in `docs.json`.\nThe repository supports both Mintlify project-directory layouts:\n\n- repository root: `docs.json`\n- docs subdirectory: `docs/docs.json`\n\nPreview locally:\n\n```bash\nbun run docs:dev\n```\n\nPreview the `/docs` project-directory setup:\n\n```bash\nbun run docs:dev:docs\n```\n\nUse a Mintlify-supported LTS Node runtime for docs commands. Node 26 is not supported by the Mintlify CLI at the moment.\n\nThe docs cover installation, configuration, provider-specific usage, examples for common frameworks, agent and IDE integration, security, migration, and a separate API Reference tab.\n\n## About\n\nModern 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.\n\npayba3 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.\n\nUse payba3 when you want:\n\n- One dependency for multiple payment and verification providers.\n- A simple provider selector: `payba3.use('provider')`.\n- Provider-specific methods without rewriting authentication and token-refresh logic.\n- A project that can be used by normal application code, workflow automations, scripts, and AI agents.\n- A growing open-source base where more providers can be added over time.\n\n## Supported Channels\n\n| Channel   | Common use cases                                       | Provider signup                                          | Provider docs                                                      |\n| --------- | ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ |\n| Paystack  | Checkout, subscriptions, transfers, dedicated accounts | [Create account](https://paystack.com/developers)        | [Docs](https://paystack.com/docs/api/)                             |\n| Safehaven | Virtual accounts, subaccounts, banking APIs            | [Sandbox](https://online.sandbox.safehavenmfb.com)       | [Docs](https://safehavenmfb.readme.io/reference/introduction)      |\n| SeerBit   | Collections, virtual accounts, online payments         | [Create account](https://www.seerbit.com/developers)     | [Docs](https://doc.seerbit.com/)                                   |\n| OPay      | Checkout, signed payment APIs, refunds                 | [Merchant dashboard](https://merchant.opaycheckout.com)  | [Docs](https://doc.opaycheckout.com/payment-authentication)        |\n| Mono      | Open banking, account linking, DirectPay, lookup       | [Create account](https://mono.co/signup)                 | [Docs](https://docs.mono.co/docs/quickstart)                       |\n| Monnify   | Checkout, reserved accounts, transfers, wallets        | [Create account](https://app.monnify.com/create-account) | [Docs](https://developers.monnify.com/docs/collections/quickstart) |\n| QoreID    | KYC, CAC lookup, identity verification                 | [Create account](https://dashboard.qoreid.com/dashboard) | [Docs](https://docs.qoreid.com/)                                   |\n\n## Installation\n\n```bash\nnpm install @grtsnx/payba3\n```\n\n```bash\nyarn add @grtsnx/payba3\n```\n\n```bash\npnpm add @grtsnx/payba3\n```\n\n```bash\nbun add @grtsnx/payba3\n```\n\npayba3 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.\n\n### Runtime Requirements\n\npayba3 2.x is framework-neutral. It does not require Nest, Express, Fastify, Next.js, or any other framework package to import or use the provider clients.\n\nUse it in server-side JavaScript or TypeScript with a runtime that provides `fetch`, `URLSearchParams`, and Node-compatible crypto APIs. Node.js 18+ and Bun are covered by package smoke tests.\n\nIf you are using the repository directly:\n\n```bash\nbun install\n```\n\n## Quick Usage\n\nCreate a payba3 client, configure the providers you want, then select a channel.\n\n```ts\nimport { createPayba3 } from '@grtsnx/payba3';\n\nconst payba3 = createPayba3({\n  paystack: {\n    secretKey: process.env.PAYSTACK_SECRET_KEY,\n  },\n  safehaven: {\n    environment: 'sandbox',\n    clientId: process.env.SAFEHAVEN_CLIENT_ID,\n    clientAssertion: process.env.SAFEHAVEN_CLIENT_ASSERTION,\n  },\n});\n\nconst checkout = await payba3.use('paystack').initializeOneTimeCheckout({\n  email: 'customer@example.com',\n  amountInKobo: 250000,\n  currency: 'NGN',\n  reference: 'order_123',\n});\n\nconst subAccount = await payba3.use('safehaven').createSubAccount({\n  phoneNumber: '08000000000',\n  identityType: 'vID',\n  identityId: 'identity-id',\n  emailAddress: 'customer@example.com',\n  externalReference: 'customer_123',\n});\n```\n\nYou can also use a channel directly when you want provider-specific methods:\n\n```ts\nconst monnify = payba3.use('monnify');\n\nawait monnify.createReservedAccount({\n  accountReference: 'customer_123',\n  accountName: 'Jane Doe',\n  customerName: 'Jane Doe',\n  customerEmail: 'jane@example.com',\n  bvn: '00000000000',\n});\n```\n\n## Configuration\n\nOnly configure the providers you use. Missing credentials for unused providers should not block your application from starting.\n\nYou can configure providers through `createPayba3()` options, environment variables, or a mix of both. Explicit constructor options win over environment variables.\n\n```ts\nconst payba3 = createPayba3({\n  monnify: {\n    environment: 'live',\n    apiKey: process.env.MONNIFY_LIVE_API_KEY,\n    secretKey: process.env.MONNIFY_LIVE_SECRET_KEY,\n    contractCode: process.env.MONNIFY_LIVE_CONTRACT_CODE,\n  },\n  qoreid: {\n    clientId: process.env.QOREID_CLIENT,\n    secret: process.env.QOREID_SECRET,\n  },\n});\n```\n\n### Paystack\n\n```bash\nPAYSTACK_ENVIRONMENT=sandbox\nPAYSTACK_SECRET_KEY=\nPAYSTACK_SECRET_KEY_LIVE=\n```\n\n### Safehaven\n\n```bash\nSAFEHAVEN_ENVIRONMENT=sandbox\nSAFEHAVEN_CLIENT_ID=\nSAFEHAVEN_CLIENT_ASSERTION=\nSAFEHAVEN_LIVE_CLIENT_ID=\nSAFEHAVEN_LIVE_CLIENT_ASSERTION=\nSAFEHAVEN_TIMEOUT_MS=10000\n```\n\nSwitch to production:\n\n```bash\nSAFEHAVEN_ENVIRONMENT=live\n```\n\n### SeerBit\n\n```bash\nSEERBIT_ENVIRONMENT=sandbox\nSEERBIT_BASE_URL=\nSEERBIT_PUBLIC_KEY=\nSEERBIT_SECRET_KEY=\nSEERBIT_LIVE_PUBLIC_KEY=\nSEERBIT_LIVE_SECRET_KEY=\n```\n\n### OPay\n\n```bash\nOPAY_ENVIRONMENT=sandbox\nOPAY_MERCHANT_ID=\nOPAY_PUBLIC_KEY=\nOPAY_SECRET_KEY=\nOPAY_LIVE_MERCHANT_ID=\nOPAY_LIVE_PUBLIC_KEY=\nOPAY_LIVE_SECRET_KEY=\n```\n\n### Mono\n\n```bash\nMONO_ENVIRONMENT=sandbox\nMONO_SECRET_KEY=\nMONO_LIVE_SECRET_KEY=\n```\n\n### Monnify\n\n```bash\nMONNIFY_ENVIRONMENT=sandbox\nMONNIFY_API_KEY=\nMONNIFY_SECRET_KEY=\nMONNIFY_CONTRACT_CODE=\nMONNIFY_LIVE_API_KEY=\nMONNIFY_LIVE_SECRET_KEY=\nMONNIFY_LIVE_CONTRACT_CODE=\n```\n\n### QoreID\n\n```bash\nQOREID_ENVIRONMENT=sandbox\nQOREID_BASE_URL=\nQOREID_CLIENT=\nQOREID_SECRET=\nQOREID_LIVE_CLIENT=\nQOREID_LIVE_SECRET=\n```\n\n## Provider Selection\n\n```ts\npayba3.use('paystack');\npayba3.use('safehaven');\npayba3.use('seerbit');\npayba3.use('opay');\npayba3.use('mono');\npayba3.use('monnify');\npayba3.use('qoreid');\n```\n\nUnsupported providers throw a clear error.\n\n```ts\npayba3.use('unknown'); // throws Unsupported payment channel\n```\n\n## Token Handling\n\npayba3 refreshes expiring provider tokens before they become stale.\n\n- Safehaven uses `expires_in` from the token response.\n- Safehaven stores `ibs_client_id` from the token response for account-call `ClientID` headers.\n- QoreID accepts `expiresIn` or `expires_in` from the token response.\n- Monnify derives expiry from the JWT `exp` claim when available.\n\n## For AI Agents And Automation\n\npayba3 is intended to be easy for agents, IDE assistants, code generators, and automation workflows to reason about:\n\n- Provider names are explicit.\n- Configuration is environment based.\n- Request signing and token refresh are handled by payba3.\n- Provider-specific actions remain discoverable through named channels.\n\n### Agent Documentation Files\n\nThe npm package includes an LLM index, a full LLM context file, an agent guide, a machine-readable manifest, a suggested MCP-style tool schema, and provider-specific references. Agents and IDEs can read these files from an installed package instead of scraping source code.\n\n```ts\nimport { readFileSync } from 'node:fs';\nimport { createRequire } from 'node:module';\n\nconst require = createRequire(import.meta.url);\n\nconst indexPath = require.resolve('@grtsnx/payba3/llms.txt');\nconst fullContextPath = require.resolve('@grtsnx/payba3/llms-full.txt');\nconst agentGuidePath = require.resolve('@grtsnx/payba3/agents.md');\nconst manifestPath = require.resolve('@grtsnx/payba3/agents.json');\nconst paystackPath = require.resolve('@grtsnx/payba3/llms/paystack.txt');\n\nconst payba3Guide = readFileSync(indexPath, 'utf8');\nconst fullContext = readFileSync(fullContextPath, 'utf8');\nconst agentGuide = readFileSync(agentGuidePath, 'utf8');\nconst manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));\nconst paystackGuide = readFileSync(paystackPath, 'utf8');\n```\n\nAvailable agent and provider docs:\n\n```text\n@grtsnx/payba3/llms.txt\n@grtsnx/payba3/llms-full.txt\n@grtsnx/payba3/agents.md\n@grtsnx/payba3/agents.json\n@grtsnx/payba3/agents/ide-prompt.md\n@grtsnx/payba3/agents/mcp-tools.json\n@grtsnx/payba3/llms/paystack.txt\n@grtsnx/payba3/llms/safehaven.txt\n@grtsnx/payba3/llms/seerbit.txt\n@grtsnx/payba3/llms/opay.txt\n@grtsnx/payba3/llms/mono.txt\n@grtsnx/payba3/llms/monnify.txt\n@grtsnx/payba3/llms/qoreid.txt\n```\n\n### IDE And Agent Workflow\n\nFor IDEs, coding agents, and internal app generators:\n\n1. Install `@grtsnx/payba3`.\n2. Read `@grtsnx/payba3/llms.txt`.\n3. Read `@grtsnx/payba3/agents.md`.\n4. Read `@grtsnx/payba3/agents.json` when a machine-readable manifest is useful.\n5. Read the provider file for the requested channel.\n6. Generate server-side code that imports from `@grtsnx/payba3`.\n7. Ask the developer for only the provider environment variables they need.\n8. Keep secrets on the server and verify provider callbacks before delivering value.\n\nExample prompt for an IDE agent:\n\n```text\nUse @grtsnx/payba3 to add Paystack checkout.\nRead @grtsnx/payba3/llms.txt, @grtsnx/payba3/agents.md, and @grtsnx/payba3/llms/paystack.txt first.\nOnly add server-side code.\nUse PAYSTACK_SECRET_KEY from the environment.\nVerify transactions server-side before marking an order paid.\n```\n\nFor MCP servers or similar tool runtimes, use `@grtsnx/payba3/agents/mcp-tools.json` as a starting contract. It describes safe, narrow tool shapes and marks actions that should generally require human approval, such as account creation and money-moving flows.\n\nFor AI tool servers, expose small provider actions instead of exposing raw secrets:\n\n```ts\nimport { createPayba3, type Payba3ChannelName } from '@grtsnx/payba3';\n\ntype PaymentToolInput = {\n  channel: Payba3ChannelName;\n  action: 'initializeCheckout' | 'verifyTransaction';\n  payload: Record\u003cstring, unknown\u003e;\n};\n\nconst payba3 = createPayba3({\n  paystack: {\n    secretKey: process.env.PAYSTACK_SECRET_KEY,\n  },\n});\n\nexport class PaymentTool {\n  async run(input: PaymentToolInput) {\n    const provider = payba3.use(input.channel);\n\n    if (input.channel === 'paystack' \u0026\u0026 input.action === 'initializeCheckout') {\n      return provider.initializeOneTimeCheckout({\n        email: String(input.payload.email),\n        amountInKobo: Number(input.payload.amountInKobo),\n        reference: String(input.payload.reference),\n      });\n    }\n\n    throw new Error('Unsupported payment tool action');\n  }\n}\n```\n\n## Contributor Checks\n\n```bash\nbun install --frozen-lockfile\nbun run lint\nbun run test\nbun run test:providers\nbun run test:e2e\nbun run build\nbun run pack:dry\nbun run test:package\nbun run test:package:bun\nbun audit\n```\n\n## Contributing\n\npayba3 welcomes provider additions, method coverage, docs, tests, examples, and security hardening.\n\nRead [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.\n\n## Security\n\nDo not open public issues for vulnerabilities. Read [SECURITY.md](./SECURITY.md) for supported reporting channels and safe disclosure guidance.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrtsnx%2Fpayba3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrtsnx%2Fpayba3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrtsnx%2Fpayba3/lists"}