billingHelp

PayPal

From a PayPal Business account to live payments — the REST app, Client ID and Secret, the webhook and its ID, sandbox buyers and the go-live checklist.

Create the business account#

  1. Open a PayPal Business account at paypal.com (or upgrade a personal one).
  2. Confirm the email address, link and confirm a bank account, and complete the business verification PayPal asks for.
  3. Sign in to developer.paypal.com with the same login. The developer dashboard has a Sandbox and a Live side; switch with the toggle at the top.

Create the REST app#

  1. Apps & Credentials → (Sandbox) → Create App. Name it after your store, type Merchant, and choose the sandbox business account PayPal created for you.
  2. Copy the Client ID and the Secret.
  3. Under the app's features, make sure Accept payments and Subscriptions are enabled (they usually are by default). For disputes, keep Customer disputes on.

Paste the Client ID and Secret into a new PayPal credential set with environment Test.

Register the webhook#

On the app's page → Sandbox Webhooks → Add Webhook:

  1. Webhook URL — the one shown on your credential set:
  1. Select these events:
  • CHECKOUT.ORDER.APPROVED
  • PAYMENT.CAPTURE.COMPLETED
  • PAYMENT.CAPTURE.PENDING
  • PAYMENT.CAPTURE.DENIED
  • PAYMENT.CAPTURE.DECLINED
  • PAYMENT.CAPTURE.REFUNDED
  • PAYMENT.CAPTURE.REVERSED
  • PAYMENT.SALE.COMPLETED
  • PAYMENT.SALE.DENIED
  • PAYMENT.SALE.REFUNDED
  • PAYMENT.SALE.REVERSED
  • BILLING.SUBSCRIPTION.ACTIVATED
  • BILLING.SUBSCRIPTION.UPDATED
  • BILLING.SUBSCRIPTION.RE-ACTIVATED
  • BILLING.SUBSCRIPTION.SUSPENDED
  • BILLING.SUBSCRIPTION.CANCELLED
  • BILLING.SUBSCRIPTION.EXPIRED
  • BILLING.SUBSCRIPTION.PAYMENT.FAILED
  • CUSTOMER.DISPUTE.CREATED
  • CUSTOMER.DISPUTE.UPDATED
  • CUSTOMER.DISPUTE.RESOLVED
  1. Save. PayPal shows the new webhook's Webhook ID. Paste it into the set's Webhook ID.

Verify credentials now also reads the webhook and reports its URL and event count. Then Put in service (Test).

Test in the sandbox#

Developer dashboard → Testing Tools → Sandbox Accounts lists a personal (buyer) account with its email and password. Pay on your product page, sign in to PayPal as that buyer, and approve. The payment becomes Paid a few seconds later. Test a refund too.

Subscriptions: the buyer approves the subscription on PayPal. With a trial, the first charge comes when the trial ends; the subscription shows Trialing until then.

Go live#

  • [ ] Business account verified, bank account confirmed.
  • [ ] Live side → your app (or a new live app) → live Client ID and Secret in a live credential set.
  • [ ] Live Webhooks → the same URL from the live set and the same events → live Webhook ID in the set.
  • [ ] Products switched to the live set.
  • [ ] One small real payment and refund.

Common errors#

MessageFix
Verify fails with an authentication errorClient ID and Secret are from the other side (Sandbox/Live) or from different apps.
Webhook deliveries answer 400The Webhook ID belongs to another webhook or the other side.
Webhook deliveries answer 503No Webhook ID in the set yet, or PayPal's verification service was unreachable; PayPal retries.
Plan change waitsPayPal asks the buyer to approve a new price; the change applies after approval, at renewal.
Payment shows ProcessingA PayPal eCheck or a held payment; it becomes Paid or Failed when PayPal decides.

Technical details#

Credentials. Go to developer.paypal.com → Apps & Credentials, choose Sandbox or Live, then open your REST app.

  • Client ID → Client ID.
  • Secret → Secret, stored sealed.
  • After you add the webhook (below), copy the Webhook ID into the set.

Verify obtains an OAuth token (POST /v1/oauth2/token). If a Webhook ID is present, it also reads that webhook (GET /v1/notifications/webhooks/{id}) and reports its URL and event count.

Webhook. In the app, choose Add Webhook and paste the URL shown on the set (https://encrypted.com/webhooks/paypal.php?cs=…). Select these events:

  • CHECKOUT.ORDER.APPROVED
  • PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED
  • PAYMENT.SALE.COMPLETED, PAYMENT.SALE.DENIED, PAYMENT.SALE.REFUNDED, PAYMENT.SALE.REVERSED
  • BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.UPDATED, BILLING.SUBSCRIPTION.RE-ACTIVATED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.EXPIRED, BILLING.SUBSCRIPTION.PAYMENT.FAILED
  • CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, CUSTOMER.DISPUTE.RESOLVED

How a delivery is verified. The five PAYPAL-* transmission headers, the Webhook ID and the event are posted to /v1/notifications/verify-webhook-signature. Only verification_status = SUCCESS passes. Before that call, the endpoint checks:

  • all five headers are present;
  • the cert URL is https://…paypal.com;
  • the transmission is less than 3 days old.

The event is sent back byte-for-byte, spliced into the request rather than re-encoded, because re-encoding can change numbers and escaping and fail the check. If PayPal cannot be reached, or the app's credentials are refused, the endpoint answers 503 and PayPal retries.

One-time flow.

  1. An order is created (custom_id and invoice_id are our checkout id) and the buyer approves it on PayPal.
  2. The order is captured when the buyer comes back. It is captured again on CHECKOUT.ORDER.APPROVED in case the buyer never returns. The capture is idempotent through PayPal-Request-Id.
  3. PAYMENT.CAPTURE.COMPLETED marks the payment Paid.

A pending capture (for example a PayPal eCheck) shows Processing until COMPLETED or DENIED arrives.

Subscriptions.

  • A catalog product and a billing plan are created once per price and cached per credential set.
  • Quarterly is MONTH × 3. Annual is YEAR × 1.
  • A free trial is a TRIAL cycle with no pricing scheme.
  • The subscription starts with user_action = SUBSCRIBE_NOW.
  • BILLING.SUBSCRIPTION.ACTIVATED starts access (Trialing during a trial).
  • Each charge is a PAYMENT.SALE.COMPLETED. Failed charges arrive as BILLING.SUBSCRIPTION.PAYMENT.FAILED and leave the subscription Past due for 3 days of grace.
  • SUSPENDED means Unpaid (access ends). CANCELLED and EXPIRED mean Canceled.

Refunds. One-time payments are refunded on the capture (/v2/payments/captures/{id}/refund). Subscription charges are refunded on the sale (/v1/payments/sale/{id}/refund). Both are confirmed by the refund webhook.

Disputes. CUSTOMER.DISPUTE.CREATED marks the payment Disputed and emails the owners. RESOLVED in the buyer's favour means Chargeback; in the seller's favour, Paid. A reversal without a dispute (PAYMENT.CAPTURE.REVERSED or PAYMENT.SALE.REVERSED) is recorded as a dispute that was opened and lost.