https://github.com/bakissation/fastify-satim
Fastify plugin for SATIM (SATIM-IPAY) payments — typed decorator, multi-tenant, built-in routes. CIB & Edahabia.
https://github.com/bakissation/fastify-satim
algeria cib edahabia fastify fastify-plugin fintech multi-tenant npm-package payment-gateway payments satim satim-ipay typescript
Last synced: about 1 month ago
JSON representation
Fastify plugin for SATIM (SATIM-IPAY) payments — typed decorator, multi-tenant, built-in routes. CIB & Edahabia.
- Host: GitHub
- URL: https://github.com/bakissation/fastify-satim
- Owner: bakissation
- License: mit
- Created: 2025-12-24T17:11:18.000Z (6 months ago)
- Default Branch: dev
- Last Pushed: 2026-05-22T19:20:17.000Z (about 1 month ago)
- Last Synced: 2026-05-22T21:59:54.386Z (about 1 month ago)
- Topics: algeria, cib, edahabia, fastify, fastify-plugin, fintech, multi-tenant, npm-package, payment-gateway, payments, satim, satim-ipay, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@bakissation/fastify-satim
- Size: 142 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# @bakissation/fastify-satim
A **Fastify plugin** for the [SATIM (SATIM-IPAY)](https://github.com/bakissation/satim-ts) payment gateway — drop SATIM **CIB & Edahabia** payments into any Fastify app with a typed `fastify.satim` decorator, optional built-in routes, schema validation, and multi-tenant support. Works with **Fastify v4 and v5**.
[](https://www.npmjs.com/package/@bakissation/fastify-satim)
[](https://github.com/bakissation/fastify-satim/actions/workflows/ci.yml)
[](./LICENSE)
- 🧩 **Typed decorator** — `fastify.satim` exposes the full SATIM client (`register`, `getOrderStatus`, `confirm`, `refund`) across all scopes.
- 🏢 **Multi-tenant** — resolve credentials per request via `getClient(request)`, or stay single-tenant with env vars / a config object / a pre-built client.
- 🛣️ **Built-in routes (opt-in)** — `/register`, `/status`, `/confirm`, `/refund` with JSON-schema validation and per-route hooks — or wire your own.
- 🔒 **Secure by default** — centralized error mapping that never leaks credentials, POST-only by default, no secret logging.
> 📖 **[Read the case study →](https://berkati.xyz/case-studies/fastify-satim-plugin/)** — how this plugin cuts SATIM integration from hundreds of lines of boilerplate per project to a single `register()` call.
## Install
```bash
npm install @bakissation/fastify-satim
```
Requires **Node.js ≥ 18** and **Fastify v4 or v5**. The core SDK [`@bakissation/satim`](https://github.com/bakissation/satim-ts) is included.
## Quick start
```typescript
import Fastify from 'fastify';
import fastifySatim, { interpretOrderStatus } from '@bakissation/fastify-satim';
const fastify = Fastify();
await fastify.register(fastifySatim, { fromEnv: true });
fastify.post('/checkout', async (request, reply) => {
const order = await fastify.satim.register({
orderNumber: 'ORD001',
amount: 5000, // 5000 DZD
returnUrl: 'https://yoursite.com/payment/success',
udf1: 'INV001',
});
if (order.isSuccessful()) return { redirectUrl: order.formUrl };
return reply.status(400).send({ error: 'Failed to create order' });
});
fastify.post('/payment/callback', async (request) => {
const { orderId } = request.body as { orderId: string };
const status = await fastify.satim.getOrderStatus(orderId);
return status.isPaid() ? { status: 'paid' } : { status: interpretOrderStatus(status.orderStatus) };
});
await fastify.listen({ port: 3000 });
```
There are four ways to configure the client (multi-tenant, env, object, pre-built) → **[docs/configuration](./docs/configuration.md)**.
## Documentation
Full docs live in **[`docs/`](./docs/)**:
| | |
|---|---|
| [Overview & concepts](./docs/overview.md) | What the plugin is, when to use it vs the raw SDK, design notes |
| [Getting started](./docs/getting-started.md) | Install, register, first payment, environments |
| [Configuration](./docs/configuration.md) | The four config modes (multi-tenant, env, object, client) |
| [Built-in routes](./docs/routes.md) | `/register` · `/status` · `/confirm` · `/refund` — paths, hooks, bodies |
| [Security](./docs/security.md) | Auth, CSRF, error mapping, best practices |
| [Architecture](./docs/architecture.md) | Module map, plugin lifecycle, routes, error handling |
For the SATIM gateway API, environments, and certification, see the [core SDK docs](https://github.com/bakissation/satim-ts/tree/main/docs).
## Contributing
Issues and PRs welcome — read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). Releases are automated from [Conventional Commits](https://www.conventionalcommits.org/) via semantic-release; **don't bump the version or edit the changelog by hand**.
## Credits
Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation).
📖 [Read the case study →](https://berkati.xyz/case-studies/fastify-satim-plugin/)
## License
[MIT](./LICENSE)