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
  [email protected]
• 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

• 1,000 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 [email protected] 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 [email protected] 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: [email protected]
• Include: Relevant UUIDs, request/response examples, and error messages