Buyer onboarding flows

Mondu provides two distinct onboarding endpoints based on the payment method you're offering to buyers:

• Standard Payment Methods (Invoice, SEPA Direct Debit, Instalments, PayNow): Use the Hosted Buyer Onboarding endpoint
• Pay on account: Use the Digital Trade Account endpoint

Both endpoints share identical legal and technical requirements. Each requires buyer data and a redirect URL in the request payload, and returns a URL to the Mondu Hosted Onboarding Page.

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.

Key differences between endpoints

Hosted buyer onboarding

• Displays standard Mondu onboarding messaging to the buyer
• Shows the approved credit limit
• Enables limit retrieval via Get Buyer Limit
• Supports: Invoice, SEPA Direct Debit, Instalments, PayNow

Digital Trade Account for Pay on account

• Displays Digital Trade Account application messaging
• Shows the approved credit limit
• Enables limit retrieval via Get Buyer Limit
• Supports: Pay on account, Invoice, SEPA Direct Debit, Instalments, PayNow

Mondu API (order creation with buyer onboarding)

Mondu Buyer Onboarding

Legal requirements

Required Action:

• Display GDPR notification to buyers before initiating onboarding:
• Information on the processing of your personal data by Mondu GmbH can be found here.

Technical implementation

Step 1: Create request

Call the Hosted Buyer Onboarding or Digital Trade Account endpoint with the following payload:

{
  //MANDATORY PARAMETERS
  "external_reference_id": "your-buyer-id-123-456",
  "redirect_urls": {
        "success_url": "http://yourshop.com/success",
        "cancel_url": "http://yourshop.com/cancel",
        "declined_url": "http://yourshop.com/declined"
    },
  	//OPTIONAL PARAMETERS
    "applicant": {
        "first_name": "Max",
        "last_name": "Musterman",
        "email": "[email protected]",// Buyer approved; all subsequent orders auto-approved
        //"email": "[email protected]",// Buyer set to pending; all subsequent orders set to pending
        //"email": "[email protected]",// Buyer declined; all subsequent orders auto-declined
        //https://docs.mondu.ai/v0.7/docs/start-integrating#32-buyer-onboarding-testing-digital-trade-account
        "phone": "030123456"
    },
    "company_details": {
    "registration_address": {
      "country_code": "DE",
      "state": "Berlin",
      "city": "Berlin",
      "zip_code": "10117",
      "address_line1": "Unter den Linden 16"
    },
    "legal_form_type": "registered_company",
    "name": "Mondu GmbH",
    "company_registration_id": "HRB 232626 B"
  }
}

Required parameters:

• redirect_urls: URLs for success, cancel, and declined scenarios
• company_details: Buyer's registered business details
• external_reference_id: Your internal buyer identifier

Best Practice: Include all available company details to minimize data entry for buyers during onboarding.

Step 2: Handle API response

Redirect the buyer to the hosted_page_url to complete onboarding.

{
  "hosted_page_url": "https://onboarding.demo.mondu.ai?session_uuid=020b95dc-69da-45da-a37a-0bda12be8824&session_token=0e296567-1afb-4c71-9879-60fefc72335e"
}

Step 3: Process buyer webhook

Configure your webhook endpoint to receive buyer status updates:

{
  "topic": "buyer/{TOPIC_NAME}",
  "buyer": {
    "uuid": "12345667-890a-bcde-f123-34567890abcd",
    "state": "accepted",
    "external_reference_id": "0cda2ccb-ebde-403b-9d64-37cff079de2f",
    "company_name": "Mondu",
    "first_name": "Max",
    "last_name": "Mustermann",
    "legal_form": "GmbH"
  }
}

Important:

• Store the buyer.uuid from the webhook—this UUID is required for all subsequent order requests.

Step 4: Handle onboarding states

When using Mondu's Digital Trade Account feature, buyers may undergo manual review during onboarding. To handle all possible outcomes, subscribe to the following webhooks:

• buyer/pending
• buyer/accepted
• buyer/declined

Implementation notes:

• Accepted buyers: You can begin creating orders immediately using the buyer.uuid from the webhook payload.
• Declined buyers: Consider providing alternative payment options in your checkout flow.
• Pending buyers: Review typically completes within 48 hours. Do not create orders until you receive the buyer/accepted webhook.

Example buyer communication:

• Pending: "Your Mondu account application is being reviewed. We'll notify you within 48 hours."
• Declined: "Unfortunately, we cannot offer Mondu payment methods at this time. Please select an alternative payment option."
• Accepted: "Your Mondu account has been approved! You can now use Mondu payment methods at checkout."

Step 4: Create orders for onboarded buyers

After successful onboarding, create orders using one of the endpoint:

• Create Order
• Create Async Order

Implementation

Follow Start Integrating for more details about the integration steps.

Summary of important requirements:

• Include the buyer.uuid received from the onboarding webhook to the Create Order Payload
• Set payment_method parameter to specify the desired payment method
  • Pay on account - billing_statement
  • Invoice payment - invoice
  • SEPA Direct Debit - direct_debit
  • Installments - installments
• Redirect the buyer to hosted_checkout_url to complete payment method selection and order confirmation.