Master Wallet Payouts

Overview

FossaPay supports business-funded payouts directly from your permanent NGN master wallet, as well as the existing customer-funded transfer APIs. Choose the flow based on who owns the source funds.

Flow	Source	Destination	Fee behavior
Master Wallet Payout	Your business master NGN wallet	Same-business customer, another FossaPay business, or an external bank	Free within the same business; payout fee otherwise
Bulk Payout	Your business master NGN wallet or a subaccount owned by your business	Multiple Nigerian bank accounts supplied in a CSV file	Existing payout fee applied to every recipient row
Wallet-to-Wallet Transfer	A customer wallet	Another customer wallet under the same business	Free
Customer Inter-Bank Transfer	A customer wallet selected with `customerId`	External Nigerian bank account	Applicable transfer fee

Use the Master Wallet Payout API when the funds belong to the business. It derives the source wallet from your API key, so you do not provide a customerId, source wallet ID, or source account number.

Prerequisites

A verified FossaPay business
An active production API key with full permission
An active permanent NGN master wallet
Sufficient available balance for the payout amount and any applicable fee
A webhook endpoint configured with your webhook secret

No separate payout API key, IP allowlisting, or per-merchant payout activation is required.

How Master Wallet Routing Works

FossaPay looks up the submitted destination account number before moving funds.

Same business

When the destination is an active customer wallet owned by your business:

route is same_business
fee is 0.00
totalDebited equals amount
the transfer can complete immediately

Another FossaPay business

When the destination is an active FossaPay wallet owned by another business:

route is fossapay_cross_business
the configured payout fee applies
the payout is processed through the charged payout rail

External bank

When the destination account is not a FossaPay wallet:

route is external_bank
the configured payout fee applies
a final provider result is delivered asynchronously

Do not attempt to select the route in your request. Always send verified beneficiary details; FossaPay determines the route from the destination account number.

Validate the Beneficiary

Retrieve supported banks and perform a name enquiry before creating the payout.

curl --request POST \
  --url https://api-production.fossapay.com/api/v1/transfers/fiat/bank-name-enquiry \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "accountNumber": "0123456789",
    "bankCode": "058"
  }'

Compare the returned name with your intended beneficiary before proceeding.

Create a Payout

Generate one idempotency key for each logical payout and persist it with your reference.

import crypto from 'node:crypto';

const reference = 'PAYOUT-10025';
const idempotencyKey = crypto.randomUUID();

const response = await fetch(
  'https://api-production.fossapay.com/api/v1/payouts',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.FOSSAPAY_API_KEY,
      'X-Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 5000,
      currency: 'NGN',
      reference,
      destinationBankCode: '058',
      destinationBankName: 'Guaranty Trust Bank',
      destinationAccountName: 'JOHN DOE',
      destinationAccountNumber: '0123456789',
      remarks: 'Vendor settlement',
      metadata: {
        invoiceId: 'INV-10025'
      }
    })
  }
);

const result = await response.json();

The beneficiary receives amount. For charged routes, your master wallet is debited by amount + fee, exposed as totalDebited.

Handle the Initial Status

HTTP 202 means the request was accepted—not necessarily that the beneficiary has received the money.

If data.status is completed, the payout is final and successful.
If it is processing, store payoutId, transactionId, reference, and providerReference, then wait for a webhook or retrieve the payout.
Never submit a second payout with a new idempotency key because the first request timed out.

Reconcile a Payout

Retrieve by FossaPay payout ID:

curl https://api-production.fossapay.com/api/v1/payouts/PAYOUT_ID \
  -H "x-api-key: $FOSSAPAY_API_KEY"

Or retrieve by your unique reference:

curl https://api-production.fossapay.com/api/v1/payouts/reference/PAYOUT-10025 \
  -H "x-api-key: $FOSSAPAY_API_KEY"

Use reference lookup when you do not know whether a create request reached FossaPay.

Endpoint map

Operation	Endpoint	Reference
Create a payout	`POST /api/v1/payouts`	Create payout
Get payout by ID	`GET /api/v1/payouts/{id}`	Get payout
Get payout by reference	`GET /api/v1/payouts/reference/{reference}`	Get payout by reference

Process Payout Webhooks

Master-wallet payouts emit:

payout.completed
payout.failed
payout.reversed

app.post('/webhooks/fossapay', (req, res) => {
  if (!verifyFossaPaySignature(req.body.data, req.get('x-fossapay-signature'))) {
    return res.sendStatus(401);
  }

  res.sendStatus(200);

  const { eventId, eventType, data } = req.body;
  enqueueWebhook(async () => {
    if (await eventWasProcessed(eventId)) return;

    switch (eventType) {
      case 'payout.completed':
        await markPayoutCompleted(data.reference, data);
        break;
      case 'payout.reversed':
        await markPayoutReversed(data.reference, data);
        break;
      case 'payout.failed':
        await flagPayoutForReview(data.reference, data);
        break;
    }

    await recordProcessedEvent(eventId);
  });
});

FossaPay signs JSON.stringify(body.data) with HMAC-SHA256. See Webhook Verification for complete Node.js and Python examples.

Idempotency Rules

Reuse the key only for the same request

The same request body and idempotency key return the existing payout. A different body with that key returns HTTP 409.

Keep references unique

A payout reference is unique per merchant. Use your own order, invoice, or withdrawal identifier so support and reconciliation are straightforward.

Resolve ambiguous responses before retrying

If the connection fails after submission, retrieve by reference. If found, continue tracking that payout. If it is not found, retry the identical body with the original idempotency key.

Terminal States

Status	Action
`completed`	Mark the payout successful.
`reversed`	Mark it unsuccessful; the payout funds were returned.
`failed`	Mark it failed and retrieve the latest state. Contact FossaPay support if funds still appear reserved.

Do not deliberately retry a terminal payout under a new reference without making a new business decision in your own system.

Go-Live Checklist

Next Steps

Create Master Wallet Payout

Send directly from your business funds

Get Payout by ID

Retrieve the latest payout status

Wallet-to-Wallet Transfer

Customer-funded transfers within one business

Webhook Events

See complete payout event payloads

Bulk Payouts

Submit and reconcile immediate CSV payout batches

Getting Started

Core Concepts

Guides

AI Tools

Master Wallet Payouts

Overview

Prerequisites

How Master Wallet Routing Works

Same business

Another FossaPay business

External bank

Validate the Beneficiary

Create a Payout

Handle the Initial Status

Reconcile a Payout

Endpoint map

Process Payout Webhooks

Idempotency Rules

Terminal States

Go-Live Checklist

Next Steps

Create Master Wallet Payout

Get Payout by ID

Wallet-to-Wallet Transfer

Webhook Events

Bulk Payouts

​Overview

​Prerequisites

​How Master Wallet Routing Works

​Same business

​Another FossaPay business

​External bank

​Validate the Beneficiary

​Create a Payout

​Handle the Initial Status

​Reconcile a Payout

​Endpoint map

​Process Payout Webhooks

​Idempotency Rules

​Terminal States

​Go-Live Checklist

​Next Steps

Create Master Wallet Payout

Get Payout by ID

Wallet-to-Wallet Transfer

Webhook Events

Bulk Payouts

Overview

Prerequisites

How Master Wallet Routing Works

Same business

Another FossaPay business

External bank

Validate the Beneficiary

Create a Payout

Handle the Initial Status

Reconcile a Payout

Endpoint map

Process Payout Webhooks

Idempotency Rules

Terminal States

Go-Live Checklist

Next Steps