Skip to main content

Get Started as a Fulfilment Company (API)

H
Written by Hayko

Get Started as a Fulfilment Company (API)

This guide is for fulfilment companies (3PLs) that pack and ship for several webshops and want to offer those webshops digital Payment on Delivery, while keeping their own warehouse management system (WMS). Your WMS keeps receiving orders as it does today. For Payment on Delivery orders it asks QrX for the carrier label and the QrX payment label through the QrX Public API. At the door the shopper scans the QrX QR code and pays through the webshop's own payment provider. QrX never holds the money, and it never passes through your company.

In PortalX this is the setup path I am a fulfilment company and connect my own WMS via the API in the Get Started guide (Settings > Business > Get started).

Choose Your Account Model

QrX works with sales channels (merchant channels). Every channel has its own payment provider, API key, branding and default carrier. There are two ways to set up your clients:

  • You manage the clients (most common): your company has one QrX account with one merchant channel per client webshop. You connect each client's own payment provider to that client's channel, so door payments settle directly to the client. You get one QrX invoice for all clients.

  • The clients have their own QrX account: each webshop signs up itself, connects its payment provider and gives your company access with Partner Access (Settings > Business > Partner Access, scope Reseller operations or Carrier operations). Your WMS then uses the API key of the client's channel, or you connect through QrX Connect (see "QrX Connect: Connecting Your Platform With OAuth").

Agree with QrX which model you use before your first client goes live. Partner fees for fulfilment companies are agreed per partnership; see "Partners and How to Partner With QrX".

1. Set Up Your Company

  1. Company details. QrX keeps the company name, address and VAT or Chamber of Commerce number from your signup. If something is missing or changed, click Ask QrX in the step and QrX completes it for you. The step ticks when all details are known.

  2. Warehouse sender address with a short code for API calls: Settings > Operations > Addresses.

  3. Team: invite your warehouse and IT colleagues in Settings > Team & Access > Users, and give them roles in Roles & Permissions.

2. Add Your Clients

  1. One channel per client webshop: Settings > Business > Merchant Channels. Use the client's shop name so shoppers recognise it on the payment page.

  2. Connect each client's payment provider in the channel's Payments tab (Stripe, Mollie or MultiSafePay). The client completes the provider onboarding with their own company details.

  3. Brand per client: logo and colours on the channel, a Track and Trace template (Settings > Operations > Track & Trace) and message templates, so shoppers see the webshop, not the warehouse.

3. Connect Carriers and Printing

  1. Carriers: Settings > Operations > Shipping Providers. Use your own carrier contracts or the QrX UPS Payment on Delivery account. Link an account to all channels or to one client channel.

  2. Label format: choose PDF or ZPL and, for UPS, Standard (carrier label plus QrX payment label) or Extended (one combined label). Print the complete set for every Payment on Delivery parcel.

  3. If your WMS prints itself, it uses the labels returned by the API. Otherwise connect PrintNode in Settings > Preferences > Printing.

4. Connect Your WMS

  1. API key per client channel: Merchant Channels, open the channel, Settings tab, Regenerate API Key. Store keys encrypted on your server, one per client.

  2. Token: POST /api/v1/auth/token with the header QrX-MerchantChannel-API-Key.

  3. Look up codes with /api/v1/reference/shipping-methods and /api/v1/reference/senders. Never hard-code ids from another client.

  4. Create the transaction with its label in one call: POST /api/v1/transactions with type Payment for Payment on Delivery, or No payment for prepaid orders, plus a parcel block with CreateCarrierLabel. Save the returned transaction id and labels before you report the parcel as packed, so a retry never buys a second label.

  5. Webhooks: Settings > Advanced > Webhooks. Subscribe to transaction paid, cancelled and shipment events, per channel or for all channels. Verify the X-QrX-Signature header.

  6. Test end to end in test mode for each client before going live: order in, label printed, test payment at the door, webhook received.

5. Go Live Per Client

  1. Ask QrX to activate live mode (Chat with QrX in the guide).

  2. Switch one client at a time, and keep the old flow for that client until the first live door payments are confirmed.

Good to Know

  • A cancelled transaction can no longer be paid, labelled or fulfilled. Cancel in QrX when the webshop cancels.

  • HTTP 201 on create is not proof of payment. Wait for the paid webhook.

  • Your partner fee is agreed in your partner agreement; there is no universal published rate.

  • Stock and picking stay in your own WMS in this path. Want to run your warehouse in QrX instead? See "Get Started as a Fulfilment Company on the QrX WMS".

When to Contact Our Support Team

Contact QrX to agree your account model and partner terms, to certify your label output and printer, when a client's payment provider onboarding is stuck, or when webhooks keep failing.

Related Articles
Did this answer your question?