Documentation
Knowledge baseStatusServices & PricingContact

Add components to your frontend

Prepare your frontend

First of all include the SDK on your website:

<script type="module" src="https://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://parts.pay.nl',
  country: 'NL'
});

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

Generic configuration options

OptionTypeDescription
sessionTokenstringThe session token from your backend
apiUrlstringThe PayParts API URL (defaults to current origin)
countrystringThe country for payment method sequencing, possible values are DEFAULT, NL, BE, DE
languagestringLanguage for the translations, possible values are nl, en, de, fr (and many more)
excludedMethodsarrayPayment method tags to exclude from display
applePayOptionsapplePayOptionssee applePayOptions
paypalOptionspaypalOptionssee paypalOptions
creditCardOptionscreditCardOptionssee creditCardOptions
expressButtonsarrayWhich express buttons to render and in what order ('applepay', 'paypal', 'googlepay')
expressButtonsLayoutstring'vertical' (default) or 'horizontal'
debugModebooleanEnabled debug mode to show disabled payment methods
lastUsedEnabledbooleanRemember / show the customer's last-used payment method
translationsCustom translations (see translations)
customerCustomer information
onSubmitTimeoutnumberTimeout (ms) for the onSubmit handler gate (default 30000)
applePayOptions
OptionTypeDescription
shippingMethodsshippingTypeCustom shipping methods for Apple Pay
requiredBillingContactFieldsarrayRequired billing contact fields
requiredShippingContactFieldsarrayRequired shipping contact fields
lineItemsCustom line items
totalTotal 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
OptionTypeDescription
clientIdstringPayPal client ID
partnerMerchantIdstringPayPal Partner merchant Id onboarded via referral flow
countrystringForce the SDK to init for a specific country
typestringThe button type to display
testModebooleanCreate a test transaction instead of a real transaction
buttonStyleobjectThe style of the displayed button
onButtonClickfunctionCustom callback when PayPal button is clicked
interface PayPalOptions {
  /** PayPal Client Id */
  clientId?: string;
  /**
   * PayPal Partner merchant Id
   */
  partnerMerchantId?: string;
  /**
   * The country the PayPal SDK will use to init, Eg. 'NL', 'DE', etc
   */
  country?: string;
  /**
   * Which PayPal buttons to render.
   * 'default' (default) - a single PayPal button
   * 'funding' - a button per eligible PayPal funding source (e.g. PayPal, Pay Later, cards)
   */
  type?: 'default' | 'funding';
  /**
   * Test mode - creates the order as a test transaction.
   * Currently only supported for PayPal.
   */
  testMode?: boolean;
  /**
   * PayPal button style options
   */
  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;
}
creditCardOptions
OptionTypeDescription
hideSubmitButtonbooleanHides the pay button inside the form; use PaymentComponent.submit() instead
onReadyChange(isReady) => voidCalled when the form's readiness changes (enable/disable your own pay button)
interface CreditCardOptions {
  /** Hides the pay button rendered inside the credit card form. */
  hideSubmitButton?: boolean;

  /** Called when the credit card form's readiness changes. */
  onReadyChange?: (isReady: boolean) => 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, PayPal, 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:

ComponentWhat it is
card-paymentsComponent to enter the credit card details (name, card number, expiry date and CVC)
applePayComponent 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
methodsFull payment method list from the payment methods that are enabled on the service. The same as our Hosted Checkout.
giftcardComponent to accept a variety of giftcards on the checkout page
click-to-pay-methodsClick-to-Pay methods list
user-optimizedUser optimized flow showcasing the last-used payment method for that user

Full Integration Example

async function initPayment(sessionToken: string) {
  const checkout = await window.PayPartsSDK.init({
    sessionToken: sessionToken,
    apiUrl: 'https://parts.pay.nl',
    language: 'nl',
    country: 'NL',
    excludedMethods: ['PM_10', 'PM_11'], // Exclude specific payment methods
    debugMode: false
  });

  checkout.events = {
    onReady: (event) => {
      console.log('Checkout ready with config:', event.config);
    },
    onSubmit: (event) => {
      console.log('Payment submitted:', event.method, event.details);
      event.resolve();
    },
    onSuccess: (event) => {
      console.log('Payment success:', event.orderId);
      console.log('Return URL:', event.returnUrl);
      event.resolve();
    },
    onError: (event) => {
      console.error('Payment error:', event.error);
      event.resolve();
    }
  };

  const cardComponent = checkout.prepare('card-payments');
  await cardComponent.bind('#card-section');

  const expressComponent = checkout.prepare('checkout-buttons');
  await expressComponent.bind('#express-section');

  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' });

// Update country for payment method sequencing
checkout.updateConfig({ country: 'BE' });

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

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

// Toggle debug mode
checkout.updateConfig({ debugMode: true });

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

Update the session

You can update the session amount and/or order (products) before a payment order has been created, for example when the cart contents change on the checkout page.

This section isn't yet available in Production.

Updated 14 days ago

Did this page help you?