PayPal

Accept PayPal payments using a popup-based authentication flow.

View as Markdown

PaymentKit.js handles the PayPal flow through a secure popup window. Customers authenticate with PayPal without leaving your checkout page.

Setup

1<script src="https://unpkg.com/@payment-kit-js/vanilla/dist/cdn/paymentkit.min.js"></script>
2<script>
3 const paymentKit = PaymentKit.default({
4 environment: 'sandbox',
5 secureToken: 'aBcDeFgHiJkLmNoPqRsTuVwXyZ123456', // From your backend
6 paymentMethods: [PaymentKit.PaymentMethods.paypal]
7 });
8</script>

Submit payment

Unlike card payments, PayPal doesn’t need input elements. Submit directly when the customer clicks your PayPal button:

1document.getElementById('paypal-button').addEventListener('click', () => {
2 paymentKit.submit({
3 fields: {
4 customer_name: 'Jane Smith',
5 customer_email: 'jane@example.com',
6 customer_country: 'US',
7 customer_zip_code: '94102'
8 },
9 paymentMethod: 'paypal',
10 options: {
11 processorId: 'proc_paypal_abc123',
12 customerInfo: {
13 first_name: 'Jane',
14 last_name: 'Smith'
15 }
16 },
17 onSuccess: (result) => {
18 console.log('ID:', result.id);
19 console.log('Checkout Attempt ID:', result.checkoutAttemptId);
20 console.log('Checkout Session ID:', result.checkoutSessionId);
21 console.log('State:', result.state);
22 window.location.href = '/success';
23 },
24 onError: (errors) => {
25 console.error(errors);
26 }
27 });
28});

The popup must be triggered by a direct user action (button click) to avoid being blocked by popup blockers.

Options

OptionTypeRequiredDescription
processorIdstringYesYour PayPal processor ID
customerInfo.first_namestringYesCustomer’s first name
customerInfo.last_namestringYesCustomer’s last name

Error handling

PayPal errors are returned in the errors.paypal field as descriptive strings:

1onError: (errors) => {
2 if (errors.processor_id) {
3 // Missing processor ID
4 console.error(errors.processor_id); // "Processor ID is required"
5 } else if (errors.customer_name) {
6 // Missing customer name
7 console.error(errors.customer_name); // "Customer first and last name are required"
8 } else if (errors.paypal) {
9 // PayPal-specific errors
10 if (errors.paypal.includes('popup')) {
11 // Popup was blocked
12 alert('Please allow popups for this site');
13 } else if (errors.paypal.includes('closed by user')) {
14 // Customer closed popup without completing
15 } else if (errors.paypal.includes('Failed to check')) {
16 // Status polling failed
17 }
18 console.error(errors.paypal);
19 }
20}
Error FieldError MessageCause
processor_idProcessor ID is requiredMissing processorId in options
customer_nameCustomer first and last name are requiredMissing customerInfo.first_name or customerInfo.last_name
paypalFailed to open PayPal popup. Please allow popups for this site.Browser blocked the popup window
paypalPayPal popup closed by userCustomer closed the popup without completing payment
paypalFailed to check PayPal statusError while polling for payment completion
paypalPayPal checkout cancelledPayment was cancelled by the customer in PayPal
paypalPayPal checkout failedPayment failed on PayPal’s side
paypalPayPal checkout expiredPopup session expired (1 hour timeout)
paypalPolling error: {error}Network error during status polling
paypalPayPal checkout error: {error}General checkout error