Digital Trade Account

learn how to onboard buyers and make use of our consolidated statements for aggregated payments

Introduction

The Digital Trade Account lets you onboard buyers who can then order multiple times throughout the billing period. At the end of a billing period, Mondu sends out a consolidated statement with an overview of all open invoices, so that buyers can pay the full amount in one sum instead of needing to pay every invoice separately.

👍

Good to Know

The Digital Trade Account requires additional configuration on your merchant account. If you'd like to use our Digital Trade Account, please get in touch with your Mondu Sales Rep.

Prerequisites

To start using the Digital Trade Account, we'll need the following parts of Mondu's API

Buyer Onboarding

Legal Requirements

Before onboarding starts, you need to make the buyer aware of data processing by Mondu. You can use this snippet:

Information on the processing of your personal data by Mondu GmbH can be found here.

Technical Buyer Onboarding

To be able to use the Digital Trade Account feature, buyers first have to go through Mondu's buyer onboarding flow. This is done using the Create trade account API call:

{
  "redirect_urls": {
    "success_url": "https://yoursite.com/buyer_success",
    "cancel_url": "https://yoursite.com/buyer_cancel",
    "declined_url": "https://yoursite.com/buyer_declined"
  },
  "company_details": {
    "registration_address": {
      "country_code": "DE",
      "city": "Berlin",
      "zip_code": "10179",
      "address_line1": "Alexanderstr. 36"
    }
  },
  "external_reference_id": "buyer-01"
}
{
  "hosted_page_url": "https://onboarding.demo.mondu.ai?session_uuid=020b95dc-69da-45da-a37a-0bda12be8824&session_token=0e296567-1afb-4c71-9879-60fefc72335e"
}

Only redirection URLs to your site, an address and a buyer ID are required, though it's beneficial to add all known company details for the buyer here, so buyers don't have to fill in their data twice.

Afterwards, you'll have to redirect the buyer to Mondu's Hosted Onboarding Page:

Buyers can be onboarded on Mondu's system with the follwing statuses: accepted, declined and pending. Refer to Pending States for info on how to treat pending buyers.

If a buyer is in pending, Mondu will review them manually and either accept or decline them within 48 hours. You will be notified of the final decision by a Webhook.

{
  "topic": "buyer/{TOPIC_NAME}",
  "buyer": {
    "uuid": "12345667-890a-bcde-f123-34567890abcd",
    "state": "accepted",
    "external_reference_id": "buyer-01",
    "company_name": "2023-02-07T15:14:22.301Z",
    "first_name": "John",
    "last_name": "Smith",
    "legal_form": "Einzelunternehmen"
  }
}

📘

Buyer UUID

Keep note of the buyer uuid in the webhook, as this uuid will be used in subsequent order requests.

Orders for Onboarded Buyers

Once onboarded, you can start creating orders for your trade account buyers: Create Order

Legal Requirements

Please again make the buyer aware of Mondu's data processing policy.

Information on the processing of your personal data by Mondu GmbH can be found here.

Necessary Parameters for Digital Trade Account

Make sure to use Mondu's Hosted Checkout and send the Buyer UUID from the webhook before in the buyer object.

{
  //hosted checkout specific attributes
  "source": "hosted",
  "state_flow": "authorization_flow",
  "success_url": "http://shopdomain.com/success",
  "cancel_url": "http://shopdomain.com/cancel",
  "declined_url": "http://shopdomain.com/declined",
  "language": "en", //en|de|nl|fr
  //order specific attibutes
  //payment_method can be set to 	  //invoice|installment_by_invoice|direct_debit|installments|billing_statement
  //your account has to be configured to support above payment methods
  "payment_method": "billing_statement",
  "currency": "EUR", //defult setting EUR (GBP|CHF|SEK can be enabled request)
  "gross_amount_cents": 1315,
  "external_reference_id": "order-id-123",
  "net_term": 30, // default setting 30, (14||45|60|90 can be enabled upon the request)
  "total_discount_cents": 15,
  "buyer": {
    //mandatory attributes
    //Following email addresses will trigger the test case on DEMO
    //[email protected] sets the order to status confirmed 
    //[email protected] sets the order to status pending
    //[email protected] sets the order to status declined
    "email": "[email protected]",
    "first_name": "joe",
    "last_name": "doe",
    //recommended to optimise ux in the mondu hosted checkout page
    "external_reference_id": "buyer-id-123",
    "company_name": "Mondu GmbH",
    "legal_form": "GmbH",
    "registration_id": "14681433", // company registration id
    "is_registered": true, // true if the company is registered
    //recommended to help mondu create better stats on buyer 
    "account_created_at": "2023-08-22T15:25:56.265Z",
    "account_updated_at": "2024-08-22T15:25:56.265Z",
    //To create order for payment method billing_statement the buyer uuid mus be added
    //For ivoice|direct_debit|installments|installment_by_invoice it is optional.
    // The buyer's UUID is sent to the merchant via buyer webhook.
    "uuid":"12345667-890a-bcde-f123-34567890abcd" 
  },
  "billing_address": {
    "country_code": "DE",
    "city": "Berlin",
    "zip_code": "10117",
    "address_line1": "Unter den Linden 16",
    "address_line2": "",
    "state": ""
  },
  "shipping_address": {
    "country_code": "DE",
    "city": "Berlin",
    "zip_code": "10117",
    "address_line1": "Unter den Linden 16",
    "address_line2": "",
    "state": ""
  },
  //prouct related attriburtes
  "lines": [
    {
      "tax_cents": 220,
      "shipping_price_cents": 100,
      "line_items": [
        {
          "quantity": 10,
          "external_reference_id": "product-id-123",
          "title": "test product #1",
          "net_price_per_item_cents": 100,
          "item_type": "product|service"
        }
      ]
    }
  ]
}
{
    "order": {
        "external_reference_id": "order-id-123",
        "hosted_checkout_url": "https://pay.demo.mondu.ai/?session_uid=b15bfa81-9a32-4d5b-98f1-520a84227ca1&session_token=5ac20573-350c-4dbd-87cf-354523091ee4",
        "state": "created",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVhdGVkX2F0IjoiMjAyNS0wOC0xMyAxMjowNjowNiBVVEMiLCJleHAiOjE3NTU3Nzc5NjYsIm9yZGVyX2lkIjo2NDcyMCwic2Vzc2lvbiI6IjVkYWUwNTc3LWJkNDMtNDk0Ny1iYWNkLWZiNzRkY2ZiMDVhNiJ9.J9lPie_8brqqTNdwtj_MVgH3xF0NojKFThUHNzzldTA",
        "uuid": "fece9778-eb61-4d0a-a007-877dc21203e1"
    }
}

Invoices

Create Invoice requests work exactly like with Mondu's other products. Make sure to issue an invoice whenever you ship an order for onboarded buyers.

Legal requirements

Please refer to Mondu Invoice Snippets for Collective Statement for legal information that has to be present on your Invoices.

Credit Notes

Credit Notes work exactly the same when issued in a Digital Trade Account context. Just make sure to create them before the billing period ends if you want to prevent already credited invoices showing up in the collective statement.

Consolidated Statement

When the billing period is over, the buyer will receive a collective statement by Mondu, asking to pay the total amount of invoices issued in the billing period with the configured net terms.