Developer Reference

IPAY API · v0.91.3

Every endpoint lives under https://last-mile-hub-5.preview.emergentagent.com · production target: https://api.ipay.global (DNS pending). Authentication: JWT bearer (7-day TTL). Complete machine-readable spec at https://portal.ipay.global/api/openapi.json · interactive Swagger UI · ReDoc.

827 live endpoints across 46 domains — auto-generated, always in sync.

Download Postman collection Browse help center →

Curated quickstart groups

Authentication

POST/api/auth/registerCreate a new merchant / operator account.

POST/api/auth/loginReturns JWT token + user payload.

GET/api/auth/meCurrent user from JWT.

Orders

Create manual or bulk orders, fetch detail, kick off IPAY payment session.

GET/api/ordersList orders for the current merchant (paginated).

POST/api/ordersCreate a single order. Body: customer + items + carrier_code + ipay_flag.

POST/api/orders/uploadBulk-upload CSV / XLSX with column auto-mapping.

POST/api/orders/{id}/create-sessionGenerate the 18-digit IPAY reference + pay URL + QR.

GET/api/orders/sample.csvDownload a sample CSV template.

Payment Sessions

The 18-digit IPAY reference flow. Filterable by country, carrier, PSP, payment_method, status.

GET/api/payment-sessionsList + filter sessions.

GET/api/payment-sessions/{id}Session detail with event log.

POST/api/payment-sessions/{id}/parcel-statusAdvance the parcel state (PICKED_UP → IN_DELIVERY → DELIVERED).

GET/api/session/{token}Public consumer endpoint (used by /pay/{token}).

POST/api/session/{token}/start-paymentKick off Stripe checkout / simulate.

Driver — OTP verification

Verify the 4-digit OTP at the door, release parcel.

POST/api/driver/verify-otpBody: ipay_reference_18 + otp_4 → release parcel.

E-commerce Integrations

Connect Shopify / PrestaShop / WooCommerce / Odoo / Shopware / Magento / BigCommerce / Lightspeed / bol.com. Each connector exposes the same shape: GET / setup-info / connect / disconnect / sync / simulate / webhook.

GET/api/integrations/statusPer-merchant connection status for all providers.

POST/api/integrations/{provider}/connectSave credentials, verify via the provider's API.

POST/api/integrations/{provider}/syncPull recent orders (limit 50).

POST/api/integrations/{provider}/simulateFire a test order without live credentials.

POST/api/integrations/{provider}/webhookReal-time push from the platform (HMAC-signed where supported).

Carrier Tariffs & Cost Engine

488 carriers × multi-origin (NL/BE/FR) tariff database. Operator-managed.

POST/api/admin/carrier-tariffs/importUpload UPS / DHL / etc. tariff Excel.

POST/api/admin/carrier-tariffs/cost-previewCompute carrier cost for a {origin, destination, weight, dimensions} query.

PUT/api/admin/carrier-tariffs/{carrier}/fuelUpdate fuel surcharge (published % + IPAY discount %).

Carrier Invoice Reconciliation

Upload carrier invoices, auto-match against shipped orders, flag MISMATCH / UNMATCHED_IN_DB.

POST/api/admin/carrier-tariffs/{cc}/invoice-uploadUpload CSV invoice file (carrier code = UPS / DHL / …).

GET/api/admin/carrier-tariffs/{cc}/invoicesList uploaded invoices with reconciliation aggregates.

GET/api/admin/carrier-tariffs/{cc}/billing-coverageWhich shipments have been invoiced vs not?

Sales & CRM

Internal CRM mirroring HubSpot. Two pipelines: merchant_sales + partner_sales.

GET/api/sales/companiesList companies (filterable by type / status / segment / search).

POST/api/sales/companiesCreate company (auto-score + auto-segment).

POST/api/sales/hubspot/connectConnect HubSpot Private App token.

POST/api/sales/hubspot/sync/push-qualifiedPush every A/B/qualified company to HubSpot.

