SDK API Reference

This page provides a concise reference for the PayParts SDK (TypeScript) public API. It covers the newer init() -> prepare() -> bind() flow. See Add components to your frontend for guidance, and Handle events for the event model.

PayPartsSDK

The global object exposed as window.PayPartsSDK (also the named export PayParts).

Checkout

The object returned by PayPartsSDK.init().

PaymentComponent

Returned by checkout.prepare(methodOrSection).

reset() and Click to Pay recognition

When called on a card component with Click to Pay enabled, reset() provides a new-user experience. Click to Pay remembers a returning shopper via a recognition binding held by the Visa / Mastercard SRC network (server-side) — not an email. reset():

1. Calls unbindAppInstance against the SRC network with the stored idToken, removing the device/app-instance recognition binding.
2. Clears the locally stored recognition tokens, then re-mounts the component.
3. On the next mount the shopper is treated as unrecognized and prompted for their identity instead of having their cards silently loaded.

If Click to Pay is not enabled on the component, reset() still clears any stale stored recognition tokens so a later mount starts fresh.

SubmitResult

Returned by PaymentComponent.submit().

type SubmitResult =
  | { status: 'success'; orderId: string; returnUrl: string }
  | { status: 'validation_failed' }
  | { status: 'error'; message: string; errorTag?: string }
  | { status: 'not_ready' };

Async submit (onSubmit)

The onSubmit handler supports asynchronous logic. When the user submits payment, the SDK waits (up to onSubmitTimeout, default 30000 ms) for the handler to call event.resolve() before continuing with the payment.

This lets you run other async work first — for example creating an order on a different platform/ERP, freezing stock, or validating inventory — and only continue once it has completed:

onSubmit: async (event) => {
  // Create the order on another platform first...
  await myPlatformApi.createOrder({ items, customer });
  // ...and only then continue with the PayParts payment
  event.resolve();
}

• Call event.resolve() to continue with the payment.
• Call event.reject(error) to cancel/abort the payment (e.g. if the external order creation fails).
• See Handle events for the full onSubmit example.

The pay call (POST /v1/session/{id}/pay)

When the payer confirms a redirect/order-based method (such as iDEAL), the SDK calls:

POST /v1/session/{sessionId}/pay
Content-Type: application/json

with a body such as:

{
  "methodId": 10,
  "customer": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+31000000000"
  }
}

Important details:

• amount is NOT required in /pay — it already exists on the session.
• methodId is required. iDEAL (10) is a redirect method and needs no issuer; only bank-selection methods (MetjeBank 5358, PayByBank 2970) require one via input.issuerId / subMethodId.
• customer and order in the body are optional — the SDK sends them if a customer was passed to init(), but PayParts builds the actual order from the session data.
• The order line items come from the session, not /pay: the products/amount are created server-side from the data you supplied in POST /v1/session/start. This is why the session must contain the full order + customer for order-based methods (see Create a session from your backend).

Example response (HTTP 200)

{
  "request": { "result": "1" },
  "data": {
    "orderId": "50xxxxxxxxxxxxxx",
    "returnUrl": "https://checkout-zero.pay.nl/to/payment/..."
  }
}

The data.returnUrl is where the payer should be sent (or directly navigated to) to complete their payment / bank selection. Use it to redirect the shopper from your checkout.

Failures worth knowing

• 422 — validation problems (e.g. a zero-priced price.value: 0 line, or a reference mismatch).
• 422 PAY-2880 requiredDataMissing — the session is missing required order/customer data. Add the full order and customer when creating the session.
• 422 PAY-1422 reference: Deze waarde is niet geldig. — the session's reference contains characters Pay rejects server-side (commonly _, e.g. a cart_... identifier). Strip them or use a plain order number. See the reference format note in Create a session from your backend.
• 410 Gone — the session has expired / is no longer available. Create a fresh session or set a longer expire.

Events

Event handlers are attached via checkout.events. Full list and event payloads: Handle events.