The current PayPal deployment saves a customer’s payment method as part of a subscription or trial
checkout. It does not offer a standalone “add PayPal payment method” embed.
OurPayEmbedPaymentMethod is a card/Stripe setup flow and is unavailable when Stripe is disabled.
Do not add that widget to a PayPal-only integration. Use the hosted checkout flow so PayPal can
collect the buyer’s approval.
How PayPal vaulting works
For a paid subscription, the buyer approves the first PayPal order and permission to save the
payment method. OurPay captures the first payment, stores the resulting PayPal Vault token as the
canonical customer payment method, and uses that token for later merchant-initiated renewals.
For a free trial, OurPay creates a PayPal setup token. No charge is made during approval. The saved
Vault token is used when the first paid billing period starts.
The stored OurPay payment method contains provider identifiers and display metadata; it never
contains the buyer’s PayPal password or raw funding credentials.
Requirements
PayPal payment-method saving is exposed only when all of these are true:
- PayPal is enabled for the deployment and organization.
OURPAY_PAYPAL_VAULTING_ENABLED=true.OURPAY_PAYPAL_MERCHANT_ID contains the receiving Business account’s merchant ID.- The PayPal REST application and account have the required save-payment-method/Vault capability.
- The checkout uses PayPal and needs a reusable method, such as a subscription or free trial.
The merchant ID is the PayPal account ID, not the REST client secret. OurPay disables vaulting when
the merchant ID is missing or mistakenly equals the client secret.
When these requirements are not met, one-time PayPal checkout can still work, but subscription and
trial checkout fails with PayPalCheckoutUnsupported. This is deliberate: OurPay will not create a
subscription that it cannot renew.
Use hosted checkout
Create a Checkout Link or Checkout Session for a recurring product and send the customer to its
url. PayPal approval and the return flow are handled by checkout.
Redirect the top-level browser to this URL. Do not put it in an iframe: PayPal approval navigates
away and must return to the hosted checkout before OurPay can finish confirmation.
Existing customers
The customer and organization payment-method APIs can list methods already saved through checkout.
Deleting a method is rejected while an active subscription still requires it.
The current PayPal-only customer portal does not provide a separate widget to replace a saved
method. Do not tell a customer that a new method was attached until a supported PayPal approval
flow completes and the resulting method appears in OurPay.
Test the full lifecycle
Use a PayPal sandbox Business account for the receiving REST app and a separate sandbox Personal
account as the buyer. Verify:
- Paid subscription approval creates one saved PayPal method and one paid initial order.
- A free trial creates a saved method without creating a paid order.
- Renewal charges the saved token once and advances the subscription.
- Duplicate Vault and capture webhooks do not create duplicate methods or orders.
- Revoked or deleted PayPal Vault tokens fail renewals visibly and enter the normal dunning path.
See Sandbox and Payment providers for the
required configuration and webhook events. 