---
name: bijection-flutterwave
description: "Evaluate and integrate the Flutterwave component with Bijection."
---

# Flutterwave

Accept payments and subscriptions with Flutterwave in your Bijection app. Reactive transactions, subscription state, and webhook ingestion.

- Package: @bijectionhq/flutterwave
- Category: Payments
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/flutterwave/tree/ff819b7f2ac077662bd75af145b0cfd9eaa27926
- Upstream: https://github.com/sholajegede/convex-flutterwave/tree/b32212a948620424d6b1c2f50bed1e7104ee1ea1
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/flutterwave

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/flutterwave.git
cd flutterwave
git checkout ff819b7f2ac077662bd75af145b0cfd9eaa27926
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-flutterwave. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex Flutterwave. Follow the installation and configuration steps exactly.

# Convex Flutterwave

## Instructions

convex-flutterwave integrates Flutterwave's v3 Standard payment API into Convex, handling webhook ingestion, signature verification, and local state persistence so you do not have to build that infrastructure yourself. It exposes reactive queries for transaction and subscription state, server-side verification, plan management, and subscription lifecycle controls. Duplicate webhook deliveries are detected and skipped automatically.

### Installation

```bash
npm install convex-flutterwave
```

Current npm version: `convex-flutterwave@0.0.5`

## Use cases

- Adding one-time payment checkout to a Convex app where you need server-side transaction verification and reactive UI updates after payment completes
- Building subscription billing with recurring payment plans, where you need to reactively check whether a customer has an active subscription before granting access
- Ingesting Flutterwave webhooks without writing your own HTTP handler, signature verification logic, or database schema
- Syncing subscription state after a plan-linked checkout because Flutterwave does not emit a subscription-created webhook event
- Displaying a customer's full transaction history from Convex queries rather than polling the Flutterwave API on every request

## How it works

You register the component in `convex/convex.config.ts`, set two environment variables (`FLW_SECRET_KEY` and `FLW_WEBHOOK_SECRET_HASH`), and mount `flutterwave.webhookHandler` on an HTTP route in `convex/http.ts`. The component verifies the `verif-hash` header on every inbound request, then writes the parsed event into its own Convex tables. Duplicate event delivery is handled with idempotency checks before any write occurs.

Checkout starts with `initializeTransaction()`, which calls Flutterwave's `/v3/payments` endpoint, records a pending transaction keyed by `tx_ref`, and returns a hosted payment link. After the customer completes payment and Flutterwave redirects back to your `redirectUrl`, you call `verifyTransaction()` with the `transaction_id` query param to confirm the final status server-side. The `charge.completed` webhook also updates the local record when it arrives, typically within a few seconds of the payment event.

Subscription plans are created with `createPaymentPlan()` and attached to a checkout by passing `paymentPlan` to `initializeTransaction()`. Because Flutterwave does not emit a subscription-created webhook, you call `syncCustomerSubscriptions()` after a successful plan-linked checkout to pull live subscription state from Flutterwave's List Subscriptions endpoint and upsert it locally. After that initial sync, `hasActiveSubscription()` and `cancelSubscription()` / `enableSubscription()` operate against the local Convex state kept in sync by subsequent webhooks.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Flutterwave is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-flutterwave)
- [GitHub repository](https://github.com/sholajegede/convex-flutterwave)
- [Live demo](https://convex-flutterwave.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-flutterwave)
- [Convex documentation](https://docs.convex.dev)