GET/api/sales/target-segmentsChina→EU strategic 4.186B-parcel target pool.

Quote Engine (Offers)

Generate branded customer quotes with full cost+margin breakdown.

POST/api/quotesCreate a new quote draft.

GET/api/quotes/{id}/external.pdfCustomer-facing PDF (with IPAY green header + logo).

GET/api/quotes/{id}/internal.xlsxInternal margin-protection Excel.

Auto-sync Scheduler

15-min interval auto-sync for every CONNECTED merchant integration. Admin only.

GET/api/admin/scheduler/statusIs the scheduler running? Next run time.

POST/api/admin/scheduler/run-nowTrigger an immediate pass.

GET/api/admin/scheduler/sync-logPer-merchant × provider run log (latest 100).

GET/api/admin/scheduler/summaryAggregate per-provider stats.

Real-time event stream (SSE)

Server-sent events for live operator dashboards.

GET/api/events/stream?token=...Open an EventSource. Heartbeat every 15s; merchants only see their own sessions.

Smart Returns (Sendcloud + IPAY composite labels)

Generate real carrier return labels with an IPAY emerald overlay (QR + warning).

POST/api/returns/openConsumer opens a return case for a paid order.

POST/api/labels/createGenerate Sendcloud label + IPAY composite PDF.

POST/api/webhooks/sendcloud/returnsInbound webhook: parcel_status_changed.

GET/api/returns/{token}Public consumer return-portal.

Carrier Statements & Aging Report

Line-by-line reconciliation → PDF statement → emailed to carrier via Resend.

POST/api/admin/carrier-tariffs/{cc}/reconciliations/{id}/request-creditFlag a row for credit (reason required, goes on the statement).

POST/api/admin/carrier-tariffs/{cc}/reconciliations/{id}/excludeMark a delta as accepted (exclusion reason required).

GET/api/admin/carrier-tariffs/{cc}/statements/{import_id}/previewInline PDF preview of the statement.

POST/api/admin/carrier-tariffs/{cc}/statements/{import_id}/sendSend PDF to carrier via Resend (logs to db.carrier_statement_log).

GET/api/admin/carrier-statements/aging-reportOutstanding statements bucketed 0-7d / 7-30d / 30-60d / 60+d.

POST/api/admin/carrier-statements/{statement_id}/mark-resolvedCarrier credited — remove from aging report.

Settlement (Merchant Portal)

Fixed-fee IPAY commercial model — gross − (count × fee_per_order) = net. PDF + accountant export.

GET/api/merchant-portal/ipay/settlementSettlement totals + daily breakdown for a period. Returns fee_per_order_eur + fee_source.

GET/api/merchant-portal/ipay/settlement/pdfBranded PDF statement for finance/accountant/audit.

PATCH/api/admin/merchants/{id}Update merchant — set ipay_fee_per_order_eur + ipay_contract_signed_at. Audit-trail in ipay_fee_history[].

HubSpot bi-directional sync

Mirror qualified companies to HubSpot; auto-graduate on Closed-Won.

POST/api/sales/hubspot/connectSave HubSpot Private App token.

POST/api/sales/hubspot/sync/push-qualifiedPush every A/B-graded company to HubSpot.

POST/api/webhooks/hubspotInbound webhook (deal stage / company property changes). Closed-Won → auto-graduate.

GET/api/sales/hubspot/webhook-eventsRecent webhook events (audit).

RBAC — roles, permissions, data scopes

Granular access: 32 resources × 6 actions × 3 data scopes. Multi-role per user.

GET/api/rbac/rolesList roles (auto-seeds 4 system roles on first call).

POST/api/rbac/rolesCreate a custom role.

PUT/api/rbac/roles/{id}/permissionsEdit a role's permission matrix.

POST/api/rbac/users/{id}/assign-roleAssign a role to a user.

GET/api/rbac/me/permissionsEffective permissions for the current user (merged across roles).

Internal Controls & Compliance

~30 daily controls (data integrity, settlement match, PSP health, …) + CFO approval + Resend digest.

