API Reference

Quick Reference

• Base URL: https://api.recivr.com/v1
• Authentication: JWT tokens in Authorization header
• Rate Limits: 1000 requests/minute, 100 requests/second burst
• Response Format: JSON
• Typical Response Time: 150-700ms

Key Features

• Unified /calculate endpoint — scheme fees, interchange, fixed fees, or all in one call
• Configurable calculation mode via options.mode
• Optional per-fee line-item breakdown via options.breakdown
• Automatic BIN lookup with optional card_details override
• Multi-currency totals with automatic EUR conversion
• Entity and FX rate overrides
• ISO 8583 passthrough support
• Transaction history retrieval

Base URL

https://api.recivr.com/v1

Authentication

All endpoints require authentication via JWT token in the Authorization header. JWT tokens are generated for each entity and can be created in the entity account settings at dashboard.recivr.com.

Authorization: Bearer <your-jwt-token>

Endpoints

1. Calculate Fees (Unified)

Endpoint: POST /calculate

Unified fee calculation endpoint. Use options.mode to control which fee components are calculated: scheme fees, interchange, or both. The response always follows the same shape — sections that weren't requested are null.

Full Request Body:

{
  "txn_id": "TXN-001",
  "txn_amount": "100.00",
  "txn_currency": "USD",
  "txn_timestamp": "2024-03-21T12:00:00",
  "merchant_id": "MERCHANT_GB_001",
  "merchant_country": "GB",
  "card_range": "53635423",
  "arn": "12345678901234567890123",
  "mcc": "5411",

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

  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "ECOM",
    "transaction_status": "NEW",
    "service_indicators": ["3ds_v2"],
    "authentication_method": "3ds",
    "terminal_id": "POS-001-GB",
    "message_type": null,
    "response_code": null,
    "eci": null,
    "cof_type": null,
    "cof_initiator": null,
    "wallet_type": null
  },

  "card_details": {
    "scheme": "MASTERCARD",
    "bin": "536354",
    "issuer_country": "US",
    "currency": "USD",
    "product_category": "CREDIT",
    "product": "MASTERCARD_DEBIT"
  },

  "iso_passthrough": null
}

Request Fields

Field	Type	Required	Description
txn_id	string	✅	Unique transaction identifier (3-100 chars)
txn_amount	string	✅	Transaction amount as decimal string (e.g. "100.00")
txn_currency	string	✅	ISO 4217 currency code (e.g. "EUR", "USD")
merchant_id	string	✅	Merchant identifier (3-50 chars)
merchant_country	string	✅	Merchant country — ISO 3166-1 alpha-2 (e.g. "GB")
card_range	string	✅	Card BIN — 6 to 8 digits
mcc	string	✅	Merchant Category Code — exactly 4 digits (e.g. "5411")
txn_timestamp	string	❌	ISO 8601 timestamp. Auto-generated if omitted
arn	string	❌	Acquirer Reference Number
options	object	❌	Calculation options (see below)
txn_metadata	object	✅	Must include transaction_type, entry_mode, transaction_status. See Transaction Metadata
card_details	object	❌	Card details override. See Card Details
fx_rate	string	❌	FX rate for EUR conversion. Auto-fetched if omitted
entity_id	string	❌	Override entity_id from JWT
entity_country	string	❌	Override entity country from JWT
iso_passthrough	object	❌	Raw ISO 8583 data elements (e.g. de_22, de_55)

Options Object

Field	Type	Default	Description
mode	string	"all"	"scheme", "interchange", or "all"
breakdown	boolean	false	Include per-fee line items

Response

