afripayments-cli

KO | EN

gitlite — search

#kotlin #typescript #security #cli #cloud-native #claude-code #awesome-list #database #json #developer-tools

afripayments-cli

(★ 9)

Scaffold a working, secure payment integration — Paystack, Hubtel, or Flutterwave — into your project in under 60 seconds.

파일 탐색기

ZIP 다운로드

- cli.js
- - init.js
- - detectModuleType.js
  - detectProject.js
- - envGenerator.js
  - routeGenerator.js
- - payment-route.cjs.template
  - payment-route.esm.template
  - payment-route.express-ts.template
  - payment-route.flutterwave-cjs.template
  - payment-route.flutterwave-next-app.template
  - payment-route.flutterwave-next-pages.template
  - payment-route.hubtel-cjs.template
  - payment-route.hubtel-next-app.template
  - payment-route.hubtel-next-pages.template
  - payment-route.next-app-ts.template
  - payment-route.next-app.template
  - payment-route.next-pages-ts.template
  - payment-route.next-pages.template
  - webhook-route.cjs.template
  - webhook-route.esm.template
  - webhook-route.express-ts.template
  - webhook-route.flutterwave-cjs.template
  - webhook-route.flutterwave-next-app.template
  - webhook-route.flutterwave-next-pages.template
  - webhook-route.hubtel-cjs.template
  - webhook-route.hubtel-next-app.template
  - webhook-route.hubtel-next-pages.template
  - webhook-route.next-app-ts.template
  - webhook-route.next-app.template
  - webhook-route.next-pages-ts.template
  - webhook-route.next-pages.template
- - logger.js
  - prompts.js
- .DS_Store
.DS_Store
.gitignore
LICENSE
package-lock.json
package.json
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Scaffold a working, secure payment integration — Paystack, Hubtel, or Flutterwave — into your project in under 60 seconds.

```
npx afripayments-cli init
```

Pick your provider, answer a few prompts, and get a correctly-verified payment initialization route and webhook handler, wired to your project's actual setup. No more copy-pasting from tutorials or getting webhook signature verification subtly wrong.

---

## ⚠️ Before you use the Hubtel option

Unlike Paystack and Flutterwave, **Hubtel does not cryptographically sign its payment callback.** There is no signature to verify. As generated, the Hubtel webhook route will accept a callback from anyone who discovers its URL — this is a real, documented limitation of Hubtel's system, not a bug in this tool.