GET/api/internal-controls/overviewToday's control snapshot + last 30 days history.

POST/api/internal-controls/{control_id}/approveCFO approves a RED control. Body: {initials}. Appends to control_approvals (permanent).

GET/api/data-integrity/snapshots30-day snapshot retention for data integrity.

GET/api/admin/compliance/registerCompliance register (GDPR/PSD2/Sendcloud T&C/etc.)

i18n / Translation Health (18 langs)

NL master + 17 Claude-translated languages. AI-fill missing keys with one POST.

GET/api/admin/translation-healthPer-language coverage % + missing/identical/extra-key breakdown by namespace.

POST/api/admin/translation-health/{lang}/ai-fillClaude Sonnet 4.5 translates all missing keys from NL → target language. Optional ?namespace=consumer.

POST/api/admin/translation-health/ai-fill-all1-click mega-fill: AI-fill all 16 target languages sequentially.

PUT/api/admin/translation-health/{lang}/editBulk-edit specific keys in a language.

Finance · Accounting Control (Exact Online)

Daily batch generation, CFO approval, post-to-Exact (mocked), accrual reconciliation.

GET/api/finance/batchesDaily accounting batches with status (pending/approved/rejected/posted).

POST/api/finance/batches/{id}/approveCFO approves the batch.

POST/api/finance/batches/{id}/post-to-exactPost journal entries to Exact Online (currently MOCKED).

GET/api/finance/reconciliationAccrual reconciliation: accrued vs settled cash.

Marketplace integrations (15+ providers)

Shopify · WooCommerce · PrestaShop · Magento · Shopware · BigCommerce · Lightspeed · bol.com · Picqer · Odoo · Lazada · TikTok · Amazon NL/DE/FR/IT/ES · Shopee · Temu · AliExpress · Vinted.

GET/api/integrations/{provider}/Per-provider connection status.

GET/api/integrations/{provider}/setup-infoWhere to obtain credentials + scopes required.

POST/api/integrations/{provider}/connectSave credentials + verify.

POST/api/integrations/{provider}/syncPull recent orders.

POST/api/integrations/{provider}/simulateFire a sample order without live creds (development/demo).

Consumer App V2 (action-first wallet)

Magic-link login · Share payment · Points · Deals · Wallet · Loyalty cards.

POST/api/consumer/magic-link/requestRequest a one-time login link via email.

POST/api/consumer/magic-link/redeemRedeem the link → returns JWT.

GET/api/wallet/balanceConsumer wallet balance + recent transactions.

POST/api/wallet/transferWallet-to-wallet transfer to another consumer.

GET/api/points/meLoyalty points balance + history.

GET/api/deals/feedPersonalized deals feed.

POST/api/share-payment/{session_id}Generate a share-payment short URL.

Webhooks

Webhook directory

Inbound webhooks let your shop/WMS/carrier push events into IPAY. Outbound webhooks let IPAY notify your systems when relevant business events fire.

Inbound webhooks — providers → IPAY

Each e-commerce / WMS / carrier connector exposes an inbound webhook URL. Configure the URL + secret in the provider's admin panel, IPAY validates the signature (where supported) and creates/updates orders + sessions.

Shopify

/api/integrations/shopify/webhook

Signature: X-Shopify-Hmac-Sha256

Topics: orders/create, orders/paid, orders/updated

WooCommerce

/api/integrations/woocommerce/webhook

Signature: X-WC-Webhook-Signature

Topics: order.created, order.updated

PrestaShop

/api/integrations/prestashop/webhook

Topics: actionValidateOrder

Magento

/api/integrations/magento/webhook

Topics: sales_order_save_after

Shopware

/api/integrations/shopware/webhook

Signature: shopware-shop-signature

Topics: order.written

BigCommerce

/api/integrations/bigcommerce/webhook

Signature: X-Hub-Signature

Topics: store/order/created, store/order/updated

Lightspeed eCom

/api/integrations/lightspeed/webhook

