Developer Reference

API Documentation

Integrate PaySense into your platform. Analyze merchant statements, generate branded reports, and calculate savings programmatically.

Getting Started#

The PaySense API lets you embed merchant statement analysis directly into your platform. Upload a PDF statement, retrieve extracted fees, generate branded reports, and calculate savings — all via simple REST endpoints.

API access is available on the Enterprise plan. Contact us to get started.

Base URL

https://paysense.up.railway.app/api/v1

Authentication#

Authenticate every request by including your API key in the x-api-key header.

curl -H "x-api-key: ps_live_your_key_here" \
  https://paysense.up.railway.app/api/v1/credits

API keys are managed in your organization settings under Admin → API Keys.

Keep your API key secret. Never expose it in client-side code, public repositories, or browser requests.

Endpoints#

POST/api/v1/analyze#

Upload a merchant statement PDF for analysis. The statement is processed asynchronously — poll the Get Analysis Results endpoint for completion.

Request body multipart/form-data

ParameterTypeRequiredDescription
filefileRequiredMerchant statement PDF
industrystringOptionalIndustry hint for improved accuracy (e.g. "restaurant", "retail")

Example request

curl -X POST https://paysense.up.railway.app/api/v1/analyze \
  -H "x-api-key: ps_live_your_key_here" \
  -F "file=@statement.pdf" \
  -F "industry=restaurant"

Example response

{
  "statement_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

GET/api/v1/analysis/{statement_id}#

Retrieve analysis results for a processed statement. Poll this endpoint until status is "completed".

Example request

curl https://paysense.up.railway.app/api/v1/analysis/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: ps_live_your_key_here"

Example response

{
  "status": "completed",
  "total_volume": 142580.00,
  "total_fees": 4219.37,
  "effective_rate": 2.96,
  "fee_breakdown": [
    {
      "category": "interchange",
      "label": "Visa CPS Retail",
      "amount": 1842.15,
      "rate": 1.65
    },
    {
      "category": "scheme",
      "label": "Visa Assessment",
      "amount": 198.61,
      "rate": 0.14
    },
    {
      "category": "psp_markup",
      "label": "Processing Fee",
      "amount": 2178.61,
      "rate": 1.53
    }
  ],
  "brand_summary": {
    "visa": { "volume": 89200, "fees": 2640.12 },
    "mastercard": { "volume": 38400, "fees": 1102.50 },
    "amex": { "volume": 14980, "fees": 476.75 }
  }
}

GET/api/v1/analysis/{statement_id}/report#

Download a branded PDF report for the analysis. Returns a PDF file directly.

Query parameters

ParameterTypeRequiredDescription
templatestringOptionalReport template: detailed_analysis (default), one_page_summary, pricing_comparison, savings_snapshot

Example request

curl https://paysense.up.railway.app/api/v1/analysis/a1b2c3d4-.../report?template=detailed_analysis \
  -H "x-api-key: ps_live_your_key_here" \
  -o report.pdf

GET/api/v1/credits#

Check your organization's remaining analysis credits and plan details.

Example request

curl https://paysense.up.railway.app/api/v1/credits \
  -H "x-api-key: ps_live_your_key_here"

Example response

{
  "credits_remaining": 47,
  "plan_tier": "enterprise",
  "credits_monthly_allowance": 200
}

GET/api/v1/templates#

List available report templates for your organization.

Example request

curl https://paysense.up.railway.app/api/v1/templates \
  -H "x-api-key: ps_live_your_key_here"

Example response

[
  {
    "id": "detailed_analysis",
    "name": "Detailed Analysis",
    "description": "Comprehensive fee breakdown with interchange verification"
  },
  {
    "id": "one_page_summary",
    "name": "One Page Summary",
    "description": "High-level overview with key metrics and savings"
  },
  {
    "id": "pricing_comparison",
    "name": "Pricing Comparison",
    "description": "Side-by-side current vs proposed pricing"
  },
  {
    "id": "savings_snapshot",
    "name": "Savings Snapshot",
    "description": "Quick savings estimate for prospect conversations"
  }
]

POST/api/v1/savings#

Calculate savings for an analyzed statement using custom pricing overrides.

Request body application/json

ParameterTypeRequiredDescription
statement_idstringRequiredID of the analyzed statement
pricing_overridesobjectOptionalCustom pricing: low_tier (%), high_tier (%), per_txn_fee ($)

Example request

curl -X POST https://paysense.up.railway.app/api/v1/savings \
  -H "x-api-key: ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pricing_overrides": {
      "low_tier": 0.99,
      "high_tier": 3.95,
      "per_txn_fee": 0.08
    }
  }'

Example response

{
  "current_cost": 4219.37,
  "proposed_cost": 3102.84,
  "monthly_savings": 1116.53,
  "annual_savings": 13398.36
}

GET/api/v1/compliance/states#

Get surcharge and dual-pricing compliance rules by state. Useful for validating pricing strategies.

Example request

curl https://paysense.up.railway.app/api/v1/compliance/states \
  -H "x-api-key: ps_live_your_key_here"

Example response

[
  {
    "code": "CA",
    "name": "California",
    "surcharge_allowed": true,
    "surcharge_cap": 4.0
  },
  {
    "code": "CT",
    "name": "Connecticut",
    "surcharge_allowed": false,
    "surcharge_cap": null
  },
  {
    "code": "TX",
    "name": "Texas",
    "surcharge_allowed": true,
    "surcharge_cap": 4.0
  }
]

Rate Limits#

The API enforces a limit of 60 requests per minute per API key. When exceeded, you will receive a 429 Too Many Requests response.

Rate limit headers

HeaderDescription
X-RateLimit-LimitMaximum requests per window (60)
X-RateLimit-RemainingRequests remaining in the current window
Retry-AfterSeconds until the rate limit resets (only on 429)

Errors#

All errors return a consistent JSON body with a detail field describing the issue.

{
  "detail": "Invalid or missing API key"
}

Status codes

CodeMeaning
401Invalid or missing API key
402Insufficient credits
404Resource not found
422Invalid request body
429Rate limit exceeded
500Server error

SDKs & Libraries#

Coming Soon

Official SDKs for Python, Node.js, and Go are in development. In the meantime, use the REST API directly with any HTTP client.

Ready to integrate?

Get an API key and start analyzing merchant statements in minutes. Enterprise plan includes dedicated support.

Get StartedContact Us