PayPal
Configure PayPal in Autonnel: credentials, sandbox testing, capturing orders, and how the refund flow writes back to your store.
PayPal supports both one-step capture and two-step authorize-then-capture flows. Sandbox and live environments use separate credentials — select the mode in the configuration form.
Prerequisites
- A PayPal business account.
- A PayPal sandbox account for testing, created in the PayPal Developer Dashboard.
- Client ID and client secret from a PayPal REST app. Sandbox apps and live apps have separate credentials.
Setup walkthrough
1. Create a PayPal REST app
In the PayPal Developer Dashboard:
- Go to Apps & Credentials.
- Under Sandbox (for testing) or Live (for production), click Create App.
- Give it a name and save. PayPal generates a client ID and secret for this app.
2. Open the PayPal card
Go to Settings → Payment. Click Configure on the PayPal card.
3. Enter credentials
| Field | Value |
|---|---|
| Client ID | From your PayPal REST app |
| Client secret | From your PayPal REST app |
| Mode | sandbox for testing, live for production |
Save the config. The card status indicator switches to Active.
4. Verify with a sandbox order
Create a test order using a sandbox buyer account. Sandbox buyer accounts are created in the PayPal Developer Dashboard under Sandbox → Accounts. Use the sandbox buyer’s email and password when PayPal’s approval page appears.
Checkout buttons
The PayPal integration surfaces two button components in the Puck page editor:
- PayPalExpressButton — renders the PayPal Express Checkout button. When clicked, it opens the PayPal approval flow directly. Use this when you want a fast single-click path for buyers who already have a PayPal account. Drop it into checkout pages using the
ExpressCheckoutblock, which renders the button with an “Or” separator. - PaymentForm — the standard checkout form that lets buyers choose between PayPal and other payment methods.
For upsell pages the adapter uses the two-step flow: it creates an AUTHORIZE intent at the initial checkout, then captures or voids on each subsequent upsell step.
Public checkout requests
Customer-facing PayPal, upsell, redirect, and final capture requests must include both orderId and trackingId. Autonnel treats the pair as the checkout flow capability and executes payment work in the order’s tenant context, so a request routed through one custom domain cannot process another tenant’s order with the wrong PayPal credentials.
Token caching
PayPal access tokens are cached to avoid a round-trip on every request. If you rotate your client secret, wait up to one hour for the cached token to expire and be refreshed.
Switching to live mode
- Return to Settings → Payment → PayPal.
- Replace the client ID and secret with your live-app credentials.
- Change Mode to
live. - Save. The adapter immediately starts hitting
api-m.paypal.com.
Sandbox credentials are silently rejected by the live endpoint, so do not mix them.
Refund flow
To issue a refund:
- Go to Orders, open the order.
- Click Refund, select full or partial amount, and confirm.
The refund is submitted to PayPal and the result is recorded automatically.
Refund window
PayPal allows refunds for up to 180 days after the original capture. After that window, you must process the refund manually outside of autonnel (e.g., through the PayPal business dashboard) and record it accordingly.
Balance requirements
For the refund to succeed, the PayPal account must either have sufficient balance or have a linked bank account that can cover the refund amount. Refunds that exceed the available balance will fail with a balance-related error from PayPal.
Caveats
- Credentials are environment-specific. Sandbox keys (
sb-...) only work againstapi-m.sandbox.paypal.com. If you set mode tolivebut leave sandbox credentials in place, every API call will return a 401. - Token refresh: If PayPal rejects a token mid-request (e.g., after a secret rotation), autonnel fetches a fresh token and retries the request once. If the retry also fails, the error is surfaced.
- Zero-decimal currencies: Pass the major-unit amount — autonnel formats it correctly for all currencies.
- Sandbox country codes: PayPal’s sandbox occasionally returns invalid two-letter country codes (such as
C2). The adapter falls back toUSwhen it detects an invalid code, so sandbox test orders may show a US shipping address even if the sandbox buyer selected another country.