Compute fees for a transaction

POST

/fee-lookups

Resolves and returns the applicable processing fee for a given transaction context. The service scores all configured fee rules against the provided currency, type, amount, and optional scoping fields (entity, account, system label, country, provider), then selects the most specific matching rule. If a card payment instrument is supplied, the card's BIN is used to resolve the issuer country, overriding any explicitly passed country value. The entity is always derived from the authenticated caller — it does not need to be supplied in the request body.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Fee lookup succeeded. Returns the original transaction context alongside the computed total fee and the individual charge line items that make up that total.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Minimal — currency, type, and amount onlyCard transaction with BIN-based country resolutionFully scoped — all optional fields providedBank transfer with bank account instrument

curl --location '/fee-lookups' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "currency": "NGN",
    "type": "card",
    "amount": 50000
}'

Response Example

200 - Response with a percentage charge and a flat cap

{
    "message": "Fee lookup successful",
    "status": "success",
    "data": {
        "amount": 50000,
        "currency": "NGN",
        "type": "card",
        "total_fees": 750,
        "fee_bearer": "payer",
        "charges": [
            {
                "type": "percentage",
                "value": 1.5
            },
            {
                "type": "flat",
                "value": 0
            }
        ]
    }
}

Modified at 2026-08-06 16:06:01

Create a card vault session

Look up the status of an intent action