Integrate PayParts (Quickstart)

How it works (30 seconds)

1. Your backend calls POST /v1/session/start with the order amount and gets back a sessionToken.
2. Your frontend loads the PayParts SDK, initializes it with that sessionToken, and mounts the payment components (card form, wallets, method list, etc.).
3. Payment completes — the consumer finishes on the payment page, you confirm via the returnUrl / onSuccess event, and your backend is notified via the exchangeUrl webhook.

Consumer ──▶ Your Checkout (PayParts components)
                │
                ├─ POST /v1/session/start ──▶ PayParts backend  ──▶ sessionToken
                │
                └─ SDK init(sessionToken) ──▶ render + complete payment ✦
                                                   │
                            returnUrl / onSuccess ◀─┘
                            exchangeUrl webhook ──▶ your backend

1. Environments

PayParts has two environments. Use the matching one on backend and frontend.

2. Backend: create a session

Your backend creates the session before the checkout page loads. This is a simple authenticated REST call.

Authentication

POST /v1/session/start uses HTTP Basic auth with your Sales Location credentials:

Authorization: Basic <base64(sl-code:secret)>

Minimal request

curl -X POST 'https://parts.pay.nl/v1/session/start' \
  -H 'Authorization: Basic <base64(sl-code:secret)>' \
  -H 'Content-Type: application/json' \
  -d '{
    "returnUrl": "https://example.com/return",
    "exchangeUrl": "https://example.com/exchange",
    "amount": {
      "value": 1,
      "currency": "EUR"
    }
  }'

curl -X POST 'https://zero-parts.pay.nl/v1/session/start' \
  -H 'Authorization: Basic <base64(sl-code:secret)>' \
  -H 'Content-Type: application/json' \
  -d '{
    "returnUrl": "https://example.com/return",
    "exchangeUrl": "https://example.com/exchange",
    "amount": {
      "value": 1,
      "currency": "EUR"
    }
  }'

Successful response

{
  "sessionId": "a3fc44c532784ce1b8ac2f2a003e1239",
  "sessionToken": "st_..."
}

Take the sessionToken — you pass it to the SDK on the frontend. Never expose your Sales Location secret to the browser; keep this call on the backend.

3. Frontend: add the SDK

On your checkout page, load the SDK, initialize it with the sessionToken, and mount the components you want.

Load the SDK

<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 and mount components

const checkout = await window.PayPartsSDK.init({
  sessionToken: '<sessionToken from your backend>', // never store this in source
  apiUrl: 'https://parts.pay.nl',                   // match your environment
  country: 'NL',
  language: 'en',
});

// Mount the components where you want them on the page
const card = checkout.prepare('card-payments');        // card form
await card.bind('#payparts-card');

const express = checkout.prepare('checkout-buttons');  // Apple Pay / PayPal / Google Pay
await express.bind('#payparts-express');

const methods = checkout.prepare('methods');           // full payment method list
await methods.bind('#payparts-methods');

The component names are lowercase strings: 'card-payments', 'checkout-buttons', 'methods', 'giftcard', 'applepay', 'paypal', 'googlepay', 'click-to-pay-methods', 'user-optimized'.

4. Finish the payment

How the flow completes depends on the method:

• Redirect methods (e.g. iDEAL): the payer is sent to a payment page. Return them to your returnUrl when done, where you confirm the outcome.
• Inline methods (cards, wallets): confirm via the SDK onSuccess event.
• Your backend is always notified by the webhook sent to your exchangeUrl with the payment result.

A minimal event handler:

checkout.events = {
  onSuccess: (event) => {
    // payment succeeded — show confirmation / complete the order
    console.log('Order:', event.orderId);
    event.resolve();
  },
  onError: (event) => {
    console.error('Payment failed:', event.error, event.errors);
    event.resolve(); // allow retry
  },
};

See Handle events for the full event model.

5. Gotchas that break integrations

These are the most common reasons a first integration fails. Handle them up front:

Next steps

• Full session request (order + customer)
• All init options and components
• Express buttons (Apple Pay / PayPal / Google Pay)
• Events
• SDK API reference