AddThisFeature

PayPal Checkout

Accept PayPal payments with approval, capture, cancellation, and refund states tracked.

involved Payments & Finance

What it adds

A server-driven PayPal payment flow that records each stage separately and reconciles the browser's return against the app's own record of what was paid.

What your agent is told to do

5
  1. 1

    Create the order on the server from trusted records. The browser may say which item is being bought and nothing about what it costs.

  2. 2

    Model approval and capture as two distinct stages in the app's own data. A payer approving a payment is not the same as the money having moved, and collapsing them into one boolean is where this integration usually goes wrong.

  3. 3

    Generate a stable reference for each attempt and use it on every capture request, so a retry after a timeout resolves to the original capture rather than taking the money a second time.

  4. 4

    Verify incoming provider notifications as genuine and record their identifiers before acting, so retried deliveries update nothing twice.

  5. 5

    If the app also carries a Stripe brief, keep one shared local record of a completed purchase and its entitlement, with each provider writing into it. Do not let two providers each maintain their own idea of whether the user has paid.

Edge cases it handles

8
  • Prices, currency, and totals must be assembled server-side from records the user cannot edit. A total submitted by the browser is a suggestion from a stranger.
  • An order can sit approved but uncaptured, or be captured for less than the full amount. Both need their own local state and their own operator-visible resolution, rather than being treated as either paid or not paid.
  • Notifications from the provider must be signature-verified and deduplicated by their identifier, because they are retried until acknowledged.
  • The payer's return to the app and the provider's server notification arrive independently and in either order. Resolve both against the app's own record of the attempt, and show a pending state rather than a contradiction while they disagree.
  • A capture request that times out may still have succeeded. Never blindly retry the raw request; retry with the original reference or query the current state first, or you will double-charge.
  • Refunds, partial refunds, and disputes change what the customer is entitled to. Decide what each does to access and reflect it in the same place the rest of the app reads.
  • When the provider is unavailable, present the failure honestly and leave the order in a resumable state instead of clearing the cart.
  • Currency support and payer country restrictions vary. Handle a rejection on those grounds with an explanation, not a generic error.

Definition of done

9
  • Orders are created server-side and no amount, currency, or quantity is accepted from the browser.
  • Approved, captured, partially captured, cancelled, and refunded are distinct, visible local states.
  • Provider notifications are signature-verified and processed once regardless of retries.
  • The browser return and the server notification reconcile to one truthful state in either arrival order.
  • A timed-out or repeated capture never results in a second charge.
  • Refunds and partial refunds update entitlement through the same record the rest of the app reads.
  • Provider outages leave the order resumable and the user informed.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.