The QrX Public API lets merchants create and manage pay-at-the-door transactions, products, returns and webhooks. Authenticate by exchanging your merchant channel API key for a short-lived access token via POST /api/v1/auth/token, then send it as a Bearer token.
Prefer clicking before coding? Our shared Postman workspace contains ready-made requests for every major flow in this reference, wired to the environment variables below. Use it to explore the API and validate your setup before you deploy a single line of integration code.
How to use it
1Open the shared workspace in Postman and select the QrX environment that ships with it (or create your own).
2Set your merchant channel API key in the QrX-MerchantChannel-API-Key variable.
3Run the Create access token request; the returned Bearer token authenticates all other requests.
4Fire any request in the collection: transactions, reference data, webhooks, products and returns are all preconfigured against https://api.qr-x.net.
Authentication
Create a merchant channel API key in your QrX portal, exchange it for a short-lived access token, and send that token as a Bearer header on every call.
1Create an API key per sales channel in Portal → Settings → Merchant channels.
2Exchange it for an access token via POST /api/v1/auth/token (valid for one hour).
3Call the API with the Authorization: Bearer header. Refresh the token when it expires.
QrX-MerchantChannel-API-Key
Merchant channel API key. Use this only to call /api/v1/auth/token.
Authorization: Bearer
Short-lived QrX access token returned by /api/v1/auth/token.
curl -X POST "https://api.qr-x.net/api/v1/auth/token" \
-H"QrX-MerchantChannel-API-Key: YOUR_MERCHANT_API_KEY"
Errors & rate limits
Errors use standard HTTP status codes with an application/problem+json body containing a machine-readable code and a human-readable message.
Rate limits are applied per merchant API key. When exceeded, QrX returns HTTP 429 with Retry-After and RateLimit-Reason headers; wait at least the indicated number of seconds before retrying.
Auth
1 Endpoints
Every integration starts here. Exchange your merchant channel API key for a short-lived Bearer token; every other endpoint requires it. Tokens expire after one hour, so build automatic refresh into your client.
Create access token
60/minMerchant API key
post/api/v1/auth/token
Exchanges a merchant channel API key for a short-lived bearer token. Use this token in the Authorization header for all other Public API calls.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X POST "https://api.qr-x.net/api/v1/auth/token" \
-H"QrX-MerchantChannel-API-Key: YOUR_MERCHANT_API_KEY"
Transactions
5 Endpoints
The heart of QrX. Create a transaction for every shipment that should be paid at the door: QrX generates the QR code, handles the payment session and reports the outcome. Follow the lifecycle from creation through shipping to payment, and mark transactions shipped or cancel them as fulfillment progresses.
Create transaction
300/minBearer token
post/api/v1/transactions
Creates a new QrX transaction and starts the payment provider process when a PSP is required.
Important: PSP processing is handled asynchronously in the background. A successful response from this endpoint means that the transaction was accepted by QrX and that the PSP process was started. It does not guarantee that the payment provider successfully created the payment session, payment link, or checkout transaction.
The PSP process can still fail after the API response has been returned, for example because of missing PSP configuration, invalid merchant credentials, missing required payment data, or a provider-side validation error.
If PSP creation fails, QrX marks the transaction as Cancelled and reports the final status through the configured webhook flow. Always listen to transaction webhooks and use the webhook status as the source of truth for the final transaction state.
Do not rely only on the immediate API response to decide whether a transaction is payable or ready for fulfillment. Always verify the latest transaction status before printing shipping labels, printing packing slips, shipping goods, or triggering downstream fulfillment.
Request bodyPublicCreateTransactionRequest
transactionTypeTransactionType
Specify what kind of transaction you want to create
One of:PaymentNoPaymentOtpOnlyDataOnly
amountnumber (double)
Total amount to collect from the customer. For Payment transactions this is the amount sent to the payment provider.
≥ 1
orderDetailsPublicOrderDetailsRequestrequired
parcelPublicParcelRequest
billingAddressPublicAddressRequest
localestringnullable
Optional locale used for customer-facing payment and communication content.
xpointsToUsenumber (double)
Optional QrX wallet or points amount to apply to the transaction.
≥ 0
testModeboolean
When true, the transaction is created in QrX test mode. PSP processing uses sandbox or test configuration where available, no real PSP payment or payout is created, and the transaction must not be treated as production fulfillment.
currencystringnullable
Three-letter ISO 4217 currency code for the transaction amount, for example EUR.
≥ 3 characters≤ 3 characters
expiresAtstring (date-time)nullable
Optional UTC date and time after which the payment or transaction should no longer be considered payable.
Returns the current transaction details for a transaction that belongs to the authenticated merchant channel. Use this call for lookup and reconciliation, but use webhooks as the primary source of truth for status changes.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/transactions/{transactionId}" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Get transaction status
1200/minBearer token
get/api/v1/transactions/{transactionId}/status
Returns the latest lightweight transaction status fields. Use this to verify a transaction before fulfillment when you need an on-demand check in addition to webhook processing.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/transactions/{transactionId}/status" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Mark transaction as shipped
300/minBearer token
post/api/v1/transactions/{transactionId}/ship
Marks an eligible transaction as shipped and stores the carrier tracking details supplied by your system. Only call this after you have verified that the transaction is valid for fulfillment.
Path parameters
transactionIdstringrequired
Request bodyPublicMarkShippedRequest
trackAndTraceNumberstringnullable
Carrier tracking number for the shipped transaction.
trackAndTraceUrlstringnullable
Carrier tracking URL that customers or merchants can use to follow the shipment.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
Cancels an eligible open transaction with a merchant-provided reason. Cancelled transactions are no longer valid for payment, label printing, packing slips, or fulfillment.
Path parameters
transactionIdstringrequired
Request bodyPublicCancelTransactionRequest
reasonstringrequired
Human-readable reason for cancelling the transaction.
≥ 1 characters
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X POST "https://api.qr-x.net/api/v1/transactions/{transactionId}/cancel" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H"Content-Type: application/json" \
-d '{
"reason": "Customer cancelled the order before shipment"
}'
Example request body
{
"reason": "Customer cancelled the order before shipment"
}
Webhooks
13 Endpoints
Know the moment something happens: a payment confirmed at the door, a transaction shipped, a return updated. Register webhook endpoints, choose event types, verify signed deliveries, inspect and redeliver failed ones, and rotate signing secrets without downtime. Webhooks are the source of truth for final transaction state.
List webhooks
1200/minBearer token
get/api/v1/webhooks
Returns configured webhooks for the authenticated merchant channel, including health and recent delivery state.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/webhooks" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Create webhook
300/minBearer token
post/api/v1/webhooks
Creates a webhook endpoint for transaction and order events. Webhooks are required for reliable status synchronization because payment and provider processing can complete or fail asynchronously.
Request bodyPublicWebhookUpsertRequest
namestringrequired
Internal name for this webhook endpoint.
≥ 1 characters≤ 120 characters
targetUrlstring (uri)required
Absolute HTTPS URL that receives webhook POST requests from QrX.
≥ 1 characters
eventTypesstring[]required
Event types this webhook should receive. Use the event types endpoint to retrieve supported values.
apiVersionstringnullable
Optional webhook API version. Leave empty to use the current default version.
isActiveboolean
Whether QrX should actively deliver events to this webhook endpoint.
xmininteger (int32)nullable
Optional optimistic concurrency token returned by existing webhook records.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/webhooks/{webhookId}" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Update webhook
300/minBearer token
patch/api/v1/webhooks/{webhookId}
Updates the configuration, target URL, event types, version, active state, or concurrency version for one webhook owned by the authenticated merchant channel.
Path parameters
webhookIdinteger (int32)required
Request bodyPublicWebhookUpsertRequest
namestringrequired
Internal name for this webhook endpoint.
≥ 1 characters≤ 120 characters
targetUrlstring (uri)required
Absolute HTTPS URL that receives webhook POST requests from QrX.
≥ 1 characters
eventTypesstring[]required
Event types this webhook should receive. Use the event types endpoint to retrieve supported values.
apiVersionstringnullable
Optional webhook API version. Leave empty to use the current default version.
isActiveboolean
Whether QrX should actively deliver events to this webhook endpoint.
xmininteger (int32)nullable
Optional optimistic concurrency token returned by existing webhook records.
Cancels pending retry attempts for a webhook delivery that should no longer be sent.
Path parameters
webhookIdinteger (int32)required
deliveryIdinteger (int64)required
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X POST "https://api.qr-x.net/api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/cancel" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Reference
5 Endpoints
The lookup data behind valid requests: supported carriers, countries, locales, sender addresses and shipping methods for your account. Fetch these once, cache them, and refresh periodically instead of hardcoding values.
List carriers
1200/minBearer token
get/api/v1/reference/carriers
Returns the carriers that can be referenced when creating transactions or shipments through the Public API.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/reference/carriers" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
List locales
1200/minBearer token
get/api/v1/reference/locales
Returns supported locale codes for localized payment pages, customer communication, and transaction content.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/reference/locales" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
List countries
1200/minBearer token
get/api/v1/reference/countries
Returns supported destination country codes and names for transaction and shipment creation.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/reference/countries" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
List shipping methods
1200/minBearer token
get/api/v1/reference/shipping-methods
Returns the shipping methods configured for the authenticated merchant channel. Use these codes in create transaction requests when you want QrX to create or prepare carrier labels.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/reference/shipping-methods" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
List sender addresses
1200/minBearer token
get/api/v1/reference/senders
Returns sender address references configured for the authenticated merchant channel. Use the sender code in parcel requests when a specific sender location should be used.
Responses
200OK
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/reference/senders" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Products
7 Endpoints
Maintain the product catalog your order lines reference: SKU, EAN, weight and customs data per product. Archive products you no longer sell; historical transactions keep working.
List products
1200/minBearer token
get/api/v1/products
Returns products available through the authenticated merchant channel, including pagination metadata for catalog synchronization.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X GET "https://api.qr-x.net/api/v1/products" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Create product
300/minBearer token
post/api/v1/products
Creates a product with optional variants, option groups, tags, images, pricing, and availability information for use in QrX ordering and catalog flows.
Request bodyPublicProductUpsertRequest
defaultLocalestringrequired
Default locale for the product content, for example en or nl.
≥ 2 characters≤ 10 characters
skustringrequired
Unique product SKU within the merchant channel.
≥ 1 characters≤ 128 characters
titlestringrequired
Product title shown in QrX catalog and ordering flows.
≥ 1 characters≤ 256 characters
unitstringnullable
Optional unit label, for example piece, box, or kg.
≥ 0 characters≤ 64 characters
currencystringnullable
Three-letter ISO 4217 currency code for product pricing.
≥ 3 characters≤ 3 characters
pricenumber (double)
Base product price including VAT unless your integration explicitly stores prices differently.
≥ 0
vatPercentnumber (double)nullable
VAT percentage applied to the product price.
≥ 0≤ 100
availableQuantityinteger (int64)
Available stock quantity for catalog and ordering flows.
≥ 0
descriptionstringnullable
Product description shown in catalog and ordering flows.
≥ 0 characters≤ 4000 characters
imageUrlsstring[]nullable
Public image URLs for the product gallery.
tagsstring[]nullable
Optional tags for product filtering, grouping, or synchronization.
429Too many requests. The response includes Retry-After and RateLimit-Reason headers.
curl -X POST "https://api.qr-x.net/api/v1/products/{productId}/unarchive" \
-H"Authorization: Bearer YOUR_ACCESS_TOKEN"
Returns
17 Endpoints
Run the full return lifecycle over the API: list and inspect return requests, approve or reject them, ask the consumer for more information, attach evidence and receipt facts, exchange messages, and record the final resolution.
List returns (cursor pagination, newest first). state filters on stored canonical states.