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><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: '###############YOUR-SESSION-TOKEN###############', // Your session token from v1/session/start
apiUrl: 'https://parts.pay.nl',
country: 'NL'
});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 configuration 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, DE |
| language | string | Language for the translations, possible values are nl, en, de, fr (and many more) |
| excludedMethods | array | Payment method tags to exclude from display |
| applePayOptions | applePayOptions | see applePayOptions |
| paypalOptions | paypalOptions | see paypalOptions |
| googlePayOptions | googlePayOptions | see googlePayOptions |
| creditCardOptions | creditCardOptions | see creditCardOptions |
| expressButtons | array | Which express buttons to render and in what order ('applepay', 'paypal', 'googlepay') |
| expressButtonsLayout | string | 'vertical' (default) or 'horizontal' |
| debugMode | boolean | Bypass amount-range filtering so methods outside their min/max amount are still shown (greyed, with min/max amounts) for testing |
| showDisabledPaymentMethods | boolean | Show disabled payment methods in the list (greyed out and unselectable) instead of hiding them |
| lastUsedEnabled | boolean | Remember / show the customer's last-used payment method |
| translations | Custom translations (see translations) | |
| customer | object | Payer details the SDK attaches to POST /v1/session/{id}/pay. Pass email, firstName, lastName, phone and addresses { shippingAddress, billingAddress } ({ street, streetNumber, streetNumberExtension, zipCode, city, country }). Note the /pay body fields are optional — PayParts builds the actual order from the session data, so make sure your backend creates the session with the full order and customer for order/redirect methods (e.g. iDEAL), otherwise /pay fails with 422 PAY-2880 requiredDataMissing. See SDK API reference. |
| paymentMethodOptions | object | Payment-method display options, e.g. the Pay By Bank flow (see paymentMethodOptions) |
| onSubmitTimeout | number | Timeout (ms) for the onSubmit handler gate (default 30000) |
customer option
customer optionPass the payer's details to init() so the SDK can attach them to POST /v1/session/{id}/pay and prefill the UI:
customer: {
email: string,
firstName: string,
lastName: string,
phone: string,
billingAddress?: { street, streetNumber, streetNumberExtension, zipCode, city, country },
shippingAddress?: { street, streetNumber, streetNumberExtension, zipCode, city, country }
}These /pay body fields are optional — PayParts builds the actual order (products, addresses, customer) from the session data your backend supplied at POST /v1/session/start. Still, for order/redirect methods (e.g. iDEAL) the session must be created with the full order and customer, otherwise /pay fails with 422 PAY-2880 requiredDataMissing.
Types package — pin it to your SDK versionUse the official types package
@paynl/payparts-typesfor the full, up-to-date config shapes (see Environments for the version). Pin it to the exact SDK version you load so the types always match the SDK on your page.The
/payrequest the SDK builds from these options is documented in the SDK API reference.
Showing disabled payment methods
debugMode and showDisabledPaymentMethods are two separate options that both affect the payment methods list, but for different reasons:
debugModebypasses the min/max amount filter. Payment methods outside their valid amount range are kept in the list, greyed out, and displayed with their min/max amounts. This is intended for testing and does not reveal methods that have been disabled by the service provider.showDisabledPaymentMethodskeeps disabled payment methods in the list, greyed out and unselectable, instead of hiding them. The disabled reason is intentionally not shown to the shopper; to read it, use the session config (paymentMethods[].disabledReason). Defaults tofalse.
const checkout = await window.PayPartsSDK.init({
sessionToken: '###############YOUR-SESSION-TOKEN###############',
showDisabledPaymentMethods: true,
});paymentMethodOptions
The paymentMethodOptions.payByBankFlow option controls which of the bank-selection
payment methods are shown based on country. It adjusts the following Pay.nl methods:
| Method | ID |
|---|---|
| Pay by Bank | 2970 |
| MetJeBank | 5358 |
| iDEAL | 10 |
| Option | Type | Description |
|---|---|---|
| payByBankFlow | string | 'default' or 'metJeBank'. When unset, all methods are shown as configured in the session and no hiding is applied. |
'default'- NL – shows MetJeBank (which provides its own iDEAL) and iDEAL; hides Pay by Bank.
- Other countries – shows Pay by Bank and iDEAL; hides MetJeBank.
'metJeBank'- NL only – shows only MetJeBank, hiding both iDEAL and Pay by Bank.
- Other countries – no methods are hidden; the session configuration is used unchanged.
Note: MetJeBank renders its bank picker as a native <select>, with the selected value drawn by the SDK's own overlay. The native open list is styled to stay legible and follow the browser's light/dark scheme on every platform (including Windows Chrome/Edge, where a transparent option colour would otherwise show as solid white).
const checkout = await window.PayPartsSDK.init({
sessionToken: '###############YOUR-SESSION-TOKEN###############',
apiUrl: 'https://parts.pay.nl',
country: 'NL',
paymentMethodOptions: {
payByBankFlow: 'default', // or 'metJeBank'
},
});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;
}| 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 |
partnerMerchantId | string | PayPal Partner merchant Id onboarded via referral flow |
country | string | Force the SDK to init for a specific country |
type | string | The button type to display |
testMode | boolean | Create a test transaction instead of a real transaction |
buttonStyle | object | The style of the displayed button |
onButtonClick | function | Custom callback when PayPal button is clicked |
Note: buttonStyles, enableFunding, disableFunding and the extended buttonStyle fields
(label, tagline, height, borderRadius, disableMaxWidth, plus the silver color and sharp
shape) are not yet available in Production — see the Zero tab.
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;
}| Option | Type | Description |
|---|---|---|
clientId | string | PayPal client ID |
partnerMerchantId | string | PayPal Partner merchant Id onboarded via referral flow |
country | string | Force the SDK to init for a specific country |
type | string | The button type to display |
testMode | boolean | Create a test transaction instead of a real transaction |
buttonStyle | object | Base style applied to every PayPal button |
buttonStyles | object | Per-funding-source style overrides (keyed by source) |
enableFunding | array | Additional funding sources to show (e.g. ['venmo']) |
disableFunding | array | Funding sources to hide (e.g. ['card']) |
onButtonClick | function | Custom 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. Applied as the base style to every
* rendered button (PayPal and all eligible funding sources) unless
* overridden by `buttonStyles`.
*
* Note: when a `partnerMerchantId` is set, PayPal forces the branded
* "Pay with PayPal" label. Setting a `label` omits `merchant-id` from
* the SDK script so the custom label takes effect.
*/
buttonStyle?: {
color?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
shape?: 'rect' | 'pill' | 'sharp';
label?: 'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment' | 'subscribe' | 'donate';
layout?: 'vertical' | 'horizontal';
tagline?: boolean;
height?: number;
borderRadius?: number;
disableMaxWidth?: boolean;
};
/**
* Per-funding-source style overrides, keyed by funding source id
* (e.g. 'paypal', 'paylater', 'venmo', 'card'). Each value is merged
* on top of `buttonStyle` for that button. Funding sources without an
* entry use `buttonStyle` (or PayPal defaults).
*/
buttonStyles?: Record<
string,
{
color?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
shape?: 'rect' | 'pill' | 'sharp';
label?: 'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment' | 'subscribe' | 'donate';
layout?: 'vertical' | 'horizontal';
tagline?: boolean;
height?: number;
borderRadius?: number;
disableMaxWidth?: boolean;
}
>;
/**
* Additional funding sources to make available (e.g. 'venmo', 'card').
* PayPal is always enabled. Pay Later is enabled by default (remove it via `disableFunding`).
*/
enableFunding?: string[];
/**
* Funding sources that should not be shown as buttons (e.g. 'card', 'venmo').
*/
disableFunding?: string[];
/**
* Custom callback when PayPal button is clicked
*/
onButtonClick?: () => void;
}googlePayOptions
| Option | Type | Description |
|---|---|---|
buttonColor | string | Button color: 'default', 'black', 'white' (default: 'black') |
buttonType | string | Button label: 'book', 'buy', 'checkout', 'donate', 'order', 'pay', 'plain', 'subscribe' (default: 'plain') |
buttonRadius | number | Button corner radius in px (default: 8) |
buttonSizeMode | string | 'static' or 'fill' (default: 'fill') |
interface GooglePayOptions {
/** The color of the Google Pay button. */
buttonColor?: 'default' | 'black' | 'white';
/** The type of Google Pay button to render. */
buttonType?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe';
/** The corner radius of the button, in pixels. */
buttonRadius?: number;
/** How the button is sized within its container. */
buttonSizeMode?: 'static' | 'fill';
}| Option | Type | Description |
|---|---|---|
buttonColor | string | Button color: 'default', 'black', 'white' (default: 'black') |
buttonType | string | Button label: 'book', 'buy', 'checkout', 'donate', 'order', 'pay', 'plain', 'subscribe' (default: 'plain') |
buttonRadius | number | Button corner radius in px (default: 8) |
buttonSizeMode | string | 'static' or 'fill' (default: 'fill') |
interface GooglePayOptions {
/** The color of the Google Pay button. */
buttonColor?: 'default' | 'black' | 'white';
/** The type of Google Pay button to render. */
buttonType?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe';
/** The corner radius of the button, in pixels. */
buttonRadius?: number;
/** How the button is sized within its container. */
buttonSizeMode?: 'static' | 'fill';
}creditCardOptions
| Option | Type | Description |
|---|---|---|
hideSubmitButton | boolean | Hides the pay button inside the form; use PaymentComponent.submit() instead |
onReadyChange | (isReady) => void | Called 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;
}| Option | Type | Description |
|---|---|---|
initialView | 'ClickToPay' | 'CreditCard' | Which view shows first when Click to Pay is available ('ClickToPay' = SRC flow first, default; 'CreditCard' = manual form first) |
hideSubmitButton | boolean | Hides the pay button inside the form; use PaymentComponent.submit() instead |
hideCardHolderName | boolean | Hides the cardholder name field (forces cardHolderNameRequired off) |
cardHolderNameRequired | boolean | Whether the cardholder name field is required (default true) |
defaultCardHolderName | string | Default name used when field is empty/hidden (falls back to "Pay") |
onReadyChange | (isReady) => void | Called when the form's readiness changes (enable/disable your own pay button) |
interface CreditCardOptions {
/** Which view to show first when Click to Pay is available:
* "ClickToPay" shows the Click to Pay SRC flow first (default),
* "CreditCard" shows the manual card form first. */
initialView?: 'ClickToPay' | 'CreditCard';
/** Hides the pay button rendered inside the credit card form. */
hideSubmitButton?: boolean;
/** Hides the cardholder name field from the credit card form. */
hideCardHolderName?: boolean;
/** Whether the cardholder name field is required. Defaults to true. */
cardHolderNameRequired?: boolean;
/** Default cardholder name used when the field is empty or hidden. */
defaultCardHolderName?: string;
/** 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:
| 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 |
| methods | Full payment method list from the payment methods that are enabled on the service. The same as our Hosted Checkout. |
| giftcard | Component to accept a variety of giftcards on the checkout page |
| click-to-pay-methods | Click-to-Pay methods list |
| user-optimized | User 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');
}async function initPayment(sessionToken: string) {
const checkout = await window.PayPartsSDK.init({
sessionToken: sessionToken,
apiUrl: 'https://zero-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.
const updated = await checkout.updateSession({
amount: { value: 8500, currency: 'EUR' },
order: {
products: [
{
id: 'SKU-001',
description: 'Product one',
type: 'ARTICLE',
price: { value: 8000, currency: 'EUR' },
quantity: 2,
vatPercentage: 21
}
]
}
});
console.log(updated.sessionId, updated.amount, updated.customer, updated.order);| Field | Type | Description |
|---|---|---|
amount | object | Required. { value, currency } |
amount.value | long | Amount in cents, must be greater than 0 |
amount.currency | string | 3-letter ISO currency code (default EUR) |
order.products | array | Order line items |
Each product supports id, description, type, price ({ value, currency }), quantity and vatPercentage.
// Response
{
"sessionId": "###############YOUR-SESSION-ID###############",
"amount": { "value": 8500, "currency": "EUR" },
"customer": { "email": "[email protected]" },
"order": { "products": [ { "id": "SKU-001", "quantity": 2 } ] }
}Note: only amount and order.products are updated. All other session data (description, reference, expire, returnUrl, exchangeUrl, customer, integration) is preserved from the original session.
The session cannot be updated once a payment order has been created (error PAY-4010), and expired sessions are also rejected.
Updated 26 days ago