PayPal (BYO)

Connect your existing PayPal Business account to accept payments via PayPal balance, PayPal Credit, and PayPal-processed cards.

When to use this

• You sell to international customers who prefer PayPal.
• You want PayPal balance as a payment option (cards alone aren't enough for some merchants).
• You already have an established PayPal Business account.

For Indonesian-only businesses, Xendit or Midtrans usually has better coverage. PayPal shines for cross-border and US/EU customers.

What you need

1. A PayPal Business account (not personal).
2. Client ID and Client Secret for the REST API (PayPal Developer dashboard → My Apps & Credentials).
3. (Optional) Webhook ID if you want to leverage PayPal's webhook signatures for additional verification.

Connecting

1. Settings → Payment methods → Add provider → PayPal.
2. Choose sandbox or live.
3. Paste client ID and client secret.
4. Connect. We OAuth our way in via PayPal's client credentials flow.

Configure PayPal webhooks:

• PayPal Developer Dashboard → Your app → Webhooks → Add webhook
• URL: https://api.plugipay.com/v1/inbound-webhooks/paypal/<your-workspace-id>
• Events: subscribe to all (we filter on our end)

Payment methods supported

Method	Status
PayPal balance	✅
Card (PayPal-processed)	✅
PayPal Credit	✅ in supported markets (US primarily)
Pay in 4 / Pay Later	✅ where PayPal offers it
Venmo	❌ (PayPal's Venmo isn't currently in our integration)

How it works

PayPal's checkout is a redirect flow:

1. Plugipay creates a PayPal order.
2. The customer is redirected to PayPal to authorize.
3. PayPal redirects back to Plugipay with confirmation.
4. Plugipay captures the order — this is when the money actually moves.

We hide all of this behind the same checkout session API. Your code is identical:

const session = await plugipay.checkoutSessions.create({
  amount: 25000,   // USD 250.00 (cents)
  currency: 'USD',
  description: 'Pro plan',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  paymentMethods: ['paypal'],  // optional - restrict to PayPal only
});

If you don't restrict paymentMethods, Plugipay shows the customer all enabled methods and they pick PayPal at the hosted checkout.

Currency

PayPal supports many currencies. Set currency per checkout session — we'll create the PayPal order in that currency. Settlement is in your PayPal account's primary currency (with PayPal's FX if there's a conversion).

For US customers, USD is the most common. For international, match the customer's likely currency to avoid surprise conversions.

Refunds

Refunds forward to PayPal's refund API. Most card-funded refunds are visible to the customer within minutes; PayPal-balance refunds are instant.

Disputes

PayPal handles disputes through its own dispute resolution center. Plugipay doesn't intermediate — you'll see disputes appear in your PayPal dashboard, and we display a banner on the affected payment in Plugipay so you can see the linkage.

If a dispute results in a chargeback, PayPal deducts from your balance and we sync the state to Plugipay.

Fees

PayPal's fee schedule applies (typically 3.49% + fixed for cross-border, lower for domestic). Plugipay charges a separate BYO platform fee. Both appear on the payment:

• fees.provider: PayPal's cut
• fees.platform: Plugipay's cut

Limits and quirks

• PayPal restricts certain merchants. If your business category isn't allowed on PayPal (regulated industries, adult content, certain digital goods), the connection will work but transactions will fail. Check PayPal's acceptable use policy before integrating.
• PayPal requires "Confirmed Shipping Address" for many transactions. If you sell digital goods, you can override this in PayPal's risk settings.
• Sandbox accounts behave differently — sandbox customers can simulate disputes via PayPal's dashboard. Useful for testing dispute handling.

Next

• Xendit (BYO) — for Indonesian payment methods.
• Midtrans (BYO) — the other Indonesian BYO option.
• Plugipay managed — bundle all the above without per-provider setup.