Skip to main content

Build a custom checkout

Build your own custom checkout experience using MONEI Components to securely collect payment details for various methods directly on your site.

MONEI Payments Demo

Live demo

Source code

MONEI Components Key Features:

  • Securely collect payment details via iframes hosted by MONEI.
  • Generate a one-time paymentToken for secure server-side processing.
  • Available for plain JavaScript, React, Vue, Angular, and Svelte.
  • Support styling, language customization, and multiple payment methods.
  • Helps meet PCI DSS compliance requirements as sensitive data doesn't touch your server.

Before You Begin​

  • This guide covers integrating various payment method Components. If you prefer a simpler, no-code solution, consider the Prebuilt Payment Page.
  • You'll need a MONEI account and your API keys (test or live). Find them in your MONEI Dashboard.
  • Use your test mode keys for integration testing.
  • Ensure relevant payment methods are enabled in your account settings.
  • You can monitor test payments in your MONEI Dashboard → Payments (ensure Test Mode is active).

How It Works​

  1. Your backend creates a payment via the MONEI API and receives a payment.id
  2. The payment.id is passed to your client-side checkout page
  3. The customer enters payment details in a MONEI Component (secure iframe)
  4. monei.confirmPayment() sends the tokenized details to MONEI, which handles 3D Secure if needed
  5. MONEI sends the final payment status to your backend via webhook

Integration Steps​

1. Create Payment (Server-side)​

Create a Payment on your server with an amount and currency. Always decide the amount on the server side.

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

(Replace YOUR_API_KEY with your actual MONEI API key)

Key Parameters:

  • amount positive integer: Amount in the smallest currency unit.
  • currency string: Three-letter ISO currency code.
  • orderId string: Your unique order identifier.
  • callbackUrl string: Your server endpoint for webhook notifications.

Check all available request parameters.

The response contains payment.id. Pass this securely to your client-side for the next step.

2. Add Component to your payment page (Client-side)​

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/v3/monei.js"></script>
</head>
<body>
  <!-- Create an empty container for the card input -->
  <div id="card-element">
    <!-- A MONEI Card Input Component will be inserted here. -->
  </div>
  <!-- Your client-side script -->
  <script src="client.js"></script>
</body>

Create an empty DOM node (container) with a unique ID in your checkout page. Then, initialize the Component:

client.js
// Get paymentId passed securely from your server
const paymentId = '{{payment_id}}'; // Replace with actual paymentId

// Create an instance of the Card Input Component using the paymentId.
const cardElement = monei.CardInput({
  paymentId: paymentId
  // You can add other options like style, onFocus, onChange here
  // See MONEI Components reference for details
});

// Render the Component into the container
cardElement.render('#card-element');

// Next step: Confirm the payment (see below)

:::tip Alternative: initialize with Account ID You can also initialize CardInput with accountId + sessionId instead of paymentId to generate a token before creating the payment. This is useful for express checkout with shipping or subscription activation.

const cardElement = monei.CardInput({
  accountId: 'YOUR_ACCOUNT_ID',
  sessionId: 'unique_session_id'
});

When using this approach, pass the same sessionId when creating the payment server-side. See the MONEI Components reference for details. :::

3. Confirm the payment (Client-side)​

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

You need to provide the paymentId (obtained in Step 1) and a paymentToken generated with the Component.

client.js
// Assumes cardElement is the initialized CardInput component from Step 2

// Function to submit the card input and confirm the payment
async function handlePayment() {
  try {
    // Generate a payment token from the card input
    const {token, error} = await cardElement.submit();

    if (error) {
      // Inform the user if there was an error.
      console.error('Submit error:', error);
      return;
    }

    // Confirm the payment with the generated token
    const result = await monei.confirmPayment({
      paymentId: paymentId,
      paymentToken: token
    });

    // At this moment you can show a customer the payment result (e.g., redirect)
    // But you should ALWAYS rely on the result passed to the callback endpoint
    // on your server (Step 4) to update the final order status.
    console.log('Payment status (client-side):', result.status);
    // Example: window.location.href = '/thank-you?paymentId=' + paymentId;
  } catch (error) {
    console.error(error);
  }
}

// You would typically call handlePayment() when the user clicks your pay button.
// Example: document.getElementById('your-pay-button').addEventListener('click', handlePayment);

After you confirm the payment, MONEI handles any necessary steps like 3D Secure authentication.

:::note Alternative Flow As an alternative process, you can submit the generated paymentToken to your server and then confirm the payment server-side. :::

4. Process Webhook Notification (Server-side)​

After the client-side interaction and any necessary background processing (like 3D Secure or bank authorization), MONEI sends the final, authoritative payment status via an asynchronous HTTP POST request to the callbackUrl you provided in Step 1.

The request body contains the full Payment object in JSON format.

This webhook is the only reliable way to confirm the definitive payment outcome.

Crucially, you must:

  1. Verify the MONEI-Signature header included in the request. This confirms the webhook genuinely came from MONEI. See the Verify Signatures guide for implementation details.
  2. Return a 200 OK HTTP status code immediately upon receiving the webhook to acknowledge receipt. Any other status code tells MONEI the notification failed.

If MONEI doesn't receive a 200 OK, it will retry sending the webhook.

Once the signature is verified, inspect the status field in the Payment object (SUCCEEDED, FAILED, CANCELED, etc.) to determine whether to fulfill the order or handle the failure.

Before you go live​