Overview

Mondu provides a RESTful API that enables you to initiate transactions, monitor account activity, and manage payment operations. The API uses HTTPS for all communications and exchanges data in JSON format.

Environments

Mondu offers two separate environments to support your development and production workflows:

Sandbox - Development and testing with mock data
- https://api.demo.mondu.ai/api/v1
Production - Live transactions and real operations
- https://api.mondu.ai/api/v1

Important Notes

Each environment is completely isolated—resources and changes in one environment are not visible in the other
The sandbox environment comes pre-defined e-mails patterns for easy testing
Your API key determines which environment you're interacting with

Authentication

All API requests must be authenticated using API key authentication via the Api-Token header.

Getting Your API Keys

Apply for a Mondu account by contacting
integration@mondu.ai
Receive your Demo API Key at the start of onboarding
Receive your Production API Key after your integration passes review

Making Authenticated Requests

Include your API key in the request header:

curl https://api.demo.mondu.ai/api/v1/orders \
  -H "Api-Token: your_api_key_here" \
  -H "Content-Type: application/json"

Security Requirements

✅ All requests must use HTTPS
✅ Never expose your API keys in client-side code
✅ Use different keys for sandbox and production environments

Error Handling

Mondu uses standard HTTP status codes to indicate the success or failure of requests.

Status Code Ranges

2xx Success—the request was processed successfully
4xx Client error—invalid parameters, missing data, or access restrictions
5xx Server error—something went wrong on Mondu's side

Error Response Format

All errors return a JSON object with the following structure:

{
  "status": 422,
  "errors": [
   	{
      "name": "currency",
      "details": "must be filled"
    },
    {
      "name": "buyer.email",
      "details": "is missing"
    },
    {
      "name": "lines.0.lineItems.1.externalReferenceId",
      "details": "is missing"
    },
    {
      "name": "lines.0.lineItems.1.quantity",
      "details": "must be an integer"
    }
  ]
}

Error Response Fields

status: HTTP status code (matches the response header)
errors: Array of error objects
name: The field or parameter that caused the error
details: Human-readable description of what went wrong

Best Practices

Parse the errors array to provide specific feedback to users
The name field uses dot notation for nested objects (e.g., buyer.email)
Array indices are included in the path (e.g., lines.0.lineItems.1.quantity)
While error messages may change, status codes remain stable—build your error handling around status codes

Rate Limits

To ensure service stability, Mondu enforces rate limits on API requests.

Current Limits

500 requests per second per IP address
Applied independently to each environment (sandbox and production each have their own limit)

Rate Limit Exceeded

When you exceed the rate limit, you'll receive:

HTTP Status Code: 429 Too Many Requests
Recommended Action: Implement exponential backoff and retry logic

Resource Identifiers (UUIDs)

Every resource created in the Mondu system is assigned a Universally Unique Identifier (UUID).

Resource Types

UUIDs are generated for:

Orders
Factoring
Invoices
Credit Notes
Buyers

Where to Find UUIDs

UUIDs are returned in:

The JSON response body when creating or retrieving resources
Webhook Attempts payloads

{
    "order": {
        "uuid": "d343de32-2deb-43a7-84a1-ae45dc0deba0",
        "state": "confirmed",
        "external_reference_id": "O-106070-1"
    }
}

{
    "topic": "order/confirmed",
    "order_uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "order_state": "confirmed",
    "external_reference_id": "DE-1-1000745773",
    "event_time": "2023-02-07T15:14:22.301Z",
    "buyer": {
        "uuid": "da696603-deb4-4b5c-8bb3-5cbdb39c3d2c",
        "name": "Max Musterman",
        "legal_form": "Einzelunternehmen"
    },
    "pending_reason_description": "Order value acceptable, manual investigation in progress.", // only shows up with pending orders
    "net_term": 30,
    "bank_account": {
        "account_holder": "Mondu Capital S.à r.l.",
        "bank": "UniCredit Bank - HypoVereinsbank",
        "bic": "HYVEDEMME40",
        "iban": "DE86207300400000000555",
       	"sort_code": "902127", // only for UK buyers
        "account_number": "29823529" // only for UK buyers
    }
}

Why UUIDs Matter

Support requests: Include the UUID when contacting integration@mondu.ai for faster resolution
Idempotency: Use UUIDs to track and prevent duplicate operations
Debugging: Reference UUIDs in logs to trace requests across systems

Quick Start Checklist

Contact integration@mondu.ai to request API access
Receive and securely store your Demo API Key
Test your integration in the sandbox environment
Implement proper error handling for 4xx and 5xx responses
Add rate limit handling with retry logic
Store UUIDs for all created resources
Request your Production API Key after testing is complete
Deploy to production with the Production API Key and Production Base URLs

Need Help?

For integration support, questions, or to report issues:

Email: integration@mondu.ai
Include: Relevant UUIDs, request/response examples, and error messages