Signature: X-Lightspeed-Shop

Topics: orders/created

bol.com Retailer

/api/integrations/bol/webhook

Topics: new orders (long-poll via /sync; bol.com does not push webhooks)

Picqer

/api/integrations/picqer/webhook

Signature: X-Picqer-Subdomain

Topics: orders.completed, picklists.created

Odoo

/api/integrations/odoo/webhook

Topics: sale.order.confirmed

Sendcloud

/api/integrations/sendcloud/webhook

Signature: Sendcloud-Signature

Topics: parcel_status_changed, integration_credentials_updated

Locker carriers — DPD / UPS / PostNL / InPost / Allegro One

/api/lockers/{carrier}/issue-code OR /api/lockers/issue-code

Signature: X-IPAY-Signature (HMAC-SHA256)

Topics: locker_code_issued

Stripe

/api/payments/webhook

Signature: Stripe-Signature

Topics: checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed

MultiSafepay

/api/webhooks/multisafepay

Signature: Auth (base64 timestamp:HMAC-SHA512)

Topics: order.completed, order.declined, order.refunded, transaction.status_changed

HubSpot

/api/webhooks/hubspot

Signature: X-HubSpot-Signature-v3 (sha256-base64)

Topics: deal.propertyChange (dealstage=closedwon → auto-graduate), company.propertyChange

Lazada Open Platform

/api/integrations/lazada/webhook

Signature: X-Lazada-Sign

Topics: order_status_change (planned — pending platform onboarding)

TikTok Shop

/api/integrations/tiktok_shop/webhook

Signature: X-Tts-Signature

Topics: package.delivered (planned)

Amazon SP-API NL/DE/FR/IT/ES

/api/integrations/amazon/webhook

Signature: AWS Sig-v4 (delivered via EventBridge / SQS)

Topics: ORDER_STATUS_CHANGE (planned)

Shopee · Temu · AliExpress · Vinted · Cdiscount · Empik · Kaufland · Shein

/api/integrations/{provider}/webhook

Signature: Varies per platform

Topics: Simulated / sync-only (no live webhook until platform partnership signed)

OpenCart · NopCommerce

/api/integrations/{provider}/webhook

Topics: order.created / order.status (via custom plugin)

Mollie · PayPal · Adyen · 2C2P

Pending — handlers to be built once direct contracts signed

Topics: Will follow PSP-specific schemes — see Integrations Roadmap

Resend

/api/webhooks/resend (planned)

Signature: Svix-Signature

Topics: email.sent · email.delivered · email.bounced (planned — currently we email outbound only)

Outbound webhooks — IPAY → merchant

Merchants can subscribe to IPAY events. Configure the URL in /app/integrations or via API. Payload is JSON, signed with HMAC-SHA256 using your merchant secret.

order.created

A new order enters the IPAY pipeline (manual, CSV, integration, or simulate).

session.created

Payment session generated — includes the 18-digit IPAY reference + pay URL + QR data URL.

session.paid

PSP confirms payment — OTP is now derivable; consumer can pick up parcel.

session.otp_verified

Driver scans OTP at the door, parcel released.

parcel.delivered

Parcel marked delivered (final state).

return.opened

Consumer opens a return case via /returns portal.

return.refunded

Refund / app-credit issued for a return.

locker.code_issued

Carrier dropped parcel into a locker; unlock code in IPAY consumer wallet.

invoice.mismatch

Reconciliation flagged a delta between carrier invoice and IPAY's computed cost.

Complete reference

Every endpoint · auto-generated from OpenAPI

The full catalog of 827 endpoints across 46 domains, regenerated on every backend reload — guaranteed never to drift from what's actually live. Click a domain to expand.

Need something not listed here? devsupport@ipay.global · Or browse the interactive Swagger UI.

IPAY Assistant

Claude Sonnet 4.5

Hoi! Ik ben IPAY Assistant — vraag me alles over hoe IPAY werkt, hoe je je shop koppelt, of API-endpoints. ✨

Quick questions