Autonnel v1.7.0

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, and Autonnel detects which environment an app belongs to when you save the account.

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:

  1. Go to Apps & Credentials.
  2. Under Sandbox (for testing) or Live (for production), click Create App.
  3. Give it a name and save. PayPal generates a client ID and secret for this app.

2. Add a PayPal account

Go to Payment and click Add account under PayPal.

3. Enter credentials

FieldValue
Client IDFrom your PayPal REST app. Required: there is no environment variable fallback
Client secretFrom your PayPal REST app
ModeRead-only. Set on save to the environment that accepts the client ID and secret

When you save, Autonnel requests an access token from both api-m.paypal.com and api-m.sandbox.paypal.com and stores the mode of whichever accepts the credentials. If neither does (wrong secret, or the ID and secret come from different apps), the save fails with an error and nothing is stored. If PayPal cannot be reached, the save fails and you can retry.

Save the account, then bind it to each domain that should take PayPal: Pages → Domains, click the domain, Payment tab, select the account in the PayPal row. A domain with no payment account bound cannot check out.

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 ExpressCheckout block, which renders the button with an “Or” separator.
  • PaymentForm — the standard checkout form that lets buyers choose between PayPal and other payment methods.

Card form

Turn on Credit / debit card form on the PayPal account’s page under Payment to add a Card tab to the payment form. Buyers type their card number into PayPal-hosted fields and pay without a PayPal account; the payment is still a PayPal order and is refunded the same way.

  • PayPal must enable Advanced Credit and Debit Card Payments on your account first. Without it the tab shows that card payment is unavailable, so leave the switch off until PayPal approves the account.
  • 3D Secure runs when the card issuer or local regulation requires it (SCA_WHEN_REQUIRED).
  • When the switch is on, the payment form opens on the Card tab (on the Stripe card tab if Stripe is also active); the PayPal button stays on its own tab.
  • If another card provider is also active, buyers see two card options. Keep only one active if that is confusing.

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

  1. Open the PayPal account under Payment.
  2. Replace the client ID and secret with your live-app credentials.
  3. Save. Mode switches to live because the live API accepted the credentials, and the adapter immediately starts calling api-m.paypal.com.

Refund flow

To issue a refund:

  1. Go to Orders, open the order.
  2. 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.

Brand name in the PayPal checkout

PayPal orders carry the sale domain’s store name as brand_name, so a buyer on one brand’s domain sees that brand’s name in the PayPal window rather than your PayPal account’s business name. Without a store name, PayPal shows the account’s own name.

Caveats

  • Credentials are environment-specific. A client ID does not show which environment it belongs to, which is why the mode is detected on save instead of chosen. Accounts created by npx autonnel payments:migrate-accounts keep the mode from the old configuration until they are saved again; if checkout fails with invalid_client, open the account and save it.
  • 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 to US when it detects an invalid code, so sandbox test orders may show a US shipping address even if the sandbox buyer selected another country.