Developer Reference
IPAY API · v0.92.79
Every endpoint lives under https://portal.ipay.global · 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.
1628 live endpoints across 58 domains — auto-generated, always in sync.
Curated quickstart groups
Merchant Operations API (v0.97.5)
Tenant-scoped REST API for orders, shipments, tracking, webhooks and audit-log. All endpoints require JWT bearer (merchant or operator role).
GET
/api/merchant-api/meIdentify the calling user + supported events + rate limits.GET
/api/merchant-api/ordersList orders (paginated, filter by status).GET
/api/merchant-api/orders/{order_id}Fetch order detail.POST
/api/merchant-api/ordersCreate a new order. Emits `order.created` webhook.PATCH
/api/merchant-api/orders/{order_id}Update fields on an existing order. Emits `order.updated`.POST
/api/merchant-api/orders/{order_id}/cancelCancel order. Emits `order.cancelled`.GET
/api/merchant-api/shipmentsList shipments (filter by order_id, status).GET
/api/merchant-api/shipments/{shipment_id}Fetch shipment detail.GET
/api/merchant-api/shipments/{shipment_id}/trackingAggregated carrier + release events timeline.POST
/api/merchant-api/shipments/{shipment_id}/tracking-eventPush a tracking update. Emits matching `shipment.*` webhook.GET
/api/merchant-api/webhooks/event-typesList the 19 supported event types.GET
/api/merchant-api/webhooks/endpointsList configured webhook endpoints (secret redacted).POST
/api/merchant-api/webhooks/endpointsCreate endpoint. Returns signing secret ONCE.PATCH
/api/merchant-api/webhooks/endpoints/{endpoint_id}Update URL, subscribed events or active flag.DELETE
/api/merchant-api/webhooks/endpoints/{endpoint_id}Delete an endpoint.POST
/api/merchant-api/webhooks/endpoints/{endpoint_id}/rotate-secretGenerate a new signing secret. Old one stops immediately.GET
/api/merchant-api/webhooks/deliveriesList delivery attempts (filter by status, endpoint, event).GET
/api/merchant-api/webhooks/dead-lettersList deliveries that failed after 5 retries.POST
/api/merchant-api/webhooks/deliveries/{delivery_id}/retryManually re-queue a delivery.POST
/api/merchant-api/webhooks/testFire a synthetic event to all subscribed endpoints.GET
/api/merchant-api/audit-logAppend-only immutable log of writes + auth + sensitive reads.Merchant Assistant API (v0.97.7)
Tenant-scoped AI helper powered by Claude Sonnet 4.5. Knowledge: per-merchant FAQ + global IPAY help articles.
GET
/api/merchant-api/assistant/profileRead assistant config (name, tone, language, instructions, topics).PUT
/api/merchant-api/assistant/profileUpdate profile. Custom instructions sanitised + capped at 500 chars.GET
/api/merchant-api/assistant/faqsList FAQ entries (tenant-scoped).POST
/api/merchant-api/assistant/faqsCreate FAQ — question, answer, tags.PATCH
/api/merchant-api/assistant/faqs/{faq_id}Update a FAQ.DELETE
/api/merchant-api/assistant/faqs/{faq_id}Delete a FAQ.POST
/api/merchant-api/assistant/chatSend a message. Returns answer + sources (FAQ + article IDs).GET
/api/merchant-api/assistant/conversationsList recent chat sessions (90d retention).GET
/api/merchant-api/assistant/conversations/{session_id}Full message thread for one session.DELETE
/api/merchant-api/assistant/conversations/{session_id}GDPR purge — irreversible.Authentication
Register, login, fetch current user. JWT bearer tokens (7-day TTL).
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.User Branding (logo + company name)
Every authenticated user can upload their own logo (≤256 KB PNG/JPG, auto-resized to 240×80) and set a company name. Renders in the persona banner across the portal. Designed to migrate to AWS S3 later — only the storage backend changes.
GET
/api/user-branding/meFetch the current user's branding (company_name + logo_data_url).PATCH
/api/user-branding/meUpdate the current user's company_name. Body: { company_name }.POST
/api/user-branding/me/logoUpload a logo (multipart/form-data: file). Returns the inline base64 data URL.DELETE
/api/user-branding/me/logoRemove the current user's logo.GET
/api/admin/user-branding/list?role=carrierAdmin · list all users with their branding (optional ?role filter).POST
/api/admin/user-branding/{user_id}/logoAdmin uploads a logo on behalf of another user.PATCH
/api/admin/user-branding/{user_id}Admin updates company_name for another user.DELETE
/api/admin/user-branding/{user_id}/logoAdmin removes a user's logo.Role-specific Action Items (banner)
Surfaces 'Vandaag: 5 factuurregels met verschil — review nodig' in the persona banner. Returns role-aware action items (Operator / Carrier / Partner / Investor / Sales / Merchant). Read-only; sources from existing collections.
GET
/api/user-actions/meReturns {role, emoji, count, items[5]} — clickable items with priority + deep-link.Admin · Internal Documents Viewer
Operator can read PRD / SSL ticket / marketing links / persona audit inside the portal — no filesystem access needed. Whitelist approach (7 fixed filenames).
GET
/api/admin/internal-docs/listList of allowed documents with size + mtime.GET
/api/admin/internal-docs/{filename}Return the raw markdown of one document (text/plain).Talking AI Avatar (D-ID)
Generate a talking-head video from text using D-ID Talks API + per-tenant presenter configuration.
GET
/api/avatar/statusIs D-ID configured? + current presenter ID.POST
/api/avatar/settingsSave presenter / voice configuration.POST
/api/avatar/talkGenerate a talking-head video clip from text input.Help Center (multilingual, v0.92.20)
56 customer-friendly articles in NL + EN with `?lang=` query param. Fallback chain: requested-lang → en → nl → legacy. Extending to 16 more languages in Q3 2026.
GET
/api/help/articles?lang=nlList all articles grouped by category in chosen language.GET
/api/help/articles/{article_id}?lang=enFetch one article (title + summary + body) in chosen language. Body is Markdown.Internal Control Catalogue
44 automated controls covering payments, security, data integrity, audit logs. Runs in parallel via asyncio.gather.
POST
/api/control-room/run-all-autoRun every catalogue control in parallel; returns status_distribution + per-control results.GET
/api/control-room/catalogueList catalogue items (control_id, title, block, automated).GET
/api/control-room/cfo-digest/previewRender the weekly CFO snapshot — JSON summary + HTML preview.POST
/api/control-room/cfo-digest/send-nowTrigger Resend send of the digest immediately (operator only).Refund Clearing Ledger
Append-only audit of who refunds what to whom · state machine + aging buckets + bulk transitions.
GET
/api/refund-ledger/balanceOpen obligations + aging buckets (>7d/>30d/>90d) + oldest_open + closed_last_30d.GET
/api/refund-ledger/entriesFiltered list with status/from_party/to_party/days_back/date_from/date_to.POST
/api/refund-ledger/bulk-transitionApply same status transition to ≤100 entries at once (v0.92.79).GET
/api/refund-ledger/export.csvCSV download with same filters as /entries.GET
/api/refund-ledger/search?q={q}Lookup by id/psp_refund_id/session_id/transaction_id (min 4 chars).Meeting Notes + Action Items
QR-coded PDF upload, GPT-4o-mini Vision analysis, Phase 2 trackable action items.
POST
/api/meeting-notes/uploadUpload PDF, auto-link via QR if covered.POST
/api/meeting-notes/{note_id}/analyzeRun GPT-4o-mini Vision to extract summary + action_items + decisions.POST
/api/meeting-notes/{note_id}/action-items/promoteBulk-promote AI action items into trackable tasks.GET
/api/meeting-notes/action-itemsList action items with filters (status, assignee, overdue_only) + summary KPIs.PATCH
/api/meeting-notes/action-items/{id}Update status/assignee/due_date/priority/notes.Internal Filing — Document Vault (5-tier)
Hierarchical document vault. Each doc has rank_required (1-5); users see docs ≤ their rank.
GET
/api/internal-filing/treeBrowse sections + documents visible to current user.POST
/api/internal-filing/documents/uploadUpload PDF with section_code + rank_required + title.PATCH
/api/internal-filing/documents/{file_id}/levelRe-classify a document's rank_required (1-5). v0.92.79. Audits to doc_level_changes.Investor Portal (5-tier hierarchical)
Phase-gated investor docs. Migrated v0.92.79 from 2-tier to 5-tier hierarchical access.
POST
/api/investor/sessions/startBegin investor session; returns visible docs for their phase + access_level.POST
/api/investor/documents/uploadOperator uploads doc with required_phase + access_level (1-5).PATCH
/api/admin/investor/documents/{file_id}/levelRe-classify an investor doc's access_level (1-5). v0.92.79.CRM Nightly Backup
Daily ZIP of companies/contacts/deals/activities CSVs into GridFS bucket with 30d retention.
GET
/api/crm/backup/csvLive download of fresh ZIP (operator/cfo).GET
/api/crm/backup/historyList nightly snapshots from GridFS (newest first).POST
/api/crm/backup/run-nowManual trigger — write fresh backup to GridFS now (operator only).Data Integrity Snapshots
Hash-based snapshots of master/event/audit collections for compliance + drift detection.
GET
/api/audit/data-integrity/master-collectionsList registered collections; supports ?category=master|event|audit filter.POST
/api/audit/data-integrity/snapshotTake a fresh snapshot of all critical collections.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/webhookSignature:
X-Shopify-Hmac-Sha256Topics: orders/create, orders/paid, orders/updated
WooCommerce
/api/integrations/woocommerce/webhookSignature:
X-WC-Webhook-SignatureTopics: order.created, order.updated
PrestaShop
/api/integrations/prestashop/webhookTopics: actionValidateOrder
Magento
/api/integrations/magento/webhookTopics: sales_order_save_after
Shopware
/api/integrations/shopware/webhookSignature:
shopware-shop-signatureTopics: order.written
BigCommerce
/api/integrations/bigcommerce/webhookSignature:
X-Hub-SignatureTopics: store/order/created, store/order/updated
Lightspeed eCom
/api/integrations/lightspeed/webhookSignature:
X-Lightspeed-ShopTopics: orders/created
bol.com Retailer
/api/integrations/bol/webhookTopics: new orders (long-poll via /sync; bol.com does not push webhooks)
Picqer
/api/integrations/picqer/webhookSignature:
X-Picqer-SubdomainTopics: orders.completed, picklists.created
Odoo
/api/integrations/odoo/webhookTopics: sale.order.confirmed
Sendcloud
/api/integrations/sendcloud/webhookSignature:
Sendcloud-SignatureTopics: parcel_status_changed, integration_credentials_updated
Locker carriers — DPD / UPS / PostNL / InPost / Allegro One
/api/lockers/{carrier}/issue-code OR /api/lockers/issue-codeSignature:
X-IPAY-Signature (HMAC-SHA256)Topics: locker_code_issued
Stripe
/api/payments/webhookSignature:
Stripe-SignatureTopics: checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed
MultiSafepay
/api/webhooks/multisafepaySignature:
Auth (base64 timestamp:HMAC-SHA512)Topics: order.completed, order.declined, order.refunded, transaction.status_changed
HubSpot
/api/webhooks/hubspotSignature:
X-HubSpot-Signature-v3 (sha256-base64)Topics: deal.propertyChange (dealstage=closedwon → auto-graduate), company.propertyChange
Lazada Open Platform
/api/integrations/lazada/webhookSignature:
X-Lazada-SignTopics: order_status_change (planned — pending platform onboarding)
TikTok Shop
/api/integrations/tiktok_shop/webhookSignature:
X-Tts-SignatureTopics: package.delivered (planned)
Amazon SP-API NL/DE/FR/IT/ES
/api/integrations/amazon/webhookSignature:
AWS Sig-v4 (delivered via EventBridge / SQS)Topics: ORDER_STATUS_CHANGE (planned)
Shopee · Temu · AliExpress · Vinted · Cdiscount · Empik · Kaufland · Shein
/api/integrations/{provider}/webhookSignature:
Varies per platformTopics: Simulated / sync-only (no live webhook until platform partnership signed)
OpenCart · NopCommerce
/api/integrations/{provider}/webhookTopics: order.created / order.status (via custom plugin)
Mollie · PayPal · Adyen · 2C2P
Pending — handlers to be built once direct contracts signedTopics: Will follow PSP-specific schemes — see Integrations Roadmap
Resend
/api/webhooks/resend (planned)Signature:
Svix-SignatureTopics: 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.createdA new order enters the IPAY pipeline (manual, CSV, integration, or simulate).
session.createdPayment session generated — includes the 18-digit IPAY reference + pay URL + QR data URL.
session.paidPSP confirms payment — OTP is now derivable; consumer can pick up parcel.
session.otp_verifiedDriver scans OTP at the door, parcel released.
parcel.deliveredParcel marked delivered (final state).
return.openedConsumer opens a return case via /returns portal.
return.refundedRefund / app-credit issued for a return.
locker.code_issuedCarrier dropped parcel into a locker; unlock code in IPAY consumer wallet.
invoice.mismatchReconciliation flagged a delta between carrier invoice and IPAY's computed cost.
Complete reference
Every endpoint · auto-generated from OpenAPI
The full catalog of 1628 endpoints across 58 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