# Get usage Source: https://docs.swippee.com/api-reference/account/get-usage /openapi.json get /v1/usage Check your quota and usage for the current month. # Get a bank profile Source: https://docs.swippee.com/api-reference/banks/get-a-bank-profile /openapi.json get /v1/banks/{code} Full profile for one bank — SWIFT code, branch count, contact info, NRB paid-up capital, head office, and current Nepal market interest rates. # List banks Source: https://docs.swippee.com/api-reference/banks/list-banks /openapi.json get /v1/banks List all banks and wallets Swippee knows about, with live NRB BFI data. READ_ONLY scope, no quota consumed. # Consent grant + access audit trail Source: https://docs.swippee.com/api-reference/connect/consent-grant-+-access-audit-trail /openapi.json get /v1/grants/{id} One consent grant plus its full access audit trail (every read of the granted data: timestamp, scope, IP, user-agent). The bank/NRB-presentable consent record. Read-only, org-scoped; no consumer PII or tokens. # Create a Connect request Source: https://docs.swippee.com/api-reference/connect/create-a-connect-request /openapi.json post /v1/connect/request Your backend starts a hosted consent flow. Returns a request_token and connect_url to open in the browser. # Exchange a public token Source: https://docs.swippee.com/api-reference/connect/exchange-a-public-token /openapi.json post /v1/connect/exchange Exchange the public_token from a completed Connect flow for an access_token and grant_id. # List consent grants (audit) Source: https://docs.swippee.com/api-reference/connect/list-consent-grants-audit /openapi.json get /v1/grants List the consent grants this org holds — the consent + access trail for compliance / NRB auditability. Read-only, org-scoped. Returns consent metadata + access counts only; no consumer PII or tokens. Reading the granted data is the separate GET /v1/grants/{id}/data. # Read granted data Source: https://docs.swippee.com/api-reference/connect/read-granted-data /openapi.json get /v1/grants/{id}/data Read only the scopes the consumer granted. The access token goes in the X-Swippee-Access-Token header, never the URL. Optionally pass `?include=` to fetch only a subset of the granted scopes (data minimization) — the response is granted ∩ requested and can never exceed what was granted. # Create a consent Source: https://docs.swippee.com/api-reference/consents/create-a-consent /openapi.json post /v1/consents Let the statement owner share a parsed report with a third party via a scoped, expiring token — without handing over an API key. # List consents Source: https://docs.swippee.com/api-reference/consents/list-consents /openapi.json get /v1/consents # Redeem a consent Source: https://docs.swippee.com/api-reference/consents/redeem-a-consent /openapi.json get /v1/consents/{id}/data Grantee reads the shared data with the opaque token only — no API key required. # Revoke a consent Source: https://docs.swippee.com/api-reference/consents/revoke-a-consent /openapi.json post /v1/consents/{id}/revoke # Banking balance sheet — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-balance-sheet-—-latest /openapi.json get /v1/data/nrb/banking/balance-sheet/latest Consolidated statement of assets & liabilities for Nepal's whole banking system (commercial + development + finance) — every line item, latest month. Values in NPR millions. # Banking balance sheet — series Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-balance-sheet-—-series /openapi.json get /v1/data/nrb/banking/balance-sheet/series One balance-sheet line item over time. # Banking indicator series Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-indicator-series /openapi.json get /v1/data/nrb/banking/indicators/series One indicator over time. # Banking indicators Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-indicators /openapi.json get /v1/data/nrb/banking/indicators Flat indicator list for a month, filterable by BFI class. # Banking profit & loss — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-profit-&-loss-—-latest /openapi.json get /v1/data/nrb/banking/pnl/latest Consolidated profit & loss for Nepal's whole banking system — interest income/expense, net interest income, fees, operating profit, provisions, net profit. NPR millions. # Banking profit & loss — series Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-profit-&-loss-—-series /openapi.json get /v1/data/nrb/banking/pnl/series One P&L line item over time. # Banking sector credit — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-sector-credit-—-latest /openapi.json get /v1/data/nrb/banking/credit/latest Loans & advances of Nepal's whole banking system, broken down by economic sector and by product. NPR millions. # Banking sector credit — series Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-sector-credit-—-series /openapi.json get /v1/data/nrb/banking/credit/series One sector or product line over time. # Banking snapshot Source: https://docs.swippee.com/api-reference/data-—-nrb/banking-snapshot /openapi.json get /v1/data/nrb/banking/snapshot All C4 indicators for a month. # Central Bank Survey — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/central-bank-survey-—-latest /openapi.json get /v1/data/nrb/cbs/latest Nepal Rastra Bank's monthly balance sheet (foreign assets, claims on government / banks / private sector, reserve money) for the most recent month. From the IMF e-GDDS SDMX feed. # Central Bank Survey — series Source: https://docs.swippee.com/api-reference/data-—-nrb/central-bank-survey-—-series /openapi.json get /v1/data/nrb/cbs/series One Central Bank Survey indicator over time. # Consumer Price Index — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/consumer-price-index-—-latest /openapi.json get /v1/data/nrb/cpi/latest Nepal's monthly CPI — overall index, COICOP groups, core, and ecological-belt breakdowns (2014/15=100). # Consumer Price Index — series Source: https://docs.swippee.com/api-reference/data-—-nrb/consumer-price-index-—-series /openapi.json get /v1/data/nrb/cpi/series One CPI index over time. # Convert currency Source: https://docs.swippee.com/api-reference/data-—-nrb/convert-currency /openapi.json get /v1/data/nrb/forex/convert Convert an amount using the latest reference rate. # Depository Corporations Survey — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/depository-corporations-survey-—-latest /openapi.json get /v1/data/nrb/dcs/latest Nepal's consolidated monetary survey (broad money M1/M2, domestic credit, net foreign assets, money multipliers) for the most recent month. # Depository Corporations Survey — series Source: https://docs.swippee.com/api-reference/data-—-nrb/depository-corporations-survey-—-series /openapi.json get /v1/data/nrb/dcs/series One monetary-survey indicator over time. # Forex series Source: https://docs.swippee.com/api-reference/data-—-nrb/forex-series /openapi.json get /v1/data/nrb/forex/series Daily series for one currency. # Interest-rate series Source: https://docs.swippee.com/api-reference/data-—-nrb/interest-rate-series /openapi.json get /v1/data/nrb/interest-rates/series One rate over time (base-rate, spread-rate, wavg-deposit, wavg-credit…). # Latest forex rates Source: https://docs.swippee.com/api-reference/data-—-nrb/latest-forex-rates /openapi.json get /v1/data/nrb/forex/latest Latest buy/sell reference rates for all currencies. Counts against your Data API quota. # Latest interest rates Source: https://docs.swippee.com/api-reference/data-—-nrb/latest-interest-rates /openapi.json get /v1/data/nrb/interest-rates/latest All commercial-bank interest rates for the latest month. # Latest macro indicators Source: https://docs.swippee.com/api-reference/data-—-nrb/latest-macro-indicators /openapi.json get /v1/data/nrb/macro/latest Latest report's indicators, each with a source quote. # Latest payment indicators Source: https://docs.swippee.com/api-reference/data-—-nrb/latest-payment-indicators /openapi.json get /v1/data/nrb/payments/latest All channels (volume + value) for the latest month. # Licensed BFI directory Source: https://docs.swippee.com/api-reference/data-—-nrb/licensed-bfi-directory /openapi.json get /v1/data/nrb/bfis Licensed banks and financial institutions, filterable by class. # Macro series Source: https://docs.swippee.com/api-reference/data-—-nrb/macro-series /openapi.json get /v1/data/nrb/macro/series One indicator over time (inflation, remittance, reserves, bop…). # Merchandise Trade — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/merchandise-trade-—-latest /openapi.json get /v1/data/nrb/trade/latest Nepal's monthly merchandise trade — total exports (FOB), imports (CIF), and the SITC-section breakdown. # Merchandise Trade — series Source: https://docs.swippee.com/api-reference/data-—-nrb/merchandise-trade-—-series /openapi.json get /v1/data/nrb/trade/series One trade aggregate over time. # Official Reserve Assets — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/official-reserve-assets-—-latest /openapi.json get /v1/data/nrb/reserve/latest Nepal's monthly official reserve assets — total reserves, monetary gold (value + troy ounces), SDR holdings, IMF reserve position, foreign exchange. # Official Reserve Assets — series Source: https://docs.swippee.com/api-reference/data-—-nrb/official-reserve-assets-—-series /openapi.json get /v1/data/nrb/reserve/series One reserve-asset line over time. # Payments series Source: https://docs.swippee.com/api-reference/data-—-nrb/payments-series /openapi.json get /v1/data/nrb/payments/series One channel/metric over time. # Per-bank balance sheet — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-balance-sheet-—-latest /openapi.json get /v1/data/nrb/banks/balance-sheet/latest Statement of assets & liabilities for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions. # Per-bank balance sheet — series Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-balance-sheet-—-series /openapi.json get /v1/data/nrb/banks/balance-sheet/series One institution's balance-sheet line item over time. # Per-bank profit & loss — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-profit-&-loss-—-latest /openapi.json get /v1/data/nrb/banks/pnl/latest Profit & loss for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions. # Per-bank profit & loss — series Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-profit-&-loss-—-series /openapi.json get /v1/data/nrb/banks/pnl/series One institution's P&L line item over time. # Per-bank sector credit — latest Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-sector-credit-—-latest /openapi.json get /v1/data/nrb/banks/credit/latest Loans & advances by economic sector for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions. # Per-bank sector credit — series Source: https://docs.swippee.com/api-reference/data-—-nrb/per-bank-sector-credit-—-series /openapi.json get /v1/data/nrb/banks/credit/series One institution's sector line over time. # List lending decisions Source: https://docs.swippee.com/api-reference/decisions/list-lending-decisions /openapi.json get /v1/decisions List the decisions your organization has recorded. Filter with ?outcome=defaulted (etc.). # Record a lending decision Source: https://docs.swippee.com/api-reference/decisions/record-a-lending-decision /openapi.json post /v1/decisions Closed-loop feedback: record the decision you made on an applicant, keyed by your own client_reference_id. Re-POSTing the same reference updates it (upsert). # Report a loan outcome Source: https://docs.swippee.com/api-reference/decisions/report-a-loan-outcome /openapi.json post /v1/outcomes The second half of the feedback loop — report what actually happened to a loan you recorded a decision on (same client_reference_id). Over time this trains the score on real results. # Enrich transactions Source: https://docs.swippee.com/api-reference/enrichment/enrich-transactions /openapi.json post /v1/enrich Send raw transactions; get merchant, MCC, and spend category tags back. A transform endpoint — no report required. # Look up a terminal Source: https://docs.swippee.com/api-reference/merchants/look-up-a-terminal /openapi.json get /v1/merchants/{terminal} Resolve a single Fonepay terminal PAN to its merchant. # Resolve a merchant QR poster Source: https://docs.swippee.com/api-reference/merchants/resolve-a-merchant-qr-poster /openapi.json post /v1/merchants/qr Upload a Fonepay merchant QR poster (PDF or image) and get the merchant back — terminal, name, MCC, category, and city. We read the printed terminal and, for images, decode the QR. FULL scope; bills 1 unit per call. Max 10 MB. # Resolve merchants Source: https://docs.swippee.com/api-reference/merchants/resolve-merchants /openapi.json post /v1/merchants/resolve Turn raw Fonepay terminal PANs and merchant-name strings into clean merchant data — name, MCC, spend category, and city. FULL scope; bills 1 unit per call (batch up to 1000 lookups). # Parse a bank statement Source: https://docs.swippee.com/api-reference/parsing/parse-a-bank-statement /openapi.json post /v1/parse Upload a Nepali bank statement (PDF, Excel, JPEG, or PNG, max 20 MB). Returns a full `StatementReport` with statement metadata, signals, monthly summary, categories, and every categorized transaction. Bills 1 unit. # Asset Report Source: https://docs.swippee.com/api-reference/products/asset-report /openapi.json get /v1/reports/{id}/asset-report The full underwriting view — statement, signals, monthly summary, categories, and every transaction. # Auth (verified numbers) Source: https://docs.swippee.com/api-reference/products/auth-verified-numbers /openapi.json get /v1/reports/{id}/auth The account's verified numbers — holder, account number, and the institution's SWIFT/BIC (only Class-A commercial banks in Nepal hold one; `swift_note` explains any absence) — plus a `verification_status` reflecting how the data was obtained. # Balance Source: https://docs.swippee.com/api-reference/products/balance /openapi.json get /v1/reports/{id}/balance Opening/closing balances, average and minimum balance, and the balance trend. # Cash flow Source: https://docs.swippee.com/api-reference/products/cash-flow /openapi.json get /v1/reports/{id}/cashflow Lender-grade cash-flow attributes: total + windowed (30/60/90d) inflow/outflow, net cash flow, average monthly balances, NSF/overdraft count, and the longest gap between transactions. Windows are measured back from the latest transaction date. # Counterparties Source: https://docs.swippee.com/api-reference/products/counterparties /openapi.json get /v1/reports/{id}/counterparties Who the money moved to/from: inflow/outflow split by counterparty type (merchant / individual / institution / wallet / cash / self) plus the top named people and merchants. # Identity Source: https://docs.swippee.com/api-reference/products/identity /openapi.json get /v1/reports/{id}/identity Account holder, account number, bank, currency, and statement period — to confirm the uploader owns the account. # Income Source: https://docs.swippee.com/api-reference/products/income /openapi.json get /v1/reports/{id}/income Salary detection (amount, regularity, day-of-month), income_sources broken down by type (SALARY / REMITTANCE / INTEREST) with per-source totals + pay frequency, total_income, monthly credits, stability score, and the income transactions. # Liabilities Source: https://docs.swippee.com/api-reference/products/liabilities /openapi.json get /v1/reports/{id}/liabilities EMI/loan obligations bucketed by detected lender, monthly EMI total, EMI load %, and bounce count. # Name match Source: https://docs.swippee.com/api-reference/products/name-match /openapi.json post /v1/reports/{id}/identity/match Verify the statement belongs to your applicant: send the claimed name, get a 0–100 match_score + banded result (match / partial_match / no_match) against the statement's account holder. Order-, initial-, honorific- and transliteration-tolerant. Names only — not full KYC. # Recurring streams Source: https://docs.swippee.com/api-reference/products/recurring-streams /openapi.json get /v1/reports/{id}/recurring Recurring inflow + outflow streams (salary, rent, EMIs, subscriptions) with cadence, average amount, MATURE/EARLY_DETECTION status, whether the stream is still active, and a forecast next date. Built from real per-counterparty cadence. # Score Source: https://docs.swippee.com/api-reference/products/score /openapi.json get /v1/reports/{id}/score A single 0–1000 creditworthiness score derived from the statement signals. # Trust (two-axis score) Source: https://docs.swippee.com/api-reference/products/trust-two-axis-score /openapi.json get /v1/reports/{id}/trust A two-axis decision score: affordability (can they service the obligation) AND integrity (can the statement be trusted — tamper/forensics). Both 1–99, with integrity_basis, integrity_confidence, and an overall_band (ACCEPT | REVIEW | REJECT). Derived from data already on the report — not billed. # Underwriting Source: https://docs.swippee.com/api-reference/products/underwriting /openapi.json post /v1/reports/{id}/underwriting Full lender decision: FOIR, disposable income, max supportable EMI, risk flags, and an approve/review/decline verdict. Bills 1 unit per call. # Verify Source: https://docs.swippee.com/api-reference/products/verify /openapi.json get /v1/reports/{id}/verify Forgery/tamper detection — a verdict (authentic | review | suspicious), confidence, a derived risk_score (0–100) + risk_band + categorised risk_reasons, a risk_coverage flag (full when PDF forensics ran, else partial), and every check with pass/fail + severity. # Get a report Source: https://docs.swippee.com/api-reference/reports/get-a-report /openapi.json get /v1/reports/{id} Fetch a single completed report by its ID. # List reports Source: https://docs.swippee.com/api-reference/reports/list-reports /openapi.json get /v1/reports List your organization's recent reports. # List transactions Source: https://docs.swippee.com/api-reference/reports/list-transactions /openapi.json get /v1/reports/{id}/transactions The categorized transaction list for a report, with query filters. Filters combine with AND. # Create a sandbox report Source: https://docs.swippee.com/api-reference/sandbox/create-a-sandbox-report /openapi.json post /v1/sandbox/reports Create a deterministic, fully-synthetic `StatementReport` (or force a deterministic error). No file required. Report scenarios persist a `complete`, `test`-environment report, so every `/v1/reports/{id}/*` sub-endpoint works against the returned `report_id`. Requires a test key; never consumes quota. # Fire a sandbox webhook Source: https://docs.swippee.com/api-reference/sandbox/fire-a-sandbox-webhook /openapi.json post /v1/sandbox/reports/{id}/fire_webhook Trigger a webhook delivery for a sandbox report to your registered endpoints, on demand. Requires a test key; the report must belong to your organization. # List sandbox scenarios Source: https://docs.swippee.com/api-reference/sandbox/list-sandbox-scenarios /openapi.json get /v1/sandbox/scenarios List the synthetic report scenarios and forced-error scenarios available in the sandbox. Requires a test key (`sk_test_…`). # List issued statements Source: https://docs.swippee.com/api-reference/statements/list-issued-statements /openapi.json get /v1/statements List the verifiable statements your organization has issued. Each carries its tamper-evident content_hash (SHA-256 of the canonical statement) and a verify_url anyone can use to confirm authenticity. Scoped to your org. Filter with status=issued|revoked. # Authentication Source: https://docs.swippee.com/authentication How Swippee API keys, scopes, and bearer authentication work. All requests require a Bearer token. Create one in the [dashboard](https://swippee.com/dashboard). ``` Authorization: Bearer swippee_sk_live_xxxxxxxxxxxxxxxx ``` Keys are shown **exactly once** at creation. Swippee only stores a SHA-256 hash — a lost key can't be recovered, only revoked and replaced. ## Scopes | Scope | Can do | | ----------- | --------------------------------------------------------------- | | `READ_ONLY` | Fetch existing reports and read public datasets. No parsing. | | `FULL` | Everything — parse, enrich, resolve merchants, manage consents. | Issue read-only keys for backend services that only need to fetch reports they didn't create. ## Quotas * **Parse** calls draw from your monthly parse quota (per organization). * **Swippee Data** calls draw from a separate Data API quota (500 on Sandbox, 2,500 on Growth, 5,000 on Scale). * Reading product views on a report you already parsed is **free**. Check your current usage any time: ```bash theme={null} curl https://api.swippee.com/v1/usage \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` ## Errors Auth failures return a structured error with an HTTP status. See [Errors](/concepts/errors) for the full taxonomy. ```json theme={null} { "error": { "code": "invalid_api_key", "message": "Key does not exist." } } ``` # Errors Source: https://docs.swippee.com/concepts/errors Swippee's error envelope and the full error-code taxonomy. Every error returns the same flat JSON envelope. **Branch on `error_code`, not the HTTP status** — the status tells you the broad class, the code tells you exactly what happened. ```json theme={null} { "error_type": "RATE_LIMIT_ERROR", "error_code": "RATE_LIMIT_EXCEEDED", "error_message": "Rate limit exceeded (60 requests/minute on the free plan).", "display_message": "You're going a little fast — try again in a moment.", "request_id": "req_8f3c9b2e4a1d4f7c9e0b1a2c3d4e5f60", "documentation_url": "https://docs.swippee.com/concepts/errors#rate_limit_exceeded", "suggested_action": "Slow down or upgrade your plan." } ``` | Field | Notes | | ------------------- | ----------------------------------------------------------------------------- | | `error_type` | Coarse grouping you can switch on (e.g. `AUTHENTICATION_ERROR`). | | `error_code` | The specific, stable code. **This is what you branch on.** | | `error_message` | Developer-facing detail (may name plan limits, fields, etc.). | | `display_message` | Safe to show your end-user, or `null` when it isn't — never surface a `null`. | | `request_id` | Quote this when contacting support. | | `documentation_url` | Deep-link to this page for the code. | | `suggested_action` | What to do next. | ## Error codes | `error_code` | `error_type` | HTTP | Meaning | | -------------------------------------------------------------------- | --------------------- | ---- | -------------------------------------------------------------------------------------------------- | | `MISSING_API_KEY` | AUTHENTICATION\_ERROR | 401 | No `Authorization` header sent. | | `INVALID_API_KEY` | AUTHENTICATION\_ERROR | 401 | Key does not exist. | | `REVOKED_API_KEY` | AUTHENTICATION\_ERROR | 401 | Key was revoked. | | `INSUFFICIENT_SCOPE` | PERMISSION\_ERROR | 403 | Key lacks the required scope (or org suspended). | | `RATE_LIMIT_EXCEEDED` | RATE\_LIMIT\_ERROR | 429 | Per-org throughput cap hit. Honour `Retry-After`. | | `QUOTA_EXCEEDED` | RATE\_LIMIT\_ERROR | 429 | Monthly parse / data quota reached. | | `INVALID_REQUEST` | INVALID\_REQUEST | 400 | Request shape or parameters invalid. | | `INVALID_FORMAT` | INVALID\_REQUEST | 400 | Body malformed or not `multipart/form-data`. | | `MISSING_FILE` | INVALID\_REQUEST | 400 | Form field `file` is missing. | | `FILE_TOO_LARGE` | INVALID\_REQUEST | 413 | File exceeds the 20 MB limit. | | `INVALID_RANGE` | INVALID\_REQUEST | 400 | Requested date range is invalid. | | `IDEMPOTENCY_IN_PROGRESS` | INVALID\_REQUEST | 409 | Same `Idempotency-Key` still processing — retry shortly. See [Idempotency](/concepts/idempotency). | | `IDEMPOTENCY_KEY_REUSED` | INVALID\_REQUEST | 422 | `Idempotency-Key` reused with different params. Use a fresh key. | | `UNSUPPORTED_DOCUMENT` | DOCUMENT\_ERROR | 422 | File is not a transaction statement. | | `UNSUPPORTED_BANK` | DOCUMENT\_ERROR | 422 | No supported Nepali bank detected. | | `IMAGE_STATEMENT_UNSUPPORTED` | DOCUMENT\_ERROR | 422 | Photo/scan — upload the original PDF. | | `PASSWORD_REQUIRED` | DOCUMENT\_ERROR | 422 | File is password-protected. | | `PASSWORD_INCORRECT` | DOCUMENT\_ERROR | 422 | Supplied statement password was wrong. | | `PARSE_FAILED` | DOCUMENT\_ERROR | 422 | Bank detected but extraction failed. | | `TAMPER_DETECTED` | FORENSICS\_ERROR | 422 | Document shows signs of tampering. | | `IMAGE_NOT_TAMPER_VERIFIED` | FORENSICS\_ERROR | 422 | Images can't be tamper-verified — upload the PDF. | | `FORENSICS_FAILED` | FORENSICS\_ERROR | 500 | The forensics pass could not complete. | | `NOT_FOUND` | NOT\_FOUND | 404 | Resource not found on this organization. | | `NOT_READY` | CONSENT\_ERROR | 409 | Resource (report/consent) not ready yet. | | `INVALID_CONSENT` / `CONSENT_INACTIVE` | CONSENT\_ERROR | 403 | Consent missing or no longer active. | | `GRANT_PENDING` / `GRANT_DENIED` / `GRANT_REVOKED` / `GRANT_EXPIRED` | CONSENT\_ERROR | 403 | Vault access-grant state. | | `SOURCE_UNCONFIGURED` / `NO_DATA_YET` / `CURRENCY_NOT_PUBLISHED` | DATA\_ERROR | 404 | Data API: series/currency unavailable. | | `INTERNAL_ERROR` | API\_ERROR | 500 | Unexpected server error — retry with backoff. | # Idempotency Source: https://docs.swippee.com/concepts/idempotency Safely retry billable requests without creating duplicates or double-charging. Network blips, timeouts, and double-taps happen. To make retries safe, send an **`Idempotency-Key`** header on the billable, resource-creating `POST` endpoints. If the same key arrives again, Swippee replays the original response instead of doing the work twice — so a retry can't create a duplicate report or charge your quota twice. ```bash theme={null} curl -X POST https://api.swippee.com/v1/parse \ -H "Authorization: Bearer sk_live_..." \ -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \ -F "file=@statement.pdf" ``` Use any unique, hard-to-guess value (a UUID v4 is ideal). Generate it **once per logical operation** and reuse it across that operation's retries — not per HTTP attempt. ## Where it applies | Endpoint | Why | | ----------------------- | ---------------------------------------------------- | | `POST /v1/parse` | Each call creates a report and consumes parse quota. | | `POST /v1/verify/issue` | Each call mints a new verification token. | Other write endpoints (e.g. `POST /v1/decisions`) are already idempotent by a natural key, so a key is optional there. `GET` requests never need one. ## Behaviour * **First request** — processed normally; the response is cached against your key. * **Retry (same key, same params)** — the original response is replayed verbatim, with an `Idempotent-Replayed: true` header. No new report, no extra charge. * **Still in flight** — if a retry arrives while the first is still processing, you get `409 IDEMPOTENCY_IN_PROGRESS`. Wait a moment and retry the same key. * **Key reused with different params** — `422 IDEMPOTENCY_KEY_REUSED`. A given key is bound to its first request body; use a fresh key for a new request. * **Server error (5xx)** — the key is released so your retry can reprocess. Only deterministic responses (success and client errors) are cached. ## Scope & lifetime * Keys are scoped to **your organization** and **environment** (`live` vs `test` keys never collide). * Cached responses expire after **24 hours** — retries beyond that window are treated as new requests. * Keys must be **8–255 characters**. # Products Source: https://docs.swippee.com/concepts/products The focused views you can derive from a parsed report — Income, Identity, Balance, Liabilities, Score, Verify, Underwriting. Once a report is `complete`, each product is a focused `GET` on it. All take a Bearer key and return JSON shaped for that one product — call only what you need, **billed as one parse** regardless of how many you read. | Product | Endpoint | Returns | | -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Asset Report | `GET /v1/reports/:id/asset-report` | The full underwriting view — statement, signals, monthly summary, categories, and every transaction. | | Income | `GET /v1/reports/:id/income` | Salary detection (amount, regularity, day-of-month), `income_sources` broken down by type (SALARY / REMITTANCE / INTEREST) with per-source totals + pay frequency, `total_income`, monthly credits, stability score, and income transactions. | | Identity | `GET /v1/reports/:id/identity` | Account holder, account number, bank, currency, and statement period. | | Auth | `GET /v1/reports/:id/auth` | Verified numbers: account holder + number, institution SWIFT/BIC, and a `verification_status`. | | Name match | `POST /v1/reports/:id/identity/match` | Send the applicant's claimed name → 0–100 `match_score` + result (`match`/`partial_match`/`no_match`) vs the statement's account holder. Order/initial/honorific/transliteration-tolerant. | | Balance | `GET /v1/reports/:id/balance` | Opening/closing balances, average and minimum balance, and the balance trend. | | Cash Flow | `GET /v1/reports/:id/cashflow` | Total + 30/60/90-day inflow/outflow, net cash flow, average monthly balances, NSF/overdraft count, longest transaction gap. | | Recurring | `GET /v1/reports/:id/recurring` | Recurring inflow + outflow streams (salary, rent, EMIs, subscriptions) — cadence, average amount, MATURE/EARLY status, active flag, forecast next date. | | Counterparties | `GET /v1/reports/:id/counterparties` | Inflow/outflow split by counterparty type (merchant / individual / institution / wallet / cash) plus top named people and merchants. | | Liabilities | `GET /v1/reports/:id/liabilities` | EMI/loan obligations bucketed by detected lender, monthly EMI total, EMI load %, and bounce count. | | Score | `GET /v1/reports/:id/score` | A single 0–1000 creditworthiness score derived from the statement signals. | | Verify | `GET /v1/reports/:id/verify` | Forgery/tamper detection — a verdict (`authentic` \| `review` \| `suspicious`), confidence, a derived `risk_score` (0–100) + `risk_band` + categorised `risk_reasons`, a `risk_coverage` flag (`full`/`partial`), and every check with pass/fail + severity. | | Trust | `GET /v1/reports/:id/trust` | Two-axis decision score — affordability **and** integrity (both 1–99), with `integrity_basis`, `integrity_confidence`, and an `overall_band` (`ACCEPT` \| `REVIEW` \| `REJECT`). | | Underwriting | `POST /v1/reports/:id/underwriting` | Full lender decision: FOIR, disposable income, max supportable EMI, risk flags, approve/review/decline verdict. **Bills 1 unit per call.** | ```bash theme={null} # fetch just the income view of a completed report curl https://api.swippee.com/v1/reports/cl_abc123/income \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` `enrich` is a transform endpoint (`POST /v1/enrich`) — send raw transactions, get merchant / MCC / category tags back. `connect` is the hosted upload flow — see the [Connect guide](/guides/connect). ## Decisions & outcomes (closed-loop feedback) Tell Swippee what you decided and what actually happened, so the score learns from real lending results: ```bash theme={null} # 1. record your decision (keyed by your own reference) curl https://api.swippee.com/v1/decisions -H "Authorization: Bearer $SWIPPEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "client_reference_id": "loan-1001", "decision": "approved", "amount": 250000 }' # 2. later, report the outcome curl https://api.swippee.com/v1/outcomes -H "Authorization: Bearer $SWIPPEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "client_reference_id": "loan-1001", "outcome": "defaulted", "detail": "90+ DPD" }' ``` `decision` ∈ `approved` | `review` | `declined`; `outcome` ∈ `repaid` | `delinquent` | `defaulted` | `written_off`. `GET /v1/decisions?outcome=defaulted` lists what you've recorded. ## Issued statements `GET /v1/statements` lists the verifiable statements your organization has issued. Each carries a tamper-evident `content_hash` (SHA-256 of the canonical statement), a `status` (`issued` | `revoked`), and a `verify_url` anyone can use to confirm it's genuine. The single-statement detail and the upload-to-check flow are public at `/v1/verify/{token}`. # Reports & transactions Source: https://docs.swippee.com/concepts/reports The StatementReport object, the transaction shape, and how to filter transactions. A **report** is the result of parsing one statement. Everything else — products, consents, enrichment — is derived from it. ## The StatementReport ```json theme={null} { "report_id": "cl_abc123", "status": "complete", "statement": { "bank": "Nabil Bank", "bank_code": "NABIL", "currency": "NPR", "period": { "from": "2025-11-01", "to": "2026-04-30" }, "opening_balance": 5028.73, "closing_balance": 5062.93, "total_transactions": 114 }, "signals": { }, "monthly_summary": [ ], "categories": { }, "merchant_categories": { "groceries": { "count": 12, "total": 8420 } }, "transactions": [ ] } ``` ## The transaction object Transactions follow a standard, industry-familiar shape. | Field | Type | Description | | --------------------------- | -------------- | ---------------------------------------------------------------------------- | | `transaction_id` | string | Stable id within the report. | | `date` | string | ISO 8601 (`YYYY-MM-DD`). | | `name` | string | Raw narration as printed on the statement. | | `amount` | number | **Signed: positive = money out (debit), negative = money in (credit).** | | `iso_currency_code` | string | e.g. `NPR`. | | `balance` | number \| null | Running balance after the transaction. | | `merchant_name` | string \| null | Merchant parsed from the narration (or resolved from a Fonepay terminal). | | `payment_terminal_id` | string \| null | Fonepay terminal PAN, when the rail carries one. | | `mcc` | string \| null | ISO 18245 Merchant Category Code, when the merchant resolves. | | `personal_finance_category` | object | `{ primary, detailed, confidence_level }` — two-level category + confidence. | | `counterparties` | array | `[{ type, name, confidence_level }]` — who the money moved to/from. | | `payment_channel` | string \| null | Not classified for parsed statements (`null`). | | `pending` | boolean | Always `false` — statement lines are settled. | ## Filtering transactions `GET /v1/reports/:id/transactions` takes query filters so you don't always need the full set. Filters combine with **AND**. ```bash theme={null} # only dining spend, debits, in April curl "https://api.swippee.com/v1/reports/cl_abc123/transactions\ ?merchant_category=dining&direction=debit&since=2026-04-01&until=2026-04-30&limit=100" \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` Filters: `category`, `merchant_category`, `direction` (credit | debit), `since`, `until` (ISO dates), `limit` (default 500, max 1000). ## Provenance Every report is stamped with how its data was obtained, so you know how far to trust it: | `data_source` | Meaning | `tamper_verifiable` | | ------------------ | ------------------------------------ | ------------------------------------------ | | `PARSED_STATEMENT` | Parsed from the bank's own PDF/Excel | yes | | `OCR_IMAGE` | Read from a photo/scan | **no** — upload the original PDF to verify | ## Listing & fetching ```bash theme={null} # fetch one report curl https://api.swippee.com/v1/reports/cl_abc123 \ -H "Authorization: Bearer $SWIPPEE_API_KEY" # list recent reports curl 'https://api.swippee.com/v1/reports?limit=20&status=complete' \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` # Webhooks Source: https://docs.swippee.com/concepts/webhooks Receive parse results on your backend, with signed, retried delivery. When a report completes (sync or async), Swippee `POST`s the result to every active webhook endpoint on your organization. ## Signature Each delivery is signed so you can verify it came from Swippee: ``` X-Swippee-Signature: t=,v1= ``` `v1` is an HMAC-SHA256 of `.` using your webhook signing secret. Reject deliveries where the timestamp is too old or the signature doesn't match. ## Payload Every delivery shares one envelope. The event is split into a grouping (`event_type`) and a specific code (`event_code`); `event` is the canonical dotted name. Switch on `event_code`. ```json theme={null} { "event": "report.ready", "event_type": "REPORT", "event_code": "READY", "report_id": "rep_abc123", "environment": "live", "created_at": "2026-05-27T10:23:41Z", "result": { } } ``` | `event` | When | | --------------- | --------------------------------------------------------------------------- | | `report.ready` | A report finished parsing. `result` is the full `StatementReport`. | | `report.failed` | A report could not be produced. `error` is `{ error_code, error_message }`. | Webhooks are hints — always reconcile against `GET /v1/reports/{id}` as the source of truth, since deliveries can arrive out of order or be retried. ## Retries Failed deliveries retry with exponential backoff for up to **24 hours**. Return a `2xx` quickly and process asynchronously to avoid timeouts. # Connect — embed the consumer Vault Source: https://docs.swippee.com/guides/connect A hosted consent flow where the consumer approves which scopes you receive — your app never sees their statement or login. Swippee Connect is the hosted consent flow: the **consumer** signs into their Swippee Vault, approves which scopes you get, and you receive a `public_token`. Your app never sees their statement or login. ```bash theme={null} curl -X POST https://api.swippee.com/v1/connect/request \ -H "Authorization: Bearer swippee_sk_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "scopes": ["identity","income"], "redirect_uri": "https://yourapp.com/cb" }' # → { "request_token": "swln_…", "connect_url": "https://swippee.com/connect?token=swln_…" } ``` Script-tag drop-in (any site). The script is first-party — for extra safety you can pin it with `integrity` / `crossorigin`. ```html theme={null} ``` React drop-in (`npm install @swippee/connect-react`): ```jsx theme={null} import { SwippeeConnect } from "@swippee/connect-react"; fetch("/api/connect-request").then(r => r.json())} onHostedSuccess={({ publicToken }) => exchangeOnYourServer(publicToken)} /> ``` ```bash theme={null} curl -X POST https://api.swippee.com/v1/connect/exchange \ -H "Authorization: Bearer swippee_sk_live_xxx" \ -d '{ "public_token": "swln_…" }' # → { "access_token": "swac_…", "grant_id": "...", "scopes": [...] } # read only the granted views (token in a header, never the URL): curl https://api.swippee.com/v1/grants/GRANT_ID/data \ -H "Authorization: Bearer swippee_sk_live_xxx" \ -H "X-Swippee-Access-Token: swac_…" # → { "granted_scopes": [...], "scopes": [...], "data": { "identity": {...}, "income": {...} } } # data minimization: fetch only a subset you need this call with ?include= # (returned scopes = granted ∩ requested — never more than granted): curl 'https://api.swippee.com/v1/grants/GRANT_ID/data?include=income,verify' \ -H "Authorization: Bearer swippee_sk_live_xxx" \ -H "X-Swippee-Access-Token: swac_…" ``` The consumer manages and revokes every connection from their Vault; a revoke kills the access token immediately. ## Audit your consents For compliance — proving *which customer consents you obtained and how the data was used* — read your consent + access trail. Both endpoints are **read-only**, scoped to your organization, and return consent metadata only: **no consumer PII, no tokens**. (Reading the granted *data* is the separate `GET /v1/grants/:id/data` above, which additionally requires the access token.) ```bash theme={null} # List your consent grants (filter with ?status=approved|pending|revoked|expired|denied, ?limit=1..200) curl 'https://api.swippee.com/v1/grants?status=approved&limit=50' \ -H "Authorization: Bearer swippee_sk_live_xxx" # → { "grants": [ { # "grant_id": "...", "app_name": "Your app", "consumer_id": "...", # "scopes": ["income","verify"], "status": "approved", # "created_at": "...", "approved_at": "...", "expires_at": "...", # "revoked_at": null, "access_count": 3 # } ] } # One grant + its full access audit trail (every read of the granted data) curl https://api.swippee.com/v1/grants/GRANT_ID \ -H "Authorization: Bearer swippee_sk_live_xxx" # → { ...grant fields above..., "access_log": [ # { "accessed_at": "...", "scope": "all", "ip": "…", "user_agent": "…" } # ] } ``` `consumer_id` is an opaque identifier — never the consumer's email, phone, or name. The access log records each time *your* app read the granted data. # Consents — share a report safely Source: https://docs.swippee.com/guides/consents Let a statement owner share a parsed report with a third party via a scoped, expiring token — without handing over an API key. Let the statement owner share a parsed report with a third party (a lender, CA, or landlord) **without** handing over an API key. You grant a scoped, expiring *consent*; the grantee redeems an opaque token and sees only the views you allowed. Every read is audit-logged, and you can revoke at any time. ## Create a consent ```bash theme={null} curl -X POST https://api.swippee.com/v1/consents \ -H "Authorization: Bearer swippee_sk_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "report_id": "cl_abc123", "scopes": ["identity", "income", "verify"], "grantee_label": "Nabil Bank loan desk", "expires_in_days": 7 }' # → { "id": "...", "token": "swcon_…", "data_url": "…/v1/consents/:id/data?token=…", # "scopes": [...], "expires_at": "..." } ``` Valid `scopes`: `identity`, `income`, `liabilities`, `verify`, `transactions`. Expiry defaults to 30 days (max 365). ## Redeem (grantee — token only, no API key) ```bash theme={null} curl 'https://api.swippee.com/v1/consents/:id/data?token=swcon_…' # → { "scopes": [...], "data": { "identity": {...}, "income": {...} } } ``` ## List & revoke (owner) ```bash theme={null} curl https://api.swippee.com/v1/consents \ -H "Authorization: Bearer swippee_sk_live_xxx" curl -X POST https://api.swippee.com/v1/consents/:id/revoke \ -H "Authorization: Bearer swippee_sk_live_xxx" # after revoke, redeem returns 403 consent_inactive ``` # Credit widget Source: https://docs.swippee.com/guides/credit-widget Embed an in-app pre-qualification widget: the customer taps, consents, and gets an instant pre-qualified decision — powered by Swippee underwriting, the final call stays yours. The **Swippee Credit widget** is a drop-in surface an institution embeds in its own app. The customer taps *“Need extra cash?”*, consents to share their account activity, and gets an instant **pre-qualified** decision — computed by Swippee's underwriting engine. It is institution-led: your brand carries the header, Swippee is the quiet "Powered by", and the **final loan decision stays yours**. **In preview — not yet self-serve.** Two things are gated until Swippee enables your institution (email [hello@swippee.com](mailto:hello@swippee.com)): * **Embedding only works on allowlisted origins.** Today `/embed/credit` allows **same-origin framing only**, so the snippet below will not load on your site until we add your domain to the allowlist. * **The `@swippee/connect-react` `SwippeeCredit` export ships with enablement** — it is not on the public npm release yet. Meanwhile, try it on our [live demo](https://swippee.com/products/connect/credit-demo). In sandbox/demo mode the decision is computed by the real engine over a **synthetic** statement — no customer data is touched. See the [live demo](https://swippee.com/products/connect/credit-demo). ## How it works Drop the card into your app with one script tag (or the React component). They tap the card and approve sharing their income & obligations — on Swippee, never on your page. On a pre-qualified result the widget posts a short-lived `public_token` back to your page. `POST /v1/connect/exchange` to read the underwriting result, then make your lending decision. ## Quick start (script tag) ```html theme={null}
``` ## React ```tsx theme={null} import { SwippeeCredit } from "@swippee/connect-react"; { if (r.status === "prequalified") exchange(r.publicToken); }} />; ``` ## Options | Option | Type | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app` | string | Your institution/app name, shown in the sheet header. | | `accent` | string | Your brand colour (`#rrggbb`). Themes the widget; never recolours the Swippee mark. | | `amount` | number | Advertised maximum loan, NPR (default 500,000). | | `theme` | string | `light` or `dark` (default `light`). | | `bank` | string | Your own bank code → excluded from the "add your other banks" grid. | | `brand` | string | Entry-card attribution: `text` (default — "Powered by Swippee"), `mark` (logo + text), or `none`. Inside the flow, the "Powered by Swippee" footer always shows. | | `scenario` | string | Sandbox demo profile: `salaried`, `high_risk`, `thin_file`, `remittance`. | | `onResult` | function | Fired with `{ status, public_token, amount, emi, tenor }`. | | `onClose` | function | Fired with `{ reason }` when the customer dismisses the flow. | ## The result ```json theme={null} { "status": "prequalified", "public_token": "swcredit_…", "amount": 500000, "emi": 11634, "tenor": 60 } ``` `amount` and `emi` are the headline pre-qualified offer; **terms and final approval are yours to set**. Exchange the `public_token` for the full underwriting result: ```bash theme={null} curl -X POST https://api.swippee.com/v1/connect/exchange \ -H "Authorization: Bearer $SWIPPEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "public_token": "swcredit_…" }' ``` ## Security & privacy * The customer consents on Swippee — **your page never sees their statement or login**. * Cross-origin messages are accepted **only** from the Swippee origin. * The widget shows a pre-qualification, not a loan offer; the copy makes the institution's final-decision role explicit. * Reasons are shown to the customer **only on a decline** (with encouraging next-steps); the full underwriting detail is server-side, for your team. ## Other banks & wallets The customer can optionally add accounts from **any bank or wallet Swippee supports** for a fuller picture and a higher limit — the list stays in sync with Swippee's coverage automatically. See [Connect](/guides/connect) for the statement-sharing flow each added account uses. # Swippee Data API Source: https://docs.swippee.com/guides/data-api Read-only access to Nepal's public-sector financial data — forex, interest rates, payments, macro — sourced from Nepal Rastra Bank with attribution. Read-only access to Nepal's public-sector financial data, parsed from Nepal Rastra Bank's releases. These endpoints **require your API key** and count against your monthly Data API quota (500 on Sandbox, 2,500 on Growth, 5,000 on Scale). Every response is wrapped in a `{ data, meta }` envelope — `meta` carries the source, publication date, and an attribution string you must surface when republishing. ## Datasets | Dataset | Cadence | Endpoints | | ------------------------------------- | -------------------- | -------------------------------------------------------------------------------------- | | **Forex reference rates** | Daily (weekdays) | `/v1/data/nrb/forex/latest` · `/forex/series` · `/forex/convert` | | **Monthly banking statistics** | Monthly | `/v1/data/nrb/banking/snapshot` · `/banking/indicators` · `/banking/indicators/series` | | **Commercial-bank interest rates** | Monthly (since 2016) | `/v1/data/nrb/interest-rates/latest` · `/interest-rates/series` | | **Macroeconomic situation** | Monthly | `/v1/data/nrb/macro/latest` · `/macro/series` | | **Payment systems indicators** | Monthly | `/v1/data/nrb/payments/latest` · `/payments/series` | | **Central Bank Survey** | Monthly (since 2010) | `/v1/data/nrb/cbs/latest` · `/cbs/series?indicator=` | | **Depository Corporations Survey** | Monthly (since 2010) | `/v1/data/nrb/dcs/latest` · `/dcs/series?indicator=` | | **Consumer Price Index** | Monthly (since 2017) | `/v1/data/nrb/cpi/latest` · `/cpi/series?indicator=` | | **Merchandise Trade** | Monthly (since 2016) | `/v1/data/nrb/trade/latest` · `/trade/series?indicator=` | | **Official Reserve Assets** | Monthly (since 2016) | `/v1/data/nrb/reserve/latest` · `/reserve/series?indicator=` | | **Banking balance sheet** (aggregate) | Monthly (since 2021) | `/v1/data/nrb/banking/balance-sheet/latest` · `/series?key=` | | **Banking profit & loss** (aggregate) | Monthly (since 2021) | `/v1/data/nrb/banking/pnl/latest` · `/series?key=` | | **Banking sector credit** (aggregate) | Monthly (since 2021) | `/v1/data/nrb/banking/credit/latest` · `/series?key=` | | **Per-bank balance sheet** | Monthly (since 2021) | `/v1/data/nrb/banks/balance-sheet/latest?bank=` · `/series?key=` | | **Per-bank profit & loss** | Monthly (since 2021) | `/v1/data/nrb/banks/pnl/latest?bank=` · `/series?key=` | | **Per-bank sector credit** | Monthly (since 2021) | `/v1/data/nrb/banks/credit/latest?bank=` · `/series?key=` | | **Licensed BFI directory** | Quarterly | `/v1/data/nrb/bfis` | ## Example ```bash theme={null} curl https://api.swippee.com/v1/data/nrb/interest-rates/latest \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` ```json theme={null} { "data": [ { "metric": "base-rate", "label": "Base Rate", "value": 5.0, "unit": "percent", "sheet": "C23" }, { "metric": "wavg-deposit", "label": "Weighted Avg. Deposit Rate", "value": 3.4, "unit": "percent", "sheet": "C20" } ], "meta": { "source": "Nepal Rastra Bank", "source_url": "https://www.nrb.org.np/contents/uploads/.../publish.xlsx", "attribution": "Source: Nepal Rastra Bank — Monthly Banking & Financial Statistics. Republished by Swippee Data with attribution.", "as_of": "2026-04-15" } } ``` Macro figures additionally include a `source_quote` field — the verbatim sentence each number was verified against. Browse every dataset and its cadence at [swippee.com/products/data](https://swippee.com/products/data). # Merchant enrichment Source: https://docs.swippee.com/guides/merchant-enrichment Resolve Fonepay terminal PANs and merchant-name strings to a clean name, MCC, spend category, and city. Turn raw Fonepay terminal PANs and merchant-name strings into clean merchant data — name, MCC, spend category, and city — so you can enrich your own transaction feed with the same data that powers Swippee's parsing. Requires a Bearer key (`FULL` scope); bills 1 unit per call (batch up to 1000 lookups). ## Resolve a batch ```bash theme={null} curl -X POST https://api.swippee.com/v1/merchants/resolve \ -H "Authorization: Bearer $SWIPPEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "terminals": ["2222000000000000"], "names": ["Example Cafe"] }' ``` ```json theme={null} { "data": { "count": 2, "matched": 2, "results": [ { "input": "2222000000000000", "type": "terminal", "matched": true, "merchant": "Example Cafe", "mcc": "5814", "category": "dining", "city": "Kathmandu", "terminal": "2222000000000000" } ] }, "meta": { "source": "Swippee Enrich" } } ``` ## Single terminal lookup ```bash theme={null} curl https://api.swippee.com/v1/merchants/2222000000000000 \ -H "Authorization: Bearer $SWIPPEE_API_KEY" ``` ## Resolve from a QR poster Upload a Fonepay merchant QR poster (PDF or image) and get the merchant back — no need to read the terminal off it yourself. We read the printed terminal and, for images, decode the QR. Accepts PDF, JPEG, or PNG (max 10 MB); bills 1 unit. ```bash theme={null} curl -X POST https://api.swippee.com/v1/merchants/qr \ -H "Authorization: Bearer $SWIPPEE_API_KEY" \ -F "file=@poster.pdf" ``` ```json theme={null} { "data": { "found": true, "method": "qr", "source": "image", "terminal": "2222000000000000", "resolution": { "matched": true, "merchant": "Example Cafe", "mcc": "5814", "category": "dining", "city": "Kathmandu", "terminal": "2222000000000000" } }, "meta": { "source": "Swippee Enrich" } } ``` Name input is matched against the directory after normalization — so "Example Sweets PLTD" and "Example Sweets P LTD" resolve to the same merchant. Unmatched inputs come back with `matched: false` and null fields. # Sandbox Source: https://docs.swippee.com/guides/sandbox Integrate end-to-end with synthetic data before sending a real statement. The sandbox lets you build and test your Swippee integration against **fully synthetic, deterministic** data — no real bank statement required. It's the fastest way to wire up parsing, reports, and webhooks before going live. ## How it works Sandbox is **test mode**. Use a **test key** (`sk_test_…`) — every `/v1/sandbox` endpoint refuses live keys, so production traffic can never create synthetic data. Sandbox calls **never consume your quota**. Nothing in the sandbox touches real data. Every account holder, number, merchant and amount is fabricated, and a given scenario always returns the same result. ## Create a synthetic report ```bash theme={null} curl https://api.swippee.com/v1/sandbox/reports \ -H "Authorization: Bearer sk_test_…" \ -H "Content-Type: application/json" \ -d '{ "scenario": "salaried" }' ``` Returns a complete `StatementReport` (HTTP `201`) — identical in shape to a real parse — and **persists** it, so every report sub-endpoint works against the returned `report_id` immediately: ```bash theme={null} curl https://api.swippee.com/v1/reports/{report_id}/income -H "Authorization: Bearer sk_test_…" curl https://api.swippee.com/v1/reports/{report_id}/score -H "Authorization: Bearer sk_test_…" ``` ### Report scenarios | `scenario` | Profile | | ------------ | ---------------------------------------------------- | | `salaried` | Regular salary, stable growing balance, light EMI. | | `thin_file` | Very little history, no salary signal. | | `high_risk` | Declining balance, an overdraft, heavy EMI load. | | `remittance` | Foreign inward remittance is the main income source. | List them (and the error scenarios) any time: ```bash theme={null} curl https://api.swippee.com/v1/sandbox/scenarios -H "Authorization: Bearer sk_test_…" ``` ### Inject your own transactions Append edge cases to any scenario: ```json theme={null} { "scenario": "thin_file", "override_transactions": [ { "date": "2026-03-25", "description": "SANDBOX EXTRA CREDIT", "amount": 5000, "direction": "credit" } ] } ``` ## Force an error To test your error handling, ask for an `error_*` scenario — you get the exact [error envelope](/concepts/errors) a real failure would return: ```bash theme={null} curl https://api.swippee.com/v1/sandbox/reports \ -H "Authorization: Bearer sk_test_…" -H "Content-Type: application/json" \ -d '{ "scenario": "error_unsupported_bank" }' # → 422 { "error_code": "UNSUPPORTED_BANK", "error_type": "DOCUMENT_ERROR", … } ``` Available: `error_unsupported_bank`, `error_unsupported_document`, `error_password_required`, `error_image_not_tamper_verified`, `error_tamper_detected`. ## Fire a webhook Trigger a delivery to your registered [webhook](/concepts/webhooks) endpoints on demand — no waiting for a real parse: ```bash theme={null} curl https://api.swippee.com/v1/sandbox/reports/{report_id}/fire_webhook \ -H "Authorization: Bearer sk_test_…" -H "Content-Type: application/json" \ -d '{ "event": "report.ready" }' ``` Use `{ "event": "report.failed", "error_code": "TAMPER_DETECTED" }` to exercise your failure path. # SDKs & client libraries Source: https://docs.swippee.com/guides/sdks Official Swippee packages — the TypeScript API client (@swippee/sdk) and the React Connect component (@swippee/connect-react). Swippee ships two official packages. Both are MIT-licensed, have zero runtime dependencies, and work in Node 18+ and modern browsers. TypeScript client for the whole API — parse, products, enrichment, banks, data. Use it server-side with your secret key. React component for the hosted Connect consent flow. Use it in the browser. ## @swippee/sdk — API client ```bash theme={null} npm install @swippee/sdk ``` ```ts theme={null} import { Swippee } from "@swippee/sdk"; const swippee = new Swippee({ apiKey: process.env.SWIPPEE_SECRET_KEY! }); // Parse a bank statement PDF const report = await swippee.parse({ file: pdfBlob, bank: "NABIL" }); console.log(report.statement.bank, report.transactions.length); ``` The SDK uses your **secret** key — keep it server-side, never ship it to the browser. ## @swippee/connect-react — hosted Connect ```bash theme={null} npm install @swippee/connect-react ``` The consumer authenticates and consents in a Swippee-hosted popup; your app never sees their statement or login. On approval you get a `public_token` to [exchange on your server](/guides/connect). ```tsx theme={null} import { SwippeeConnect } from "@swippee/connect-react"; fetch("/api/connect-request").then((r) => r.json())} onHostedSuccess={({ publicToken }) => exchangeOnYourServer(publicToken)} onExit={(info) => console.log("closed:", info.reason)} /> ``` Prefer your own trigger? Use the headless hook: ```tsx theme={null} import { useSwippeeConnect } from "@swippee/connect-react"; const { open } = useSwippeeConnect({ createRequest: () => fetch("/api/connect-request").then((r) => r.json()), onHostedSuccess: ({ publicToken }) => exchangeOnYourServer(publicToken), }); // Connect bank ``` No bundler? The same hosted flow is available as a plain `