Custom payment integrations

Integrate Bookingmood with a payment provider of your choice.

Why custom payment integrations#

Bookingmood supports several payment providers out of the box.

As we serve users world-wide, each country may have its own payment provider.

Instead of building custom integrations with all of these, we expose primitives that allow you to build custom payment pipelines.

Custom payment setup#

Go to Settings › General and set the Payment method to Custom.

A custom payment configuration consists of 2 fields:

• endpoint: The URL that will be called for generating payment links

• signing_secret: The secret we use to sign our requests, so that you can validate the request actually originates from Bookingmood.

Handling payment requests#

When a guest initiates a payment (by clicking on the "pay" button), Bookingmood sends a POST request to endpoint.

This request contains a JSON body:

{
  action: "PAYMENT_LINK_CREATE",
  date: number, // Number of seconds since epoch
  language: string, // User language identifier
  payment_id, // ID of the payment the request is for
}

You can request further data regarding the payment and the related booking using our API.

The endpoint should quickly return a successful status code (2xx) and a JSON object:

{
  payment_url: string
}

Example endpoint#

// This example uses Express to receive requests
const express = require("express");
const app = express();

// Match the raw body to content type application/json
// If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
app.post(
  "/payment-link-generation-endpoint",
  express.json({ type: "application/json" }),
  (request, response) => {
    const event = request.body;
    // Handle the event
    switch (event.action) {
      case "PAYMENT_LINK_CREATE":
        const payment = await bookingmoodApi
          .from("payments")
          .select("*")
          .eq("id", event.payment_id)
          .single();
        return response.json({
          payment_url: `https://custom-payment-provider.com/pay/${payment.amount - payment.paid}`
        });
      default:
        throw new Error(`Unexpected action: ${event.action}`);
    }
  }
);

app.listen(8000, () => console.log("Running on port 8000"));

Securing your endpoint#

After confirming that your endpoint works as expected, secure the connection by implementing best practices.

Verify requests are sent from Bookingmood#

Bookingmood signs every request in its X-Signature header, in the same way as webhook events, using your configuration's signing_secret. The request's date field protects against replay attacks. See Verify events are sent from Bookingmood for the steps and an example.

Zuletzt geändert 3. November 2026