Quick Start

Calculate scheme fees, interchange, and fixed fees for any payment transaction through a single API call.

Prerequisites

• An active entity account on dashboard.recivr.com
• A JWT token (generated in entity account settings)

Step 1: Get Your API Token

1. Login to dashboard.recivr.com
2. Select your entity → Account Settings → API Tokens
3. Click Generate New Token and copy it — you won't see it again

Step 2: Your First API Call

Send a transaction with the 7 required fields + txn_metadata:

cURL

curl -X POST "https://api.recivr.com/v1/calculate" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "test-001",
    "txn_amount": "25.00",
    "txn_currency": "EUR",
    "merchant_id": "merchant-123",
    "merchant_country": "DE",
    "card_range": "53635423",
    "mcc": "5411",
    "txn_metadata": {
      "transaction_type": "PURCHASE",
      "entry_mode": "ECOM",
      "transaction_status": "NEW"
    }
  }'

JavaScript

const response = await fetch('https://api.recivr.com/v1/calculate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    txn_id: 'test-001',
    txn_amount: '25.00',
    txn_currency: 'EUR',
    merchant_id: 'merchant-123',
    merchant_country: 'DE',
    card_range: '53635423',
    mcc: '5411',
    txn_metadata: {
      transaction_type: 'PURCHASE',
      entry_mode: 'ECOM',
      transaction_status: 'NEW'
    }
  })
});

const result = await response.json();
console.log('Total fees:', result.total_fees_by_currency);
console.log('Scheme:', result.scheme);
console.log('Region:', result.txn_region);

Python

import requests

response = requests.post(
    "https://api.recivr.com/v1/calculate",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "txn_id": "test-001",
        "txn_amount": "25.00",
        "txn_currency": "EUR",
        "merchant_id": "merchant-123",
        "merchant_country": "DE",
        "card_range": "53635423",
        "mcc": "5411",
        "txn_metadata": {
            "transaction_type": "PURCHASE",
            "entry_mode": "ECOM",
            "transaction_status": "NEW"
        }
    }
)

result = response.json()
print(f"Total fees: {result['total_fees_by_currency']}")
print(f"Scheme: {result['scheme']}")
print(f"Region: {result['txn_region']}")

Expected Response

{
  "txn_id": "test-001",
  "txn_amount": "25.00",
  "txn_currency": "EUR",
  "scheme": "mastercard",
  "txn_region": "INTRA_EEA",

  "scheme_fees": {
    "total_by_currency": { "EUR": "0.025000" }
  },
  "interchange": {
    "ird_code": "IRF001",
    "rate_percent": "0.20",
    "flat_fee": "0.00",
    "fee_amount": "0.040000",
    "currency": "EUR"
  },
  "fixed_fees": {
    "total_by_currency": { "EUR": "0.005000" }
  },
  "total_fees_by_currency": { "EUR": "0.070000" },

  "included": ["scheme", "interchange", "fixed"]
}

Step 3: Calculation Modes

Control what gets calculated with options.mode:

cURL

# Scheme fees only (fastest)
curl -X POST "https://api.recivr.com/v1/calculate" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "test-002",
    "txn_amount": "50.00",
    "txn_currency": "EUR",
    "merchant_id": "merchant-123",
    "merchant_country": "DE",
    "card_range": "53635423",
    "mcc": "5411",
    "options": { "mode": "scheme" },
    "txn_metadata": {
      "transaction_type": "PURCHASE",
      "entry_mode": "ECOM",
      "transaction_status": "AUTHORIZED"
    }
  }'

JavaScript

const response = await fetch('https://api.recivr.com/v1/calculate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    txn_id: 'test-002',
    txn_amount: '50.00',
    txn_currency: 'EUR',
    merchant_id: 'merchant-123',
    merchant_country: 'DE',
    card_range: '53635423',
    mcc: '5411',
    options: { mode: 'scheme' },
    txn_metadata: {
      transaction_type: 'PURCHASE',
      entry_mode: 'ECOM',
      transaction_status: 'AUTHORIZED'
    }
  })
});

Python

response = requests.post(
    "https://api.recivr.com/v1/calculate",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN", "Content-Type": "application/json"},
    json={
        "txn_id": "test-002",
        "txn_amount": "50.00",
        "txn_currency": "EUR",
        "merchant_id": "merchant-123",
        "merchant_country": "DE",
        "card_range": "53635423",
        "mcc": "5411",
        "options": {"mode": "scheme"},
        "txn_metadata": {
            "transaction_type": "PURCHASE",
            "entry_mode": "ECOM"
        }
    }
)

Mode	What's calculated	Typical response time
"all" (default)	Scheme + interchange + fixed fees	50–80ms
"scheme"	Scheme + fixed fees only	40–60ms
"interchange"	Interchange only	30–50ms

Step 4: Add a Breakdown

Set breakdown: true to get per-fee line items:

{
  "options": { "mode": "all", "breakdown": true }
}

This adds a breakdown array inside scheme_fees and fixed_fees with individual fee IDs, descriptions, and amounts.

Required vs Optional Fields

Field	Required	Notes
txn_id	✅	Unique transaction ID
txn_amount	✅	Amount as string (e.g. "100.00")
txn_currency	✅	ISO 4217 (e.g. "EUR")
merchant_id	✅	Merchant identifier
merchant_country	✅	ISO 3166-1 alpha-2 (e.g. "GB")
card_range	✅	Card BIN (6-8 digits)
mcc	✅	Merchant Category Code (4 digits)
txn_metadata.transaction_type	✅	PURCHASE, REFUND, REVERSAL, etc.
txn_metadata.entry_mode	✅	ECOM, CHIP, CONTACTLESS, etc.
txn_metadata.transaction_status	✅	AUTHORIZED, DECLINED, REVERSED, etc.
txn_timestamp	—	Auto-generated if omitted
arn	—	Acquirer Reference Number
card_details	—	Auto-enriched from BIN lookup
txn_metadata.service_indicators	—	e.g. ["3ds_v2"]
options	—	Defaults to mode: "all", breakdown: false

For the full field reference including Tier 3 fields, see API Reference.

Case-Insensitive Validation

All enum fields accept both uppercase and lowercase:

• "purchase" or "PURCHASE" → both work
• "ecom" or "ECOM" → both work
• Values are auto-normalized

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Invalid or expired JWT	Generate a new token in dashboard
400 Bad Request	Missing required field or invalid value	Check field validation in Transaction Metadata
404 Not Found	Wrong endpoint	Use /v1/calculate

Next Steps

• API Reference — Complete field reference, response format, rate limits
• Transaction Metadata — All metadata fields, Tier 3 integration
• Card Details — Override BIN-resolved card data
• Transaction Status — Full list of status values