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
- A session logged on as the shopper (see api/logon4).
- The tenant has PayPal configured in the shop settings (a PayPal account; for the link flow
and the card-capable SDK additionally a PayPal merchant id). You can tell from the
Config object:
paypal_id—0PayPal is off,1on,2on and offered even when the customer could pay by SEPA direct debit. Negative values mean the shop talks to the PayPal sandbox: expect test accounts, show a hint to your testers.prepaid_paypal_enabled/prepaid_paypal_info— the link flow is on, and the (HTML encoded) text to show the customer before they choose it.paypal_over,paypal_over_a,paypal_mode— the overcharge and settlement mode, see below.
- The shopper is allowed to use the method:
2and/or9are inallowed_paycodesof the UserInfo object. The backend lists what the tenant offers and the customer's payment profile permits; the standard cart additionally hides PayPal when the customer has a usable SEPA setup andpaypal_idis1, not2. Mirror that rule if you want the same behaviour.
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.
- Load the SDK from the URL returned by
/api/system/ppscript1 (
script_url;configuredisfalsewhen 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. - Create the order from the SDK's
createOrdercallback 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) andrelvoucheridwhen 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 atoken. Resolve the SDK promise with it — it is the PayPal order id. A409/ERRORmeans PayPal could not be started (configuration or upstream problem); nothing is pending then. - The customer logs in and approves inside the SDK overlay.
- From
onApprovePOST /api/client/ppresponse1 withppresult=confirmed,token(the SDK'sorderID),PayerID(the SDK'spayerID),guid=0andsid(your session id).confirmedback means the authorization is now attached to the session.403/securitymeans the token does not belong to this session — treat it as a failed payment and start over at step 2. - 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.
Flow B: pay by link (paycode 9)
Nothing to integrate client-side beyond the order store:
- Offer the method when
prepaid_paypal_enabledistrueand9is in the shopper'sallowed_paycodes. Showprepaid_paypal_infoas the explanatory text. - Store the order with
used_paycode = 9. - 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:
0(refunded): the full amount is captured when the order is stored; after invoicing the tenant refunds what was too much.1(deferred): the order store only authorizes; the final invoice amount is captured later, the rest of the authorization is released. LEGACY, avoid using it for new implementations.
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
- Re-authorize after every cart change. An authorization is for one amount and one
delivery date. If the customer changes the cart after approving, cancel the pending
authorization (POST ppresponse1 again with
ppresult=canceledand the same token) and run steps 2–4 again before storing. The standard cart does exactly this on every cart event. - Changing a stored PayPal order means paying again. On a change submit the backend
refunds (or voids) the original payment of every modified order and then charges the new
authorization from the session. If you call changeorder8 for a PayPal order without a
fresh authorization, the original payment is reverted and the order stays unpaid with
used_paycode = 2. Keep the PayPal button on stored PayPal orders and force the shopper through the SDK again. - The session must survive. The authorization lives on the shopper's session. A new session (dropped cookie, other browser) cannot complete it; start over.
- Don't reuse a token. One ppauthorize1 token is good for exactly one order store.
- Guests: the standard cart only starts PayPal for a logged-on customer; send a guest through registration first.
- Sandbox: with a negative
paypal_idthe SDK and all captures run against PayPal's sandbox; use PayPal sandbox buyer accounts and do not expect money to move. - Subscriptions: a subscription keeps generating orders after the one you paid for; those later orders are unpaid and need the customer's regular payment method.
- Legacy script: a tenant without a merchant id gets the old
checkout.jsURL from ppscript1, which has nopaypal.ButtonsAPI and no card payments. Prefer tenants with a merchant id; the standard cart still supports both. - Order mails: the pay-by-link flow depends on the customer actually receiving the confirmation e-mail. A customer with notifications switched off never gets the link.
What the API tells you about a PayPal order
- Order
used_paycodeis2or9, andwasPaypalis1as soon as a PayPal reference exists for the order — for a link order that is already at store time, before the customer has paid. - There is currently no field that says whether a link order has been paid, nor the PayPal transaction id; the tenant sees both in the admin PayPal overview. If you need it in your client, ask for an API extension rather than inferring it.
Ideas
- Show the sandbox hint from
paypal_id < 0prominently in test shops; it saves support calls from testers who "paid" and see no money. - Use the pay-by-link method as the default for customers who order by phone or chat: an
operator stores the order with
used_paycode = 9, the customer pays from the mail. - Offer the SDK flow with card funding (merchant id required) to customers without a PayPal account — the same three calls, nothing changes on your side.
Response types
- PaypalScript — returned by /api/system/ppscript1
- PaypalAuthorize — returned by /api/client/ppauthorize1
- PaypalResponse — returned by /api/client/ppresponse1
- ChangeOrderResult — returned by /api/client/neworder8 / /api/client/changeorder8