Flovide API Documentation

Authentication

The Flovide API uses your Public Key and Secret Key to authenticate requests. Include both keys in the request headers. Your public key identifies your account, while your secret key authorizes access.

All API requests must be made over HTTPS. Never expose your secret key in frontend code or public repositories.

Security

Store your secret key only on the server side. Use your public key for identification and your secret key for authorization.

Balances API

Reference

GET /api/v1/balances

List all balances

Returns all balances that belong to the matched account.

Parameters

currency String

Optional

GET /api/v1/balances/{id}

Fetch single balance

Returns one balance record for the matched account.

Path Parameter

id Integer

Required

POST /api/v1/balances

Create a balance

Creates a new balance for the matched account.

Body Parameters

name

Required

currency

Required

Beneficiaries API

Reference

POST /api/v1/beneficiaries/account-inquiry

Account Inquiry

Validate recipient details before creating a beneficiary.

Body Parameters

currency

Required

bank_code

Required

account_number

Required

POST /api/v1/beneficiaries

Create beneficiary

Creates a beneficiary for the matched account.

Body Parameters

type

Required (Individual or Corporate)

firstNames

Individual

lastName

Individual

name

Corporate

transfer_method

Required (bank or mobile)

bank.country

Required

bank.currency

Required

bank.accountHolder

Required (non-CAD)

bank.accountNumber

Required (Bank)

bank.bankCode

Required (Bank)

bank.mobileNumber

Required (Mobile, alt. to accountNumber)

bank.interac_first_name

Required (CAD)

bank.interac_last_name

Required (CAD)

bank.interac_email

Required (CAD)

GET /api/v1/beneficiaries

List beneficiaries

Returns all beneficiaries for the matched account.

GET /api/v1/beneficiaries/{id}

Fetch single beneficiary

Returns one beneficiary record for the matched account.

Path Parameter

id Integer

Required

DELETE /api/v1/beneficiaries/{id}

Delete beneficiary

Deletes a beneficiary by ID for the matched account.

Path Parameter

id Integer

Required

Transactions API

Reference

GET /api/v1/transactions

List transactions

Returns all transactions for the matched account.

GET /api/v1/transactions/{id}

Fetch single transaction

Returns one transaction record for the matched account.

Path Parameter

id Integer

Required

POST /api/v1/transactions

Initiate transaction

Creates a new transaction for the matched account.

Path Parameter

order_id Random UUID generate by you

Required

reference Random UUID generate by you

Required

Collections API

Reference

POST /api/v1/collections/interac

Interac collection (top-up)

Sends an Interac Auto Deposit money request to the payer's email. Your CAD wallet is credited automatically once the payer approves. The collection fee (configured per account) is deducted from the amount before crediting.

Body Parameters

amount

Required

email

