This guide provides a comprehensive overview of the integration steps required to implement Mondu’s payment methods in your system. Follow these steps to integrate, test, and deploy Mondu's payment solutions.

Obtain API credentials

Action items:

1. Contact [email protected] to get a Mondu test account
2. Receive your Demo API Key at onboarding start for integration development and testing
3. Receive Mondu Production Bank details for the invoice templates
4. Receive your Production API Key after successful integration review

Timeline:

• Demo credentials are typically provided within 1-2 business days.
• Production credentials are issued after integration approval.

Testing credentials

Mondu provides predefined email patterns on the DEMO environment that trigger specific risk engine outcomes for comprehensive testing.

👍

Please check in the article Test credentials for the email patterns can be used to successfully place orders during the implementation.

Integration components

Step 1: Order creation

Purpose: Submit buyer data and transaction details to Mondu's Risk & Fraud Engine for buyer identification and risk evaluation.

Implementation:

• The endpoint you have to use depends on your system type (E-Commerce, Back-office, ERP)
  • Create Order endpoint for E-Commerce.
    • Overview order status
  • Create Async Order endpoint for ERP, Back-office or Offline orders
    • Overview async order status
• Here you get an overview of the different order states for normal orders and for async-orders.

Developer note: Ensure all required buyer and order data fields are mapped correctly from your system to Mondu's API schema.

Step 2: Order confirmation

Purpose: Synchronize order status between your system and Mondu after successful order placement.

Applicability: This step is only required when using the Create Order endpoint. Orders created via the Async Order endpoint do not require confirmation via confirm-API-endpoint. The buyer consent through the e-mail changes the order status from authorized to confirmed.

Implementation:

• Listen for the Order/Authorized Webhook from Mondu
• When received, trigger the Confirm Order request with your buyer facing order number
• This updates the order status in Mondu from authorized to confirmed

Critical: Order confirmation must occur after the order is successfully placed in your system but before shipment.

Step 3: Webhook integration

Purpose: Receive real-time status updates for Orders, Invoices, Credit Notes, Buyers, and Payouts.

Implementation steps:

• Whitelist Mondu IP addresses to allow webhook delivery - view Whitelist IP Addresses
• Register webhook endpoints for relevant WEBHOOK TOPICS
• Implement webhook signature verification to ensure requests originate from Mondu. - Compare Signatures
• Return HTTP 200 responses to acknowledge receipt
• Implement webhook handlers in your system to process status changes

Testing: Use webhook testing tools to verify your endpoints are accessible and responding correctly.

Retry logic: If a webhook delivery attempt fails, Mondu will automatically retry sending the webhook.

Step 4: Pending order state handling

Purpose: Support manual review processes that increase overall order approval rates.

What happens:

• Some orders require manual review by Mondu (completed within 24 business hours)
• During review, the order status is set to pending
• Final decision (approved/declined) is communicated via Order Webhook

Implementation:

• Handle pending status in your order management system
  • Orders with pending status should NOT be shipped
  • Orders with confirmed status should be shipped
• Display appropriate messaging to buyers (e.g., "Order under review")
• Listen for webhook updates to capture final decision
• Update order status in your system accordingly

Read more: Implement Pending, Order Status, Async Order Status

Step 5: Invoice submission

Purpose: One of the most important API calls, it enables Mondu to process payouts to your bank account and starts the due date towards the buyer.

Implementation:

• Invoice template must comply with Mondu's legal requirements. See Mondu Invoice Snippet for details.
• Generate invoice PDF in your system when order is marked as shipped
• Verify order status in Mondu is confirmed Order Status, Async Order Status
• Submit invoice via Create Invoice endpoint with the embedded invoice PDF or as a public available link to the PDF document, when the order status changes to shipped in your e-commerce system

Partial invoicing:

• Multiple invoices can be submitted for a single order
• Sum of all partial invoices must equal the total order amount
• Useful for split shipments or partial fulfillment scenarios

Important:

• No payout will be processed without invoice submission
• Invoice submission starts the payment net terms for the buyer
• each invoice number has to be unique

Step 6: Credit note handling (optional)

Purpose: Adjust invoice amounts for returns, discounts, or other post-shipment modifications.

Implementation:

• When a shipped order is partially returned or discounted, submit a Create Credit Note request
• Credit notes reduce the invoiced amount and adjust payout calculations

Use cases:

• Product returns
• Post-sale discounts
• Damaged goods adjustments

Step 7: Order adjustments (optional)

Purpose: Modify order details before shipment when buyers request changes, costs are updated or articles are out of stock.

Implementation:

• Use Adjust Order Request to update order details
• Allowed: Product changes, quantity updates, cost adjustments
• Not Allowed: Buyer information changes
• Orders paid with PayNow cannot be adjusted.

Important considerations:

• Adding products or increasing costs may trigger re-evaluation by Mondu's risk engine

Timing: Only adjust orders before shipment. Use credit notes for post-shipment changes.

Step 8: Cancellation operations

Purpose: Keep Mondu synchronized when orders, invoices, or credit notes are cancelled in your system.

Implementation:

• Send cancellation requests to the appropriate endpoint:
• Order cancellation: Cancel Order
• Invoice cancellation: Cancel Invoice
• Credit Note cancellation: Cancel Credit Note

Best practice: Implement cancellation handlers in your order management workflow to automatically sync with Mondu.