PayPal Direct
PayPal Direct is a self-serve connector: a client ID and a secret, two read scopes, and five API settings enabled on the app. It is the best dispute source in the catalog, and it is settled reporting, which shapes what you can and cannot ask of it.
What you get
Settled transactions, balances and payouts, and dispute records with their lifecycle.
Strongest for disputes. PayPal's dispute data is more complete than most, which makes this the connector to lean on for dispute rate by segment, win and loss outcomes, and the lag between a transaction and the dispute it attracts. Disputes surface 30 to 180 days later, which is why a full year of history matters here.
Weakest for attempt-level failure analysis. Transaction Search is settled reporting — it tells you what completed, not what was tried, so per-attempt decline codes are not available here.
Before you start
Your merchant account must be enabled for Direct Payments. Live use requires PayPal approval — request it before you start.
In the PayPal console, create a REST API app for Athia and note its Client ID and Secret. This is the normal path. Legacy Direct Payments accounts instead use NVP/SOAP credentials — Username, Password and Signature.
Attach exactly two scopes:
transactions:readpayouts:read
These two scopes are read-only: this credential cannot capture, refund or send money.
Enable the app API settings
The scope strings do not gate the data on their own — the app's API settings do. Enable all five on the app:
| App setting | What it gates |
|---|---|
| Accept payments | Payments, authorizations, captures, refunds |
| Subscriptions | Billing plans and subscription records |
| Invoicing | Invoice records |
| Customer Disputes | Disputes and their lifecycle |
| Transaction Search | Settled transaction history and balances |
Without Invoicing and Subscriptions enabled, invoice and billing-plan data arrives empty.
After you enable new permissions on the app, PayPal can take up to nine hours to apply them. If verification fails immediately after you change scopes, that is the usual cause — wait and retry before re-issuing credentials.
Create a read-only role
Log into the PayPal Developer Dashboard as an admin and create a custom role — for example Athia Integration — with read-only permissions for:
- Transactions (search, details)
- Reporting (balances, transactions)
- Payouts (details)
- Subscriptions
- Disputes
Production and Sandbox are separate connections. Create an app and an Athia connection for each environment. Use live credentials for the production connection, or it verifies and carries nothing you recognize.
Credentials Athia asks for
| Field | Required | What it is / where to find it |
|---|---|---|
| Name | Yes | Your label for this connection — identify the PayPal merchant account |
| Schedule | No | How often Athia polls PayPal |
| Client Id | Yes | From the app you created for Athia |
| Secret Key | Yes | The matching secret for that app |
| Username / Password / Signature | Legacy only | NVP/SOAP credentials — use these instead of Client Id and Secret Key on legacy Direct Payments accounts |
Setting up the connection
- Create the app, enable the five API settings and confirm both scopes are attached.
- In Settings → Connections, choose + Add Connection and select PayPal Direct.
- On Configure Connector, enter a Name and pick a Schedule.
- On Enter Credentials, enter the Client Id and Secret Key.
- Choose Verify Connection.
- Copy the Athia Webhook Destination URL from the wizard.
- In the PayPal console, go to My Apps & Credentials → select your app → Webhooks → Add Webhook, paste the URL, and select
PAYMENT.CAPTURE.COMPLETED,DISPUTE.CREATEDandPAYOUTS.BATCH.PROCESSED. Save, then enable the webhook.
The connection then shows as ACTIVE and the first sync starts. For several PayPal merchant accounts, create an app and a connection for each.
Sync cadence
Settled reporting rewards frequent polling less than a gateway connector does, and polling faster will not produce attempt-level detail the source does not carry. Match the schedule to how often you actually read the data.
Limits and things to know
- No per-attempt decline codes. Transaction Search reports settled activity; source decline reasons from a gateway connector instead.
- Amounts are decimal — never divide by 100.
- Dispute timing. Disputes appear well after the transaction, so recent-period dispute rates always look better than they will turn out to be. Compare cohorts that have had time to mature.
- History reaches back three years. Transaction Search returns at most three years of transactions. For anything older, load files — see Integrating Athia.
- Card data is minimized. Field-level detail on what Athia stores is in Athia Data Dictionary.
PayPal amounts are decimal. PPRO amounts are minor units. Dividing by 100 in the wrong place is the most common reconciliation error across these two connectors.
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
| Transactions arrive but no payouts | payouts:read not enabled | Add the scope, then reconnect |
| No decline reasons anywhere | Expected — settled reporting only | Use a gateway-level connector for attempt data |
| Verification fails right after a scope or permission change | New permissions not applied yet | Wait up to nine hours, then retry — do not re-issue credentials |
| Invoice or billing-plan data is empty | Invoicing or Subscriptions not enabled on the app | Enable the app setting, wait for it to apply, then reconnect |
| No dispute or payout events arrive between polls | Webhook not registered or not enabled | Re-add the Athia Webhook Destination URL under My Apps & Credentials → Webhooks and enable it |
| Dispute rate looks unusually low | Recent transactions have not aged into their dispute window | Read dispute rate on matured cohorts |
Related
- Athia Connectors — the full connector catalog
- Athia Data Dictionary — field definitions
- Integrating Athia — file drops, warehouse shares and the other integration paths
Updated 1 day ago