Required (payer's email)

DASHBOARD Interac Auto Deposit (CAD)

Setting up Auto Deposit

Auto Deposit is a standing setup, not an API call. Once you register an email address for a CAD wallet, anyone who sends an Interac e-Transfer to that email is credited to your wallet automatically — no request needs to be sent first, and no collections/interac call is required for each payment.

There is no API endpoint for this — Auto Deposit emails are registered from your dashboard, since they're a wallet-level setting rather than a per-transaction request.

Where to set it up

Go to Wallets in your dashboard and open your CAD wallet.
Under Account Details, find the Interac Auto Deposit panel and click Manage Auto Deposit Emails.
Click Add Email and enter the email address you want customers to send e-Transfers to. Auto Deposit emails must end with @flovide.com, for example payment@flovide.com.
You can register more than one email per wallet — useful if you route different products or channels to different addresses.

Once an email is active, any e-Transfer sent to it is matched to your wallet and credited automatically, and you'll receive a transaction.success webhook just like any other collection — see the Webhooks section for the payload shape.

Rates API

Reference

GET /api/v1/rates

Get exchange rate

Returns exchange rate and transfer fee for a currency pair.

Query Params

from_currency

Required

to_currency

Required

amount

Optional

Reference Data API

Reference

GET /api/v1/reference-data/currencies

Currencies only

Returns all supported currencies.

GET /api/v1/reference-data/banks

Banks only

Returns banks, optionally filtered by country_iso and currency.

Query Params

country_iso

Optional

currency

Optional

Webhooks

Flovide sends a webhook to your webhook_url whenever a transaction changes status. Configure your endpoint from the Webhooks settings panel — this also generates your webhook secret_key, used to sign every payload.

Always verify the X-Flovide-Signature header before trusting a webhook payload. Never process a webhook you haven't verified.

Event Types

transaction.success

Sent when a transaction's status resolves to success — a deposit is credited, a payout clears, or a collection completes.

transaction.failed

Sent when a transaction's status resolves to failed — a payout is declined or a collection is rejected.

Payload

Every webhook request is a POST with a JSON body in this shape:

Example Payload

{
                  "event": "transaction.success",
                  "data": {
                    "id": "019f6bb5-7f5f-724d-8999-8a86b98c0f2a",
                    "reference": "CAyAHe1XxpDs",
                    "order_id": "TEST_ae8cda30-f4a8-4c0f-a873-40e3d9436d70",
                    "transaction_type": "payout",
                    "status": "success",
                    "amount": 100.00,
                    "currency": "NGN",
                    "balance_id": "b6820b8a-2434-11f1-a9fd-84a93e49c6d5",
                    "created_at": "2026-07-16T16:14:44+00:00",
                    "updated_at": "2026-07-16T16:15:02+00:00"
                  },
                  "created_at": "2026-07-16T16:15:02+00:00"
                }

Headers

Header	Description
X-Flovide-Signature	HMAC-SHA256 hex digest of the raw request body, signed with your webhook `secret_key`.
X-Flovide-Event	The event type, matching the `event` field in the body (e.g. `transaction.success`).

Verifying the Signature

Compute an HMAC-SHA256 digest of the raw request body using your secret key, then compare it to the X-Flovide-Signature header using a constant-time comparison.

$payload = file_get_contents('php://input');
                $signature = $_SERVER['HTTP_X_FLOVIDE_SIGNATURE'] ?? '';
                $secret = 'your_webhook_secret_key';

                $expected = hash_hmac('sha256', $payload, $secret);

                if (!hash_equals($expected, $signature)) {
                    http_response_code(401);
                    exit('Invalid signature');
                }

                $event = json_decode($payload, true);
                // process $event['event'] / $event['data'] ...

const crypto = require('crypto');

                function verifyWebhook(rawBody, signature, secret) {
                  const expected = crypto
                    .createHmac('sha256', secret)
                    .update(rawBody)
                    .digest('hex');

                  return crypto.timingSafeEqual(
                    Buffer.from(expected),
                    Buffer.from(signature)
                  );
                }

                // Express example
                app.post('/webhooks/flovide', express.raw({ type: 'application/json' }), (req, res) => {
                  const signature = req.headers['x-flovide-signature'];
                  const valid = verifyWebhook(req.body, signature, process.env.FLOVIDE_WEBHOOK_SECRET);

                  if (!valid) return res.status(401).send('Invalid signature');

                  const event = JSON.parse(req.body);
                  // process event.event / event.data ...
                  res.sendStatus(200);
                });

import hmac
                import hashlib
                import json

                def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
                    expected = hmac.new(
                        secret.encode(),
                        raw_body,
                        hashlib.sha256
                    ).hexdigest()
                    return hmac.compare_digest(expected, signature)

                # Flask example
                @app.route('/webhooks/flovide', methods=['POST'])
                def flovide_webhook():
                    signature = request.headers.get('X-Flovide-Signature', '')
                    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
                        return 'Invalid signature', 401

                    event = request.get_json()
                    # process event['event'] / event['data'] ...
                    return '', 200

Retry Policy

If your endpoint doesn't respond with a 2xx status, Flovide retries delivery up to 5 times with increasing backoff:

Attempt	Delay After Previous Failure
1	10 seconds
2	30 seconds
3	2 minutes
4	10 minutes
5	30 minutes

Respond quickly — return a 200 immediately, then process the event asynchronously if it requires heavier work. Your endpoint should be idempotent, since the same event may be delivered more than once.

Error Handling

All errors return a consistent structure: success, message, code, and optional errors/data.

Error Response Example

{
                  "success": false,
                  "message": "Validation failed",
                  "code": "VALIDATION_ERROR",
                  "errors": {
                    "amount": ["The amount field is required."]
                  },
                  "data": null
                }

HTTP Status	Error Code	Meaning
400	BAD_REQUEST	Malformed or invalid request payload.
401	UNAUTHORIZED	Missing or invalid authentication credentials/API keys.
403	FORBIDDEN	Authenticated but not allowed to perform this action.
404	NOT_FOUND	Requested resource was not found.
422	VALIDATION_ERROR	Validation failed for one or more request fields.
422	INSUFFICIENT_FUNDS	Wallet balance is not enough to complete the transaction.
500	SERVER_ERROR	Unexpected internal server error occurred.
500	TXN_FAILED	Transaction processing failed on the server/provider side.

Official SDKs

NodeJS

PHP

Python

Java

Build clean, reliable money flows

1 Quick Start Guide

Create Account

Generate Keys

Make Request

Authentication

Security

Balances API

List all balances

Fetch single balance

Create a balance

Beneficiaries API

Account Inquiry

Create beneficiary

List beneficiaries

Fetch single beneficiary

Delete beneficiary

Transactions API

List transactions

Fetch single transaction

Initiate transaction

Collections API

Interac collection (top-up)

Setting up Auto Deposit

Where to set it up

Rates API

Get exchange rate

Reference Data API

Currencies only

Banks only

Webhooks

Event Types

transaction.success

transaction.failed

Payload

Headers

Verifying the Signature

Retry Policy

Error Handling

Official SDKs