← API Index

PayPal payments in a customer context

This document is for a client that drives the checkout of a logged-in shopper on top of the customer API — a partner frontend replacing the standard shop. PayPal comes in two shapes here, and both end in an ordinary order store:

Flow Paycode Who pays when Needs the PayPal JavaScript SDK?
SDK checkout 2 (PayPal) in the cart, before the order is stored yes
Pay by link 9 (prepaid via PayPal link) later, from a link in the order confirmation e-mail no

Wero, the other provider-backed method, has its own document: customer Wero API. See use the API for how to authenticate at all.

The standard shop's cart implements everything below. You only need this if you are building your own cart and checkout in place of it.

Prerequisites

Flow A: SDK checkout (paycode 2)

The shape to internalize: PayPal only authorizes in the cart; the money moves when the order is stored. The authorization is remembered on the shopper's session, and the order store call picks it up.

  1. Load the SDK from the URL returned by /api/system/ppscript1 (script_url; configured is false when the shop has no PayPal). The URL already carries the right client id, merchant id and sandbox/production host — do not build it yourself. Note this call needs an API key, unlike the two below.
  2. Create the order from the SDK's createOrder callback by POSTing to /api/client/ppauthorize1 with the cart figures: total (all positions including VAT, without shipping), vatsum (VAT contained in total and shipping), shipping, count (number of positions) and relvoucherid when a relative voucher sits in the cart. The backend adds the tenant's overcharge, subtracts the voucher, checks that the delivery date has no locked order yet and returns a token. Resolve the SDK promise with it — it is the PayPal order id. A 409/ERROR means PayPal could not be started (configuration or upstream problem); nothing is pending then.
  3. The customer logs in and approves inside the SDK overlay.
  4. From onApprove POST /api/client/ppresponse1 with ppresult=confirmed, token (the SDK's orderID), PayerID (the SDK's payerID), guid=0 and sid (your session id). confirmed back means the authorization is now attached to the session. 403/security means the token does not belong to this session — treat it as a failed payment and start over at step 2.
  5. Store the order with /api/client/neworder8 (or /api/client/changeorder8 for a change) and used_paycode = 2. The order is written first, then the backend authorizes or captures the PayPal order and clears the session's pending authorization. The owner's notification carries the PayPal transaction id; the customer's confirmation looks like any other order mail.

Whether step 5 should follow the approval immediately depends on the token: an EC-… token is a legacy express-checkout authorization and keeps for a while, any other token is a PayPal Orders v2 id that must be captured promptly — the standard cart submits the order right away in that case instead of showing a second "buy" button. Do the same.

Nothing to integrate client-side beyond the order store:

  1. Offer the method when prepaid_paypal_enabled is true and 9 is in the shopper's allowed_paycodes. Show prepaid_paypal_info as the explanatory text.
  2. Store the order with used_paycode = 9.
  3. The order confirmation e-mail contains a "Pay now with PayPal" button and the raw link. The PayPal order is only created when the customer clicks it, so the link does not expire before the customer gets to it; after payment the customer lands on the shop's thank-you page (or the tenant's configured return page).

The order is stored unpaid and lives its normal life; the payment is a separate event the tenant reconciles. A changed order gets a new link in the new confirmation mail, and the old link answers with "expired or changed".

The overcharge, and why amounts differ

Weighed goods and deposits can move the final invoice above the cart total. The tenant can therefore configure an overcharge: paypal_over (percent of the total) or paypal_over_a (a fixed amount), both exposed in Config. The amount PayPal shows the customer is the cart total plus that overcharge; the standard cart explains this in the PayPal dialog ("we ask for an authorization of +X over the cart value …") — explain it in yours too, PayPal does not.

How the difference comes back depends on paypal_mode:

Either way, never assert that the PayPal amount equals the order total, and do not show the customer the PayPal figure as "your price".

Things not to forget

What the API tells you about a PayPal order

Ideas

Response types