{
  "txn_id": "TXN-001",
  "arn": "12345678901234567890123",
  "txn_amount": "100.00",
  "txn_currency": "USD",
  "scheme": "mastercard",
  "txn_region": "INTER_REGIONAL",

  "scheme_fees": {
    "total_by_currency": {
      "EUR": "0.043700",
      "USD": "0.330000"
    }
  },

  "interchange": {
    "ird_code": "IRF001",
    "rate_percent": "0.20",
    "flat_fee": "0.00",
    "fee_amount": "0.200000",
    "currency": "EUR",
    "region": "INTER_REGIONAL",
    "card_type": "CONSUMER",
    "product_name": "Debit Mastercard Consumer"
  },

  "fixed_fees": {
    "total_by_currency": { "EUR": "0.010000" }
  },

  "total_fees_by_currency": {
    "EUR": "0.097400",
    "USD": "0.330000"
  },

  "total_converted": {
    "amount": "0.457910",
    "currency": "EUR",
    "exchange_rate": "1.000000"
  },

  "card_details": {
    "bin": "536354",
    "scheme": "mastercard",
    "type": "debit",
    "product_category": "Debit",
    "issuer_name": "Sample Bank",
    "issuer_country": "US",
    "product": "MASTERCARD_DEBIT"
  },

  "regions": {
    "region_scope": "INTER_REGIONAL",
    "geographic_region": "europe",
    "issuer_country": "US",
    "acquirer_country": "GB",
    "merchant_country": "GB"
  },

  "transaction_characteristics": {
    "entry_mode": "ecom",
    "channel": "ecom",
    "transaction_type": "purchase",
    "category": "consumer",
    "card_not_present": true
  },

  "entity_id": "entity-abc",
  "included": ["scheme", "interchange", "fixed"]
}

Response Fields

Field	Type	Description
txn_id	string	Echo of the request transaction ID
arn	string | null	Acquirer Reference Number
txn_amount	string	Echo of the request amount
txn_currency	string	Echo of the request currency
scheme	string | null	Detected card scheme ("visa", "mastercard")
txn_region	string | null	Region scope ("INTRA_EEA", "INTER_REGIONAL")
scheme_fees	object | null	Scheme fee totals. Includes breakdown when requested
interchange	object | null	Interchange fee details — IRD code, rate, flat fee, amount
fixed_fees	object | null	Fixed/recurring fees allocated per transaction
total_fees_by_currency	object | null	Sum of all fee types, keyed by currency
total_converted	object | null	All fees converted to single currency with exchange rate
card_details	object | null	Resolved card details (from BIN lookup or override)
regions	object | null	Region classification used for fee calculation
transaction_characteristics	object | null	Derived transaction characteristics
entity_id	string | null	Entity ID used for calculation
included	array	Which components were calculated

2. Get Transaction History

Endpoint: GET /transactions/{org_id}

Retrieve recent transaction history for an organization.

Query Parameters:

• entity_id (optional): Filter by specific entity
• hours (optional, default: 24): Number of hours to look back (max 24)
• limit (optional, default: 100): Maximum number of transactions to return

Response:

{
  "transactions": [
    {
      "txn_id": "unique-transaction-id",
      "txn_amount": "20.00",
      "txn_currency": "EUR",
      "created_at": "2024-03-21T12:00:00Z",
      "status": "COMPLETED",
      "fees_calculated": true
    }
  ],
  "count": 1,
  "period_hours": 24,
  "org_id": "org-123",
  "entity_id": "entity-123"
}

Error Responses

400 Bad Request

{ "detail": "Invalid transaction data: Transaction amount must be positive" }

401 Unauthorized

{ "detail": "Invalid or expired token" }

403 Forbidden

{ "detail": "Not authorized to access this organization's data" }

500 Internal Server Error

{ "detail": "Error calculating fees: Database connection failed" }

Rate Limits

• Standard: 1000 requests per minute per organization
• Burst: Up to 100 requests per second
• Daily: 100,000 requests per day per organization

Response Times

• Scheme Fees only (mode: "scheme"): 40–60ms
• Interchange only (mode: "interchange"): 30–50ms
• All fees (mode: "all"): 50–80ms
• Transaction History: 30–50ms

Best Practices

1. Use mode: "all" (default) when you need the complete fee picture
2. Always include mcc — required and directly affects interchange rates
3. Include txn_metadata with accurate transaction_type and entry_mode
4. Use options.breakdown: true only when you need per-fee line items
5. Provide card_details when you have more accurate card information than BIN lookup
6. Handle errors gracefully and implement retry logic for transient 500s
7. Set transaction_status for accurate fee tier determination
8. For Tier 3 integrations: pass message_type, response_code, eci, cof_type, cof_initiator, wallet_type