The generated code includes clear `TODO` comments explaining how to guard against this (matching the callback to a reference you generated yourself, and/or calling Hubtel's Status Check API). **Read those comments and implement at least one of those checks before using the Hubtel integration in production.** See [Security](#security) below for more.

---

## Why this exists

Integrating any of these providers usually means writing the same boilerplate from scratch — and each has its own way to get something important wrong:

- **Paystack** signs the *raw* request body, not the parsed JSON. If your body-parsing middleware runs before you verify the signature, verification silently breaks.
- **Flutterwave** signs webhooks using a separate *secret hash* you set in your dashboard — not your API secret key, a common mix-up. It also expects `amount` in the *main* currency unit (e.g. `50` for GHS 50.00), not the smallest unit like Paystack uses.
- **Hubtel** doesn't sign webhooks at all (see above) — the safe pattern here is different from the other two, not just a variation on it.

`afripayments-cli` generates code that handles each of these correctly (or, for Hubtel, as safely as the provider allows) by default, so you start from a working baseline instead of discovering these gotchas in production.

---

## What it supports

| Provider | Express (JS) | Express (TS) | Next.js App Router | Next.js Pages Router |
|---|---|---|---|---|
| Paystack | ✅ | ✅ | ✅ | ✅ |
| Hubtel | ✅ | ❌ | ✅ | ✅ |
| Flutterwave | ✅ | ❌ | ✅ | ✅ |

TypeScript output currently exists for Paystack only. If you pick Hubtel or Flutterwave in a TypeScript project, the CLI will warn you and offer to generate plain JavaScript instead — it won't silently generate the wrong thing.

Not yet supported: Django, Laravel. See [Roadmap](#roadmap).

---

## Quickstart

Run this inside an existing Node.js project (Express or Next.js):

```bash
npx afripayments-cli init
```

You'll be asked:
1. **Which provider** — Paystack, Hubtel, or Flutterwave
2. **Your credentials** for that provider (see below — each provider needs different ones)
3. **Where to place the routes** — sensible defaults provided based on your framework

The tool detects your framework, module system, and (for Next.js) router style automatically.

### Credentials by provider

| Provider | What you'll be asked for |
|---|---|
| Paystack | Secret key (`sk_test_...` / `sk_live_...`) |
| Flutterwave | Secret key, **and** a separate Webhook Secret Hash (set this in your Flutterwave dashboard → Settings → Webhooks first) |
| Hubtel | Client ID, Client Secret, and Merchant Account Number |

All input is hidden where sensitive, and written only to your local `.env` — never transmitted anywhere else, never logged.

### After it runs

**Express projects** — mount the generated routes in your app entry file:

```js
const paymentRoute = require('./routes/payment');
const webhookRoute = require('./routes/webhook-<provider>'); // e.g. webhook-hubtel

app.use('/api/payment', paymentRoute);
app.use('/api/webhook/<provider>', webhookRoute);
```

**Next.js projects** — nothing to mount. Routes are file-based and ready as soon as they're generated, e.g.:
- `app/api/payment/initialize/route.js` (App Router) or `pages/api/payment/initialize.js` (Pages Router)
- `app/api/webhook/<provider>/route.js` (App Router) or `pages/api/webhook/<provider>.js` (Pages Router)

### Test it

**Paystack / Flutterwave** (amount conventions differ — see the table below):

```bash
curl -X POST http://localhost:3000/api/payment/initialize \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","amount":5000}'
```

**Hubtel:**

```bash
curl -X POST http://localhost:3000/api/payment/initialize \
  -H "Content-Type: application/json" \
  -d '{"amount":50,"description":"Order #123","callbackUrl":"http://localhost:3000/api/webhook/hubtel"}'
```

| Provider | Amount convention |
|---|---|
| Paystack | Smallest currency unit — `5000` = GHS/NGN 50.00 |
| Flutterwave | Main currency unit — `50` = GHS 50.00 |
| Hubtel | Main currency unit — `50` = GHS 50.00 |

Set your webhook/callback URL in your provider's dashboard once your app is publicly reachable (use [ngrok](https://ngrok.com) for local testing), and test with each provider's sandbox test credentials.

---

## Security

- Credentials are written **only** to your local `.env` (or `.env.local` for Next.js) — never transmitted anywhere else, never logged, never written to any other file.
- If you enter what looks like a live/production credential, the CLI warns you and asks for confirmation before proceeding (Paystack and Flutterwave only — Hubtel's credentials carry no detectable live/test marker, so no warning is possible there).
- The tool will never overwrite an existing file without your explicit confirmation (or the `--force` flag).
- **Make sure `.env` / `.env.local` is in your `.gitignore`.** The tool doesn't do this for you — check before you commit.

**Webhook verification, by provider:**
- **Paystack** — HMAC SHA512 over the raw request body, checked against the `x-paystack-signature` header.
- **Flutterwave** — HMAC SHA256 (base64) over the raw request body, checked against the `flutterwave-signature` header, using your Webhook Secret Hash.
- **Hubtel** — no signature exists to check. The generated route logs the callback and includes TODOs for the mitigations described in the [warning above](#-before-you-use-the-hubtel-option). Treat this integration as incomplete until you've implemented at least one of them.

All webhook/callback routes acknowledge quickly, as each provider expects, before running your business logic.

---

## What gets generated

**Payment route** — validates input, calls the provider's payment initialization endpoint, returns the checkout URL/link to redirect your customer to.

**Webhook route** — verifies the signature where one exists, handles the success event (with a clear `TODO` for your own logic), includes a basic in-memory duplicate-event guard, and acknowledges quickly. The in-memory guard is a starting point — swap it for a database or Redis-backed check before production if you're running multiple server instances.

---

## Options

```bash
afripayments-cli init --force
```

`--force` overwrites existing generated files instead of skipping them. Use with care.

---

## Roadmap

Planned, not yet built:
- TypeScript output for Hubtel and Flutterwave
- Django support
- Laravel support

Open an issue if you'd like to help with any of these.

---

## Contributing

Issues and pull requests are welcome. If you're adding a new provider or framework combination, please include a test showing the generated webhook/callback handler behaves correctly for both a valid and an invalid/malicious request — that's the part that matters most.

---

## License

MIT

afripayments-cli

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README