Developers

The whole integration is three steps

Endpoints and payloads on this page are the demo interface. Shapes are stable enough to review; they are not a production contract.

Demo environment

Step 1

POST

Create a customer session

/v1/sessions

{
  "program_id": "prog_northstar_rewards",
  "external_customer_id": "cust_12345",
  "completion_redirect_url": "https://northstar.example/rewards"
}

{
  "session_token": "short_lived_demo_token",
  "hosted_url": "https://connect.airyvl.com/session/demo"
}

Step 2

CLIENT

Launch Airyvl

hosted link or JS SDK modal

// Option A — hosted link
window.location = hosted_url;

// Option B — modal
Airyvl.open({ sessionToken: session_token });

// customer completes consent, connection and optional receipt upload

Step 3

WEBHOOK

Receive intelligence

POST https://api.northstar.example/hooks/airyvl

{
  "event": "customer.intelligence.updated",
  "external_customer_id": "cust_12345",
  "item": "Running Shoes",
  "evidence": "predicted",
  "confidence": 0.84,
  "source_transaction_id": "txn_demo_918"
}

200 OK

Transaction connection architecture

Plaid sandbox / planned integration

Brand customer sessionCreated server-to-serverAiryvlProgram config + consent scopesPlaid LinkSandbox / planned integrationAiryvl backendTransaction sync + webhooksItem-level layerVerified receipts + prediction

Plaid provides merchant, date, amount and category-level signals. Item-level intelligence comes from verified receipt data and Airyvl prediction — card transactions do not return SKUs.

Session security

No permanent secret is ever placed in browser code.
Session tokens are short-lived and single-use.
Redirect URLs and embed origins are allowlisted per program.
Consent scopes are stored per customer and revocable.
Demo environment — no security certifications are claimed.

Event log & delivery

Every program emits the same event stream to webhooks and destinations.

Seeded + live session events

Event	Detail	Time	Delivery
session.created	program_id=prog_northstar_rewards · external_customer_id=cust_12345	Aug 19, 09:12:04	200
consent.granted	scopes: transactions, receipts, personalized_insights	Aug 19, 09:12:31	200
account.connected	sandbox institution · 8 transactions synced	Aug 19, 09:12:58	200
receipt.uploaded	rcp_3391 · Green Market · $72.48	Aug 19, 09:13:40	200
receipt.matched	rcp_3391 → txn_5002 · confidence high	Aug 19, 09:13:42	200
item.verified	4 verified items from rcp_3391	Aug 19, 09:13:43	200
item.predicted	Running Shoes · 0.84 from txn_demo_918	Aug 19, 09:14:02	200
reward.earned	1,000 Northstar Points	Aug 19, 09:14:10	200
customer.intelligence.updated	cust_12345 · 3 attributes changed	Aug 19, 09:14:12	200
destination.delivery.succeeded	Demo Salesforce connector · 200 OK	Aug 19, 09:14:13	200