Stripe
A single restricted API key gives Athia your Stripe activity end to end: charges, approvals and declines, refunds and disputes, and what Stripe settled and charged you for.
What you get
Payments and payment attempts with their outcomes, refunds, disputes, and the fee recorded against each transaction.
Strongest for breadth from one credential. One restricted key covers every domain — there are no reports to enable first, which makes this the fastest connector to stand up.
Weakest for cost granularity. Fees arrive blended, so interchange cannot be split from scheme and gateway components. For interchange-level work, add Adyen or Checkout.com data.
Before you start
Your Stripe account's API version must be 2019-02-19 or later.
Create a restricted API key (rk_…) for Athia in the Stripe console — not your standard secret key:
- Go to Developers → API keys and choose Create restricted key.
- Choose Building your own integration and continue.
- Name the key — for example,
Athia Integration. - Set the permissions below.
- Create the key and copy the token.
| Access | Resources |
|---|---|
| Read | Balance, Balance transaction sources, Balance Transfers, Charges, Disputes, Events, Files, PaymentIntents, PaymentMethods, Payouts, Products, SetupIntents, Sources, Tokens, Credit notes, Subscriptions, SKUs, Report Runs, Report Types. If you use Connected Accounts, also grant Read on the Connect resources, including Account Links. |
| Write | Webhook Endpoints |
Three grants are easy to miss. One stops the connection dead; the other two fail silently.
Read on Events is mandatory — without it the connection fails outright. Read on Reporting (Report Runs and Report Types) is what makes transaction-level card fee data available, and omitting it produces missing fee data with no obvious cause.
| Grant | Omit it and |
|---|---|
| Read on Events | The connection fails outright. |
| Read on Reporting — Report Runs and Report Types | Transaction-level card fee data is unavailable, with no obvious cause. |
| Read on the Connect resources, including Account Links | Connected-account data cannot be selected at all. |
The Webhook Endpoints grant is write-capable. Athia uses it for one purpose: to register the endpoint that receives ongoing Stripe events, which it then reads. It does not create, modify or refund a payment. Every other permission on the key is read-only.
Credentials Athia asks for
| Field | Required | What it is / where to find it |
|---|---|---|
| Name | Yes | Your label for this connection — identify the Stripe account it covers |
| Schedule | No | How often Athia polls Stripe |
| Api Key | Yes | The restricted key created above |
| Historical Sync Time Frame | Yes | All Time or Date Limit — how far back the backfill reaches |
| Backward Sync Limit | With Date Limit | The earliest date the backfill reaches |
Setting up the connection
- In Settings → Connections, choose + Add Connection and select Stripe.
- On Configure Connector, enter a Name and pick a Schedule.
- On Enter Credentials, paste the key into Api Key, choose a Historical Sync Time Frame, and set the Backward Sync Limit date if Date Limit reveals one.
- Choose Verify Connection.
- Copy the Athia Webhook Destination URL shown in the wizard.
- In Stripe, go to Developers → Webhooks → Add endpoint, paste that URL, and select the events
charge.succeeded,dispute.createdandpayout.paid. Test, save, and enable the endpoint.
If an Athia webhook endpoint already exists on this Stripe account, remove the old one first to avoid conflicts.
The connection then shows as ACTIVE and the first sync starts. For every additional Stripe account — including Connected Accounts — create a separate restricted key and a separate connection.
Sync cadence
Pick a Schedule that matches how closely you watch acceptance. Faster polling does not improve payout and fee records, which change only when Stripe settles.
Limits and things to know
- Historical sync is capped at one year. All Time backfills the full year Athia can reach; Date Limit takes a Backward Sync Limit date, which cannot be earlier than one year before today. For older history, load it through a secure file drop (SFTP/S3) — see Integrating Athia.
- Fees are blended. Granular interchange is not available through this connector.
- Amounts are minor units — divide by 100. Athia handles this on ingest; it matters when reconciling against a raw Stripe export.
- Card data is minimized. For what each ingested field holds, see Athia Data Dictionary.
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
| Verification succeeds but a domain is empty | Missing Read on that resource | Edit the key's permissions, then reconnect |
| Less history than expected | The one-year cap | Load older history through a secure file drop |
Related
- Athia Connectors — the full connector catalog.
- Integrating Athia — integration paths, including file drops and warehouse-to-warehouse.
- Athia Data Dictionary — field-level definitions.
Updated 1 day ago