> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dmly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Flutterwave

> Collect card, bank-transfer and mobile-money payments across Africa with Flutterwave, in naira and every other currency your account takes.

Flutterwave is a payment gateway built for African businesses. A pay link opens Flutterwave's own hosted
checkout, where your client pays by card, bank transfer, USSD or mobile money (whatever your account has
switched on for that currency), and Flutterwave tells DMLY the money arrived. You share that link on
WhatsApp like any other pay link.

It is Nigeria-first like Paystack and Monnify, but not Nigeria-only: one Flutterwave account can collect
NGN, GHS, KES, ZAR, UGX, TZS, RWF, XOF, XAF, EGP, USD, GBP, EUR and more.

This page covers what's specific to Flutterwave. The general rules (how pay links are minted, what each
payment status means, what a missed webhook looks like) are the same for every gateway and live in
[Connect a payment gateway](https://docs.dmly.io/finance/payments-and-gateways.md).

## Connect it

Flutterwave is a tile under **Configurations → Integrations → Payments**. There's no "sign in with
Flutterwave" button: you copy one key out of your Flutterwave dashboard, make up one value of your own,
and paste both in.

**1. Copy your secret key**

In your Flutterwave dashboard, open **Settings → API Keys** and copy your **secret key**. It starts
with `FLWSECK`. The **public key** (`FLWPUBK`) sits right beside it and is not the one DMLY needs;
paste it by mistake and the tile tells you so.

There is no environment dropdown in DMLY. **The key decides whether you are taking real money:**
`FLWSECK_TEST-…` is test mode and `FLWSECK-…` is live. Check it before you paste.

**2. Choose a secret hash**

Flutterwave does not hand you a webhook secret; you invent one. Make up a long random value (a
password manager's generator is ideal) and type it into the tile's **Secret hash** field. You will
type the same value into Flutterwave in a moment.

**3. Connect**

Paste the secret key into its field and click **Connect**. DMLY checks the key with Flutterwave
straight away, so a typo fails now rather than at the first real payment. The webhook URL appears on
the tile once you're connected.

**4. Add the webhook in Flutterwave**

DMLY does not register the webhook for you. In Flutterwave, go to **Settings → Webhooks**, paste the
URL from the tile, enter the **same secret hash** you typed into DMLY, tick every box (webhook
retries included) and save.

Test mode and live mode each have their own webhook settings in the Flutterwave dashboard. Set the
URL and secret hash in the mode your key belongs to.

**5. Take one real payment end to end**

Send yourself a small invoice, pay it, and confirm it flips to **Paid** on its own. If it doesn't,
the webhook isn't reaching DMLY; fix that before a client pays.

> [!WARNING]
>
> **No secret hash, no paid invoices.** Flutterwave sends your secret hash with every webhook, and DMLY
> refuses any webhook whose hash doesn't match the one saved on the tile. If the field is empty, the tile
> shows a red warning: the gateway connects and clients can pay, but nothing is ever marked paid until
> you add it.

> [!TIP]
>
> Unlike Monnify, Flutterwave's test mode works end to end. With a `FLWSECK_TEST-…` key and the webhook
> set in test mode, a payment made with one of Flutterwave's published test cards is confirmed in DMLY
> exactly as a real one would be, so you can rehearse the whole flow before switching to your live key.

## How DMLY confirms a payment

A Flutterwave webhook is treated as a hint, not proof. When one says a payment completed, DMLY asks
Flutterwave's own verification service about that transaction and uses only what Flutterwave confirms:
the status, the amount, the currency and the reference. A message that claims more than Flutterwave
will confirm changes nothing.

> [accordion] The client paid less than asked, or in another currency
>
> DMLY does **not** mark the payment as paid. A booking isn't confirmed and the client isn't sent a
> receipt. Your team gets a **Paid amount differs from the bill** alert, and the details are in
> **Reports → Logs**. Talk to the client, then either record the payment yourself under
> **Finance → Payments** or refund it.

> [accordion] The client paid more than asked
>
> The payment is marked paid at the amount you billed, and your team gets the same alert, because the
> client is owed the difference.

> [accordion] A card was declined
>
> Nothing changes on the payment. Flutterwave's page lets the client try again on the same link, so a
> declined attempt is not treated as the end of the checkout. A pay-before booking hold simply runs to
> its normal length.

These alerts are the **Payment needs review** event on the **In-app alerts** tab of
[notification settings](https://docs.dmly.io/account/notifications.md). It is on by default, and an admin can turn it off.

## Card or bank transfer

A Flutterwave pay link offers every method your account has switched on for the link's currency. In a
payment step, set **Payment method** to **Bank transfer only** and the checkout opens on a one-time
account number, as it does on Paystack. **Card only** restricts it to card. A bank-transfer link holds
a pay-before booking for the longer transfer time (see [Appointment payments](https://docs.dmly.io/appointments/payments.md)).

> [!NOTE]
>
> Flutterwave only honours that restriction while **Disable preferred payment methods** is off in your
> Flutterwave business preferences. If it's on, the link opens on every method whatever the step says.

**Let the customer choose** asks **Card** or **Bank transfer** only when you have also saved your own
bank account under **Finance → Settings → Gateways**; with Flutterwave alone, the client gets the pay
link straight away, because Flutterwave's page already offers both. See
[Collect bank transfers in chat](https://docs.dmly.io/finance/pay-with-transfer.md#let-the-client-choose).

## Refunds

The **Refund** button refunds through Flutterwave, in full or in part, for any payment method. The money
comes out of your Flutterwave balance, and the smallest refund Flutterwave accepts is NGN 100 (KES 10 in
Kenya).

If Flutterwave refuses the refund request, nothing changes in DMLY and you see Flutterwave's reason. If
it accepts the request, DMLY marks the payment **Refunded** straight away, while Flutterwave finishes the
refund in the background: card refunds can take 3 to 15 days to reach the client, bank refunds about a
day.

To have refunds you make **in the Flutterwave dashboard** show up in DMLY too, switch on Flutterwave's
refund webhook with the same URL. Should Flutterwave report that a refund failed, your team gets a
**Refund failed** alert and the reason is in **Reports → Logs**.

## Current limitations

These are known behaviours of the Flutterwave integration today, not faults to report.

> [accordion] Subscriptions can't auto-charge a saved card yet
>
> DMLY doesn't save Flutterwave cards for automatic renewals yet. A subscription on Flutterwave is
> collected with a pay link each cycle. Use another gateway for automatic renewals (see
> [Subscriptions](https://docs.dmly.io/finance/subscriptions.md)).

> [accordion] No account number in the chat
>
> **Account number in chat (automatic)** is a Monnify feature. On Flutterwave, **Bank transfer only**
> puts the account number behind the link instead.

> [accordion] A currency your account can't take fails when the link is made
>
> DMLY passes the currency straight to Flutterwave, so a pay link in a currency your Flutterwave account
> hasn't enabled fails when it is made, with Flutterwave's reason.

> [card] [Payments and gateways](https://docs.dmly.io/finance/payments-and-gateways.md)
>
> Pay links, payment statuses and what a failed webhook means.

> [card] [Collect bank transfers in chat](https://docs.dmly.io/finance/pay-with-transfer.md)
>
> Transfer-only links, your own account details, and letting the client choose.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.