Skip to main content

Use payment modal

MONEI Payment Modal is the simplest way to securely collect payments from your customers without them leaving your website.

Collecting payments on your website consists of creating a payment object, and confirming the payment.

MONEI Payment Modal preview

note

Apple Pay and Bizum are not available when using MONEI Payment Modal integration.

Integration​

1. Create a Payment Server-side​

Create a Payment on your server with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious customers from being able to choose their own prices.

POST https://api.monei.com/v1/payments
curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 110,
  "currency": "EUR",
  "orderId": "14379133960355",
  "description": "Test Shop - #14379133960355",
  "customer": {
    "email": "john.doe@microapps.com"
   },
  "callbackUrl": "https://example.com/checkout/callback"
}'

The following parameters are required:

  • amount positive integer - Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD)
  • currency string - Three-letter ISO currency code, in uppercase. Must be a supported currency.
  • orderId string - An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system.
  • callbackUrl string - The URL to which a payment result should be sent asynchronously.

Check all available request parameters.

Included in the returned Payment object is a payment id, which is used on the client side to securely complete the payment process instead of passing the entire Payment object.

2. Confirm the payment Client-side​

To complete the payment you need to confirm it using monei.js confirmPayment function

Include monei.js on your checkout page by adding the script tag to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v2/monei.js"></script>
</head>
<body>
  <form id="payment-form" action="https://secure.monei.com/payments/{{payment_id}}" method="GET">
    <button id="payment-button" type="submit">Pay</button>
  </form>
</body>

You need to provide a paymentId (obtained in step 1). You can also provide additional parameters like customer.email. Check all available parameters.

client.js
// Handle form submission.
const paymentForm = document.getElementById('payment-form');
const paymentButton = document.getElementById('payment-button');
paymentForm.addEventListener('submit', function (event) {
  event.preventDefault();
  paymentButton.disabled = true;
  monei
    .confirmPayment({paymentId: '{{payment_id}}'})
    .then(function (result) {
      paymentButton.disabled = false;
      // At this moment you can show a customer the payment result
      // But you should always rely on the result passed to the callback endpoint on your server
      // to update the order status
      console.log(result);
      if (result.status === 'SUCCEEDED') {
        handleResult(result);
      } else {
        handleError(result);
      }
    })
    .catch(function (error) {
      paymentButton.disabled = false;
      console.log(error);
    });
});

After the form is submitted MONEI will automatically show a popup window with a payment page to collect payment details and then a 3d secure confirmation screen (if needed)

note

As an alternative process you can redirect your customer to payment.nextAction.redirectUrl on the server-side. Check our prebuilt payment page guide

3. An asynchronous request is sent to your server.​

MONEI will notify you about the payment status by sending an HTTP POST request to the callbackUrl. The request body will contain full payment object in JSON format.

This ensures that you get the payment status even when customer closed the browser window or lost internet connection.

The request also contains a MONEI-Signature header. Verify this signature to confirm that received request is sent from MONEI.

To acknowledge receipt of the request, your endpoint must return a 200 HTTP status code to MONEI. All other response codes, including 3xx codes, indicate to MONEI that you did not receive the event.

If MONEI does not receive a 200 HTTP status code, the notification attempt is repeated. After multiple failures to send the notification over multiple days, MONEI marks the request as failed and stops trying to send it to your endpoint.