Fee Management API: Configure, Track & Withdraw Fees

Use the Fee Management API to configure the fee structures applied to your users’ onramp and offramp transactions, monitor accumulated fee balances broken down by transaction type, and withdraw earned fees directly to a bank account of your choice.

Endpoints overview

Section	Endpoint	Method	Description
Withdrawal History	`/getwithdrawalhistory`	GET	Retrieve paginated history of all fintech fee withdrawals
Fee Withdrawal	`/feewithdrawal`	POST	Request withdrawal of accumulated fees to a bank account
Accumulated Fees	`/getaccumulatedfees`	GET	Get a summary of accumulated fees and available withdrawal balance
Manage Fees	`/managefees`	PUT	Configure onramp and offramp fee percentages, caps, and toggles
Get Fees	`/getfees`	GET	Retrieve the current fee configuration and example calculations
Strails Fee Preview	`/fees/strails/preview`	POST	Preview the Strails platform fee for a given amount and transaction type
Verify Withdrawal	`/verifywithdrawal`	POST	Check the status or outcome of a previously submitted withdrawal

GET /getwithdrawalhistory

Retrieve a paginated list of all fee withdrawal requests for your fintech account. Filter by status to isolate completed, pending, or failed withdrawals.

This endpoint supports query parameters for pagination and filtering by status. Use limit to control page size and status to filter by a specific withdrawal outcome.

Query parameters

number

Maximum number of records to return per page. Defaults to 20.

string

Filter withdrawals by status. Accepted values: pending, completed, failed.

Request

curl --request GET \
  --url "{{BASE_URL}}/getwithdrawalhistory?limit=20&status=completed" \
  --header "x-api-key: YOUR_API_KEY"

Response

string

High-level result of the request. "Success" on success.

string

Machine-readable status code. "00" indicates success.

string

Human-readable description of the result.

array

Array of withdrawal records matching the query.

Show Withdrawal object fields

string

Unique identifier for the withdrawal transaction.

number

Withdrawal amount in the smallest currency unit (kobo).

string

Destination bank account number (partially masked in responses).

string

NIBSS bank code for the destination bank.

string

Name of the destination account holder.

string

Description provided at the time of the withdrawal request.

string

Current status of the withdrawal: pending, completed, or failed.

string

ISO 8601 timestamp when the withdrawal was submitted.

string

ISO 8601 timestamp when the withdrawal was settled. null if not yet processed.

string

Human-readable reason for failure. null if the withdrawal succeeded.

object

Pagination metadata for the result set.

Show Pagination fields

number

Number of records returned in this page.

number

The limit applied to this request.

boolean

true if additional pages exist beyond this result.

