---
updatedAt: 2026-09-17T11:57:45.000Z
---
Fetch the complete documentation index at: https://developer.pay.nl/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Create a session from your backend
In order to use a component of Pay.Parts in your frontend you need to initialize a session. A session is initialized by sending a POST request from your backend.
# Create a session from your backend
In order to use a component of Pay.Parts in your frontend you need to initialize a session. A session is initialized by sending a POST request from your backend.
# Base URL
The following URLs are available:
**Production**
`https://parts.pay.nl`
**Zero (Pre-Production)**
`https://zero-parts.pay.nl`
# Authentication
## Session Create (Basic Auth)
The `POST /v1/session/start` endpoint uses HTTP Basic Authentication with your Sales Location credentials:
```bash
Authorization: Basic
```
## Session Get (Basic Auth)
The `GET /v1/session/{sessionId}` endpoint uses Basic Authentication with your Sales Location credentials (same as create session):
```bash
Authorization: Basic
```
# Endpoints
## Create Session
Create a new payment session.
**Endpoint:** `POST /v1/session/start`
**Authentication:** Basic Auth (`SL-CODE:SECRET`)
### Minimum Required Request
```curl
curl -X POST 'https://parts.pay.nl/v1/session/start' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/json' \
-d '{
"returnUrl": "https://example.com/return",
"exchangeUrl": "https://example.com/exchange",
"amount": {
"value": 100,
"currency": "EUR"
}
}'
```
```curl
curl -X POST 'https://zero-parts.pay.nl/v1/session/start' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/json' \
-d '{
"returnUrl": "https://example.com/return",
"exchangeUrl": "https://example.com/exchange",
"amount": {
"value": 100,
"currency": "EUR"
}
}'
```
```curl
curl -X POST 'https://parts.pay.nl/v1/session/start' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/json' \
-d '{
"returnUrl": "https://example.com/return",
"exchangeUrl": "https://example.com/exchange",
"amount": { "value": 100, "currency": "EUR" },
"description": "Order 12345",
"reference": "REF-12345",
"expire": "2026-09-01T12:00:00Z",
"customer": {
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+31000000000",
"birthDate": "1990-01-01",
"gender": "M",
"locale": "nl_NL"
},
"order": {
"countryCode": "NL",
"deliveryDate": "2026-09-02",
"invoiceDate": "2026-09-01",
"deliveryAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL",
"region": "Noord-Holland"
},
"invoiceAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL"
},
"products": [
{
"id": "SKU-001",
"description": "Product one",
"type": "ARTICLE",
"price": { "value": 800, "currency": "EUR" },
"quantity": 1,
"vatPercentage": 21
},
{
"id": "SKU-002",
"description": "Product two",
"type": "SHIPPING",
"price": { "value": 200, "currency": "EUR" },
"quantity": 1,
"vatPercentage": 21
}
]
},
"integration": {
"checkoutUrl": "https://example.com/checkout/"
}
}'
```
```curl
curl -X POST 'https://zero-parts.pay.nl/v1/session/start' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/json' \
-d '{
"returnUrl": "https://example.com/return",
"exchangeUrl": "https://example.com/exchange",
"amount": { "value": 100, "currency": "EUR" },
"description": "Order 12345",
"reference": "REF-12345",
"expire": "2026-09-01T12:00:00Z",
"customer": {
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+31000000000",
"birthDate": "1990-01-01",
"gender": "M",
"locale": "nl_NL"
},
"order": {
"countryCode": "NL",
"deliveryDate": "2026-09-02",
"invoiceDate": "2026-09-01",
"deliveryAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL",
"region": "Noord-Holland"
},
"invoiceAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL"
},
"products": [
{
"id": "SKU-001",
"description": "Product one",
"type": "ARTICLE",
"price": { "value": 800, "currency": "EUR" },
"quantity": 1,
"vatPercentage": 21
},
{
"id": "SKU-002",
"description": "Product two",
"type": "SHIPPING",
"price": { "value": 200, "currency": "EUR" },
"quantity": 1,
"vatPercentage": 21
}
]
},
"integration": {
"checkoutUrl": "https://example.com/checkout/"
}
}'
```
### Successful Response
```json
{
"sessionId": "a3fc44c532784ce1b8ac2f2a003e1239",
"sessionToken": "st_eyJTZXNzaW9uSWQiOiJhM2ZjNDRjNTMyNzg0Y2UxYjhhYzJmMmEwMDNlMTIzOSIsIkNvbmZpZyI6eyJtZXJjaGFudE5hbWUiOiJDYW55b24gQmlrZXMiLCJhbW91bnQiOnsidmFsdWUiOjI5OTksImN1cnJlbmN5IjoiRVVSIiwiZm9ybWF0dGVkIjoiMjk5Ljk5In19fQ=="
}
```
## Get a session
Retrieve session details. Returns the same session token, amount, customer, and order that were used when creating the session.
**Endpoint:** `GET /v1/session/{sessionId}`
**Authentication:** Basic Auth (`SL-CODE:SECRET`)
```curl
curl -X GET "https://parts.pay.nl/v1/session/a3fc44c532784ce1b8ac2f2a003e1239" \
-H 'Authorization: Basic '
```
```curl
curl -X GET "https://zero-parts.pay.nl/v1/session/a3fc44c532784ce1b8ac2f2a003e1239" \
-H 'Authorization: Basic '
```
```json
{
"sessionId": "a3fc44c532784ce1b8ac2f2a003e1239",
"sessionToken": "st_eyJhbGciOiJIUzI1NiJ9...",
"amount": {
"value": 1000,
"currency": "EUR"
},
"customer": {
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+31000000000",
"birthDate": "1990-01-01",
"gender": "M",
"locale": "nl_NL"
},
"order": {
"countryCode": "NL",
"deliveryDate": "2026-09-02",
"invoiceDate": "2026-09-01",
"deliveryAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL",
"region": "Noord-Holland"
},
"invoiceAddress": {
"firstName": "John",
"lastName": "Doe",
"street": "Main Street",
"streetNumber": "1",
"streetNumberExtension": "A",
"zipCode": "1234AB",
"city": "Amsterdam",
"country": "NL",
"region": "Noord-Holland"
},
"products": [
{
"id": "SKU-001",
"description": "Product one",
"type": "ARTICLE",
"price": { "value": 800, "currency": "EUR" },
"quantity": 1,
"vatPercentage": 21
}
]
},
"orderStatus": {
"orderId": "50xxxxxxxxxx7f",
"status": "PENDING",
"amount": { "value": 1000, "currency": "EUR" },
"capturedAmount": { "value": 0, "currency": "EUR" },
"authorizedAmount": { "value": 1000, "currency": "EUR" },
"outstandingAmount": { "value": 1000, "currency": "EUR" },
"isFullyPaid": false,
"payments": [
{
"id": "11111111-1111-2222-3333-123412341234",
"paymentMethod": {
"id": 1
},
"amount": { "value": 1000, "currency": "EUR" },
"capturedAmount": { "value": 0, "currency": "EUR" },
"authorizedAmount": { "value": 1000, "currency": "EUR" },
"status": {
"code": 25,
"action": "AUTHORIZE"
}
}
]
}
}
```
> `orderStatus` is only present once the session has an order (after the first authenticate step); before that it's `null`.
## Update a session
Update the session amount and/or order (products) **before a payment order has been created**.
**Endpoint:** `PATCH /v1/session/{sessionId}`
**Authentication:** Authenticated against the session (typically invoked via the SDK's `checkout.updateSession()` after initialization).
This endpoint isn't yet available in Production.
```curl
curl -X PATCH "https://zero-parts.pay.nl/v1/session/a3fc44c532784ce1b8ac2f2a003e1239" \
-H 'Content-Type: application/json' \
-d '{
"amount": { "value": 8500, "currency": "EUR" },
"order": {
"products": [
{
"id": "SKU-001",
"description": "Product one",
"type": "ARTICLE",
"price": { "value": 8000, "currency": "EUR" },
"quantity": 2,
"vatPercentage": 21
}
]
}
}'
```
### Request fields
| 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`.
### Successful Response
```json
{
"sessionId": "a3fc44c532784ce1b8ac2f2a003e1239",
"amount": { "value": 8500, "currency": "EUR" },
"customer": { "email": "john@example.com" },
"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.