Prepare your frontend

First of all include the SDK on your website:

<script type="module" src="https://zero-parts.pay.nl/sdk/payparts-sdk.js"></script>

Initialize the SDK

In order to use the components you need to initialize the SDK using your sessionToken from the session API:

const checkout = await window.PayPartsSDK.init({
  sessionToken: 'st_eyJTZXNzaW9uSWQiOiI5YTg3ODFk....', // Your session token from v1/session/start
  apiUrl: 'https://zero-parts.pay.nl'
  country: 'NL'

});

The following configuration options are available when you want to initialize the SDK

Generic configration options

Option	Type	Description
sessionToken	string	The session token from your backend
apiUrl	string	The PayParts API URL (defaults to current origin)
country	string	The country for payment method sequencing, possible values are `DEFAULT`, `NL`, `BE`
language	string	Language for the translations, possible values are `nl`,`en`,`de`, `fr`
excludedMethods	array	Payment method tags to exclude from display
applePayOptions	applePayOptions	see applePayOptions
paypalOptions	paypalOptions	see paypalOptions
debugMode	boolean	Enabled debug mode to show disabled payment methods
translations

applePayOptions

Option	Type	Description
shippingMethods	shippingType	Custom shipping methods for Apple Pay
requiredBillingContactFields	array	Required billing contact fields
requiredShippingContactFields	array	Required shipping contact fields
lineItems		Custom line items
total		Total configuration

interface ApplePayOptions {
  /** Custom shipping methods for Apple Pay */
  shippingMethods?: ApplePayShippingMethod[];

  /** Required billing contact fields */
  requiredBillingContactFields?: string[];

  /** Required shipping contact fields */
  requiredShippingContactFields?: string[];

  /** Custom line items */
  lineItems?: ApplePayLineItem[];

  /** Total configuration */
  total?: {
    label: string;
    type?: 'final' | 'pending';
  };

  /** Shipping type */
  shippingType?: 'shipping' | 'delivery' | 'store' | 'service';

  /** Callback when shipping method is selected */
  onShippingMethodSelected?: (method: ApplePayShippingMethod) => ApplePayShippingMethodUpdate;

  /** Callback when shipping contact is selected */
  onShippingContactSelected?: (contact: ApplePayShippingContact) => ApplePayShippingContactUpdate;

  /** Callback when payment method is selected */
  onPaymentMethodSelected?: (method: ApplePayPaymentMethod) => ApplePayPaymentMethodUpdate;
}

paypalOptions

Option	Type	Description
clientId	string	PayPal client ID
buttonStyle
onButtonClick

interface PayPalOptions {
  /** PayPal client ID */
  clientId?: string;

  /** PayPal button style */
  buttonStyle?: {
    color?: 'gold' | 'blue' | 'white' | 'black';
    shape?: 'rect' | 'pill';
    size?: 'small' | 'medium' | 'large';
    layout?: 'vertical' | 'horizontal';
  };

  /** Custom callback when PayPal button is clicked */
  onButtonClick?: () => void;
}

Create and mount a component

In your front-end you need to add these tags where you want the components to appear:

<!-- Express checkout buttons (Apple Pay, Google Pay) -->
<div id="checkout-buttons"></div>

<!-- Alternative payment methods list -->
<div id="methods"></div>

<!-- Credit card payment form -->
<div id="card-payments"></div>

<!-- Giftcard form -->
<div id="giftcard"></div>

The following components are available:

Component	What it is
card-payments	Component to enter the credit card details (name, card number, expiry date and CVC)
applePay	Component to add the Apple Pay wallet button
googlePay [Alpha]	Component to add the Google Pay wallet button
paypal [Alpha]	Component to add the PayPal wallet button
checkout-buttons [Alpha]	Component that combines the Apple Pay, PayPal and Google Pay buttons
method	Full payment method list from the payment methods that are enabled on the service. The same as our Hosted Checkout.

interface PayPalOptions {
  /** PayPal client ID */
  clientId?: string;

  /** PayPal button style */
  buttonStyle?: {
    color?: 'gold' | 'blue' | 'white' | 'black';
    shape?: 'rect' | 'pill';
    size?: 'small' | 'medium' | 'large';
    layout?: 'vertical' | 'horizontal';
  };

  /** Custom callback when PayPal button is clicked */
  onButtonClick?: () => void;
}

Full Integration Example

import type {
  Checkout,
  CheckoutEventHandlers,
  CheckoutReadyEvent,
  PaymentSubmitEvent,
  PaymentErrorEvent,
  PaymentSuccessEvent,
  InitOptions,
  InfoUpdatedEvent,
  ShippingUpdatedEvent
} from '@payparts/sdk';

async function initPayment(sessionToken: string) {
  // Initialize the SDK
  const checkout: Checkout = await window.PayPartsSDK.init({
    sessionToken: sessionToken,
    apiUrl: 'https://zero-parts.pay.nl',
    language: 'nl',
    country: 'NL',
    excludedMethods: ['PG_2', 'PG_4'], // Exclude specific payment methods
    debugMode: false
  } as InitOptions);

  // Set up event handlers
  checkout.events = {
    onReady: (event: CheckoutReadyEvent) => {
      console.log('Checkout ready with config:', event.config);
    },
    onSubmit: (event: PaymentSubmitEvent) => {
      console.log('Payment submitted:', event.method, event.details);
      // Perform async merchant logic (e.g., create internal order)
      // Then resolve to continue with payment
      event.resolve();
    },
    onSuccess: (event: PaymentSuccessEvent) => {
      console.log('Payment success:', event.orderId);
      console.log('Return URL:', event.returnUrl);
      console.log('3DS data:', event.threeDs);
      console.log('Transaction:', event.transaction);
      event.resolve();
    },
    onError: (event: PaymentErrorEvent) => {
      console.error('Payment error:', event.error);
      console.error('Error ID:', event.errorId);
      console.error('Result:', event.result);
      console.error('Field errors:', event.errors);
      event.resolve();
    },
    onInfoUpdated: (event: InfoUpdatedEvent) => {
      console.log('Info updated:', event.data);
    },
    onShippingUpdated: (event: ShippingUpdatedEvent) => {
      console.log('Shipping updated:', event.data);
    }
  };

  // Mount Credit Card component
  const cardComponent = checkout.prepare('card-payments');
  await cardComponent.bind('#card-section');

  // Mount Express buttons (Apple Pay, Google Pay)
  const expressComponent = checkout.prepare('checkout-buttons');
  await expressComponent.bind('#express-section');

  // Mount Payment Methods list
  const methodsComponent = checkout.prepare('methods');
  await methodsComponent.bind('#methods-section');
}

Dynamic Configuration Updates

You can update the SDK configuration after initialization:

// Update language
checkout.updateConfig({ language: 'en' } as Partial<CheckoutConfig>);

// Update country for payment method sequencing
checkout.updateConfig({ checkoutCountry: 'BE' } as Partial<CheckoutConfig>);

// Update excluded methods
checkout.updateConfig({ excludedMethods: ['PM_10', 'PM_11'] } as Partial<CheckoutConfig>);

// Update Apple Pay configuration
checkout.updateConfig({
  applePayOptions: {
    requiredBillingContactFields: ['postalAddress', 'name'],
    requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'],
    shippingType: 'shipping'
  }
} as Partial<CheckoutConfig>);

// Toggle debug mode
checkout.updateConfig({ debugMode: true } as Partial<CheckoutConfig>);

// Get current config
const config = checkout.getConfig();