{
  "status": "Success",
  "response_code": "00",
  "message": "Withdrawal history retrieved successfully",
  "data": {
    "withdrawals": [
      {
        "withdrawalId": "FTW_your_fintech_id_1725444600000",
        "amount": 50000,
        "bankAccountNumber": "123456****",
        "bankCode": "058",
        "accountName": "YOUR COMPANY NAME",
        "narration": "Fee withdrawal for August 2025",
        "status": "completed",
        "createdAt": "2025-09-04T10:30:00.000Z",
        "processedAt": "2025-09-04T12:15:00.000Z",
        "failureReason": null
      }
    ],
    "pagination": {
      "count": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

POST /feewithdrawal

Submit a request to withdraw accumulated fees to a destination bank account. Withdrawals are processed within 1-3 business days.

Body parameters

string

required

Destination bank account number.

string

required

NIBSS bank identifier code for the destination bank (e.g., "058" for GTBank).

string

required

Full name of the account holder at the destination bank.

number

required

Amount to withdraw, expressed in the smallest currency unit (kobo). Must not exceed your available balance or fall below the minimum withdrawal threshold.

string

Optional description for this withdrawal (e.g., "Fee withdrawal for August 2025").

object

Optional additional data to attach to the withdrawal.

Show metadata fields

string

Your own unique reference ID for this transaction.

string

Free-text notes or comments about the withdrawal.

Request

curl --request POST \
  --url "{{BASE_URL}}/feewithdrawal" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "bankAccountNumber": "1234567890",
    "bankCode": "058",
    "accountName": "YOUR COMPANY NAME",
    "amount": 50000,
    "narration": "Fee withdrawal for August 2025",
    "metadata": {
      "reference": "FEE_WITHDRAWAL_AUG_2025",
      "notes": "Monthly fee withdrawal"
    }
  }'

Response

string

Unique identifier assigned to this withdrawal. Use it with /verifywithdrawal to poll the outcome.

number

The withdrawal amount that was submitted, in kobo.

string

Initial status of the withdrawal. Always "pending" on successful submission.

string

Estimated time for the withdrawal to settle to the destination bank account.

{
  "status": "Success",
  "response_code": "00",
  "message": "Withdrawal request submitted successfully",
  "data": {
    "withdrawalId": "FTW_your_fintech_id_1725444600000",
    "amount": 50000,
    "status": "pending",
    "estimatedProcessingTime": "1-3 business days"
  }
}

Error responses

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount exceeds available balance"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount is below minimum withdrawal threshold"
}

GET /getaccumulatedfees

Retrieve a real-time summary of your accumulated fees, broken down by transaction direction (onramp vs offramp), collection status, and withdrawal availability.

Request

curl --request GET \
  --url "{{BASE_URL}}/getaccumulatedfees" \
  --header "x-api-key: YOUR_API_KEY"

Response

number

Total fees earned across all transactions since account creation, in kobo.

number

Fees earned specifically from onramp (fiat-to-crypto) transactions, in kobo.

number

Fees earned specifically from offramp (crypto-to-fiat) transactions, in kobo.

number

Fees that have been fully collected and settled, in kobo.

number

Fees that are accrued but not yet finalized, in kobo.

number

Total number of fee-generating transactions.

number

Total amount currently locked in pending withdrawal requests, in kobo.

number

Net balance you can withdraw right now, in kobo (collected fees minus pending withdrawals). In the example below, 100000 is ₦1,000.00. Compare /feewithdrawal amounts against this figure, not against totalAccumulatedFees.

object

Additional account-level configuration details.

Show details fields

string

Currency in which fees are denominated (e.g., "NGN").

number

Minimum amount required to submit a withdrawal request, in kobo (1000 = ₦10.00).

number

Maximum amount allowed per withdrawal request, in kobo (10000000 = ₦100,000.00).

{
  "status": "Success",
  "response_code": "00",
  "message": "Accumulated fees retrieved successfully",
  "data": {
    "summary": {
      "totalAccumulatedFees": 125000,
      "onrampFees": 100000,
      "offrampFees": 25000,
      "collectedFees": 120000,
      "pendingFees": 5000,
      "transactionCount": 150,
      "pendingWithdrawals": 20000,
      "availableForWithdrawal": 100000
    },
    "details": {
      "lastUpdated": "2025-09-04T10:30:00.000Z",
      "currency": "NGN",
      "minimumWithdrawal": 1000,
      "maximumWithdrawal": 10000000
    }
  }
}

PUT /managefees

Configure the fee structure applied to your users’ transactions. You can set an independent percentage fee and cap for onramp and offramp directions, and enable or disable each independently.

Both onrampFee and offrampFee are optional in a single request - omit whichever object you do not want to update. Fields within an included object are required.

Body parameters

object

Fee configuration for onramp (fiat-to-cNGN) transactions.

Show onrampFee fields

number

required

Fee percentage to charge on each onramp transaction (e.g., 1.5 for 1.5%).

number

required

Maximum fee amount in kobo that can be charged regardless of transaction size.

boolean

required

Set to true to activate this fee or false to waive it entirely.

object

Fee configuration for offramp (cNGN-to-fiat) transactions.

Show offrampFee fields

number

required

Fee percentage to charge on each offramp transaction (e.g., 2.0 for 2%).

number

required

Maximum fee amount in kobo that can be charged regardless of transaction size.

boolean

required

Set to true to activate this fee or false to waive it entirely.

object

Optional notes to attach to this configuration change for your own audit trail.

Show metadata fields

string

Short description of why the fee configuration is being updated.

string

Additional context or rationale for the change.

string

Email or identifier of the administrator making this change.

Request

curl --request PUT \
  --url "{{BASE_URL}}/managefees" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "onrampFee": {
      "percentageFee": 1.5,
      "capFee": 500,
      "enabled": true
    },
    "offrampFee": {
      "percentageFee": 2.0,
      "capFee": 1000,
      "enabled": true
    },
    "metadata": {
      "description": "Updated fee configuration for Q4 2025",
      "notes": "Reduced onramp fees, increased offramp fees",
      "lastUpdatedBy": "admin@yourfintech.com"
    }
  }'

Response

string

Your fintech account identifier.

string

Confirmation of the operation performed. Typically "updated".

object

The full fee configuration as it now stands after the update.

object

An illustrative fee calculation based on a typical transaction amount, useful for sanity-checking your configuration.

{
  "status": "Success",
  "response_code": "00",
  "message": "Fee configuration updated successfully",
  "data": {
    "fintechId": "your_fintech_id",
    "operation": "updated",
    "feeConfiguration": {
      "onrampFee": { "percentageFee": 1.5, "capFee": 500, "enabled": true },
      "offrampFee": { "percentageFee": 2.0, "capFee": 1000, "enabled": true }
    },
    "exampleCalculation": {
      "onramp": { "amount": 10000, "fee": 150, "capped": false },
      "offramp": { "amount": 10000, "fee": 200, "capped": false }
    }
  }
}

GET /getfees

Retrieve your current fee configuration including any active onramp and offramp settings, configuration timestamps, and a schema version indicator.

Request

curl --request GET \
  --url "{{BASE_URL}}/getfees" \
  --header "x-api-key: YOUR_API_KEY"

Response

string

Your fintech account identifier.

boolean

true if a fee configuration has been set. false if you are using platform defaults.

object

The full active fee configuration object including onramp and offramp settings and any attached metadata.

string

ISO 8601 timestamp when your fee configuration was first created.

string

ISO 8601 timestamp when your fee configuration was last modified.

string

Schema version of the fee configuration object.

{
  "status": "Success",
  "response_code": "00",
  "message": "Fee configuration retrieved successfully",
  "data": {
    "fintechId": "your_fintech_id",
    "hasConfiguration": true,
    "feeConfiguration": {
      "onrampFee": {
        "percentageFee": 1.5,
        "capFee": 500,
        "enabled": true
      },
      "metadata": {
        "description": "Onramp fee configuration",
        "lastUpdatedBy": "your_fintech_id"
      }
    },
    "timestamps": {
      "createdAt": "2025-09-10T11:02:11.539Z",
      "updatedAt": "2026-04-29T05:47:38.653Z"
    },
    "version": "1.0.0"
  }
}

POST /fees/strails/preview

Calculate the Strails platform fee that will be applied to a transaction before you confirm it. This is separate from the fintech-configured fee returned by /getfees.

Use this endpoint to show users a transparent fee breakdown before they confirm a transaction. The Strails platform fee is applied on top of any fintech fee you have configured.

Body parameters

number

required

Transaction amount in the smallest currency unit (kobo) to calculate the fee for.

string

required

Direction of the transaction. Accepted values: "onramp" or "offramp".

Request

curl --request POST \
  --url "{{BASE_URL}}/fees/strails/preview" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 150000,
    "transactionType": "offramp"
  }'

Response

number

The input amount you provided.

string

The transaction type ("onramp" or "offramp") you provided.

string

Your authenticated fintech ID.

number

The percentage rate applied to calculate this fee.

number

The fee derived from the percentage calculation before any cap is applied.

number

Any flat fixed-fee component added on top of the percentage fee.

number

The total fee that will be charged, after applying any cap.

boolean

true if the calculated fee exceeded the cap and was reduced.

number

The cap value that was enforced. null if no cap was applied.

object

The amount tier that matched the input and determined the fee rate.

boolean

true if a fintech-specific fee override was applied instead of the default platform rate.

{
  "status": "Success",
  "response_code": "00",
  "message": "Strails fee calculated",
  "data": {
    "input": {
      "amount": 150000,
      "transactionType": "offramp",
      "fintechId": "fintech-123"
    },
    "result": {
      "amount": 150000,
      "feePercentage": 0.4,
      "calculatedFee": 600,
      "fixedFee": 0,
      "finalFee": 600,
      "wasCapped": false,
      "appliedCap": null,
      "tierUsed": {
        "minAmount": 100000,
        "maxAmount": 500000
      },
      "transactionType": "offramp",
      "usedFintechOverride": false
    }
  }
}

POST /verifywithdrawal

Check the current status of a fee withdrawal by its ID. Use this to confirm whether a pending withdrawal has been processed or to retrieve the reason for a failure.

Body parameters

string

required

The withdrawalId returned when you submitted the withdrawal via /feewithdrawal.

Request

curl --request POST \
  --url "{{BASE_URL}}/verifywithdrawal" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "transactionReference": "FTW_your_fintech_id_1725444600000"
  }'

Response

string

The withdrawal identifier you queried.

string

Current status of the withdrawal: pending, completed, or failed.

string

ISO 8601 timestamp when the withdrawal settled. null if still pending.

string

Human-readable explanation if the withdrawal failed. null on success.

{
  "status": "Success",
  "response_code": "00",
  "message": "Withdrawal status retrieved",
  "data": {
    "withdrawalId": "FTW_your_fintech_id_1725444600000",
    "status": "completed",
    "processedAt": "2025-09-04T12:15:00.000Z",
    "failureReason": null
  }
}

Overview

Core APIs

FX & Trading

Configuration

Fee Management API: Configure, Track & Withdraw Fees

Endpoints overview

GET /getwithdrawalhistory

Query parameters

Request

Response

POST /feewithdrawal

Body parameters

Request

Response

Error responses

GET /getaccumulatedfees

Request

Response

PUT /managefees

Body parameters

Request

Response

GET /getfees

Request

Response

POST /fees/strails/preview

Body parameters

Request

Response

POST /verifywithdrawal

Body parameters

Request

Response

​Endpoints overview

​GET /getwithdrawalhistory

​Query parameters

​Request

​Response

​POST /feewithdrawal

​Body parameters

​Request

​Response

​Error responses

​GET /getaccumulatedfees

​Request

​Response

​PUT /managefees

​Body parameters

​Request

​Response

​GET /getfees

​Request

​Response

​POST /fees/strails/preview

​Body parameters

​Request

​Response

​POST /verifywithdrawal

​Body parameters

​Request

​Response

Endpoints overview

GET /getwithdrawalhistory

Query parameters

Request

Response

POST /feewithdrawal

Body parameters

Request

Response

Error responses

GET /getaccumulatedfees

Request

Response

PUT /managefees

Body parameters

Request

Response

GET /getfees

Request

Response

POST /fees/strails/preview

Body parameters

Request

Response

POST /verifywithdrawal

Body parameters

Request

Response