MONEI Widget

Follow @MONEI Star

The easiest way to accept payments from your customers.

Embed this widget on your website, blog or online store. It is easy to use, very secure, configurable, PCI compliant and mobile friendly.

To use the MONEI widget you need to be registered in MONEI Payment Gateway

Try out the MONEI Widget right now by clicking the button below! Use the following test card number: 5454545454545454, any future month and year for the expiration date, and any three-digit number for the CVC. Other test cards.

Quick links

Integration Examples Different payment methods SEPA Direct Debit Apple Pay Subscription mode Embedded mode How to get the payment status Advanced options Asynchronous mode Test Accounts List of supported configuration parameters

Integration

Insert this code before closing the </body> tag:

<script src="https://widget.monei.net/widget2.js"></script>

Generate the HTML code for your widget in MONEI dashboard.

Insert this code where you want your widget to show up:

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-name="My product" data-description="Product description" data-amount="100" data-currency="eur" data-checkout-text="Pay with Card" data-submit-text="Pay {amount}"> </div>

Examples

Use custom elements

Click me to pay with a Credit Card

<a href="#" class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-no-enhance> Click me to pay with a Credit Card </a> Back to top

Define the primary color

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-primary-color="#1990c6"> </div> Back to top

Show cardholder field

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-show-card-holder> </div> Back to top

Show address fields

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-show-billing-address> </div> Back to top

Localize - Show the widget in different language than english

Supported languages are: ar, be, bg, cn, cz, de, da, el, en, es, fi, fr, gr, hu, it, ja, ko, nl, no, pl, pt, ro, ru, sv, sk, sl, tr

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-show-card-holder data-checkout-text="Pagar {amount}" data-locale="es"> </div> Back to top

Force cardholder to equal billing name

By default the cardholder is displayed as one field. If this option is set then the form displays a field for the given name and a separate field for the surname. The values entered here will be submitted both as card.holder and as customer.givenName and customer.surname. Only works if data-show-card-holder is present.

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-amount="100" data-currency="eur" data-show-card-holder data-force-card-holder-equals-billing-name> </div> Back to top

Different payment methods

You can enable different card brands and additional payment methods like Paypal, Bitcoin, Alipay and SEPA. Supported brands and payment methods. To enable additional payment methods they should be configured in your sub account. Please contact support if you want to know more.

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-brands="VISA MASTER MAESTRO JCB PAYPAL BITCOIN ALIPAY" data-amount="100" data-currency="eur"> </div> Back to top

SEPA Direct Debit

MONEI allows to accept SEPA Direct Debit payments from customers in countries within the Single Euro Payments Area.

During the payment process, your integration collects your customer’s EUR-denominated IBAN bank account information. SEPA Direct Debits require the bank account holder to accept a mandate (debit authorization) that allows you to debit their account.

You can test it with DE23100000001234567890. Other test accounts.

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-brands="DIRECTDEBIT_SEPA" data-amount="100" data-currency="eur"> </div> Back to top

Apple Pay

MONEI allows Apple Pay to securely make payments on their iPhone, iPad, and Apple Watch.
The button will be visible only on apple devices that support Apple Pay. The page where the widget is embedded needs to be served via https.

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-brands="VISA MASTER APPLEPAY" data-amount="100" data-currency="eur"> </div> Back to top

Subscription mode

You can create recurrent payments and allow your customers to buy daily and monthly subscriptions.

To allow subscriptions through the widget you need to specify planId of the plan created in the MONEI dashboard. The amount and currency should be the same as in the specified plan.

<div class="monei-widget" data-token="{TOKEN}" data-plan-id="example-plan" data-redirect-url="https://static.monei.net/invoice.html" data-amount="4.99" data-currency="eur" data-checkout-text="Subscribe for {amount}" data-submit-text="Subscribe now!"> </div> Back to top

Embedded mode

You can render the payment form directly on your page. If a widget is rendered inside an iframe it is possible to redirect the iframe instead of main window. Only one form can be used on a page in embedded mode.

<div class="monei-widget" data-token="{TOKEN}" data-redirect-url="https://static.monei.net/invoice.html" data-payment-target="embedded_frame" data-shopper-result-target="embedded_frame" data-amount="100" data-currency="eur" data-popup="false"> </div> Back to top

How to get the payment status

To get the status of the payment, you should make a GET request to:

https://api.monei.net/checkouts/{id}?token={token}

IMPORTANT! If you're using the subscription mode, you have to call this endpoint to activate the subscription. If the payment is successful, the subscription will be activated.

https://api.monei.net/plans/{planId}/subscriptions/payment-status?token={token}&checkoutId={id}

you'll get id and token as query parameters appended to the redirect URL, planId should be the same as the one provided to the widget.

Read about the response structure and available parameters in documentation.

Advanced options

You can setup the widget using JavaScript

// Disables automatic setup for all DOM elements with monei-widget class
moneiWidget.disableAutoSetup();

// Setups widget when page is loaded.
document.addEventListener('DOMContentLoaded', function() {

  // Widget will be rendered to a container with id="my-widget"
  moneiWidget.setup('my-widget', {
    token: '{TOKEN}',
    redirectUrl: 'http://monei.net',
    amount: 100,
    currency: 'usd',
    name: 'Product title',
    description: 'Product description',
    autofocus: 'customer.email',
    test: true
  });
});

Provide additional information to the widget

moneiWidget.setup('widget1', {
  token: '{TOKEN}',
  redirectUrl: 'https://static.monei.net/invoice.html',
  amount: 100,
  currency: 'usd',
  name: 'Product title',
  description: 'Product description',
  customer: {
    email: 'example@email.com',
    givenName: 'John',
    middleName: 'Unknown',
    surname: 'Doe',
    sex: 'M',
    birthDate: '1970-02-17',
    phone: '+34666666666',
    mobile: '+34666666666',
    workPhone: '+34666666666',
    companyName: 'microapps SL',
    status: 'NEW',
    identificationDocType: 'PASSPORT',
    identificationDocId: '123456789',
  },
  billingAddress: {
    country: "US",
    state: "NY",
    city: "New York",
    postcode: "12345",
    street1: "Suite 1234",
    street2: "Some Road"
  },
  shipping: {
    country: "US",
    state: "NY",
    city: "New York",
    postcode: "12345",
    street1: "Suite 1234",
    street2: "Some Road",
    method: "LOWEST_COST",
    comment: "a comment left by customer"
  },
  showBillingAddress: true,
  customParameters: {
    foo: 'bar'
  }
});

Asynchronous mode

It is possible to avoid redirect and use JavaScript callback function to get transaction data right away. Asynchronous mode is available only for card payment brands without 3D secure!

moneiWidget.setup('widget1', {
  token: '{TOKEN}',
  amount: 100,
  currency: 'eur',
  redirect: false,
  onPaymentSuccess: function(data) {
    console.log('success', data);
  },
  onPaymentError: function(data) {
    console.log('error', data);
  }
});

Test Accounts

Credit Card Test Accounts

BrandNumberCVVExpiry Date
VISA 4200000000000000 (no 3D)
4711100000000000 (3D enrolled)
any 3 digits any date after today
MASTER 5454545454545454 (no 3D)
5212345678901234 (3D enrolled)
any 3 digits any date after today
AMEX 377777777777770 (no 3D)
375987000000005 (3D enrolled)
any 4 digits any date after today

Test Bank Accounts (SEPA)

CountryIBANBIC
Austria (AT) AT152011128161647502 GIBAATWWXXX
Germany (DE) DE23100000001234567890 MARKDEF1100
Spain (ES) ES9121000418450200051332 CAIXESBBXXX

List of supported configuration parameters

Change how the widget looks and behaves using the following configuration parameters:

You can either use data-dashed-case HTML attributes or a JavaScript object with camelCase options as setup() second parameter.

Required parameters

token Token generated for sub account in MONEI dashboard
amount The amount to be charged
currency The currency in which to charge. It should match your sub account currency.
redirectUrl After submitting the form a customer will be redirected to this url. Transaction id and token will be passed to this URL. How to get payment status. Only required if redirect: false is not specified.
redirect If false the user will not be redirected and onPaymentComplete callback will be called instead. It works only for card payment brands without 3D secure! If false it is required to specify onPaymentComplete or onPaymentSuccess callbacks.
Default: true
planId Id of the plan created in MONEI dashboard. Only required for subscription mode.

Payment parameters

brands String with space as delimiter. Supported brands and payment methods. To enable additional payment methods they should be configured in your sub account. Please contact support if you want to know more. Default: 'VISA MASTER'
paymentType PA (Preauthorization) or DB (Debit). Default is DB but it is possible to pass PA to enable preauthorisation payments that should be captured manually through the dashboard.
paymentTarget We submit the form to this target. In case of additional shopper interaction, e.g. 3DSecure, we redirect the shopper within this target. This only works for card payment brands.
shopperResultTarget Works only in combination with paymentTarget option. By default, we redirect the shopper to the given redirectUrl using a self-submitting form with target="_top". If you use a widget in an iframe and want to redirect the shopper within this iframe, then the shopperResultTarget and the paymentTarget should be the name of this iframe.
paymentType PA (Preauthorization) or DB (Debit). Default is DB but it is possible to pass PA to enable preauthorisation payments that should be captured manually through the dashboard.
merchantTransactionId Merchant-provided reference number, should be unique for your transactions. This identifier is often used for reconciliation.
merchantInvoiceId Merchant-provided invoice number, should be unique for your transactions. This identifier is not sent onwards.
transactionCategory The category of the transaction, possible values are:
EC - eCommerce
MO - Mail order
TO - Telephone order
RC - Recurring
IN - Installment
PO - pos
PM - mpos
customer

Information about the customer. It will be saved in the transaction. List of available fields.

html data attributes:
data-customer-email
data-customer-given-name
data-customer-middle-name
data-customer-surname
data-customer-sex
data-customer-birth-date
data-customer-phone
data-customer-mobile
data-customer-work-phone
data-customer-company-name
data-customer-identification-doc-type
data-customer-identification-doc-id
data-customer-status

billingAddress

Information about the customer billing address. It will be saved in the transaction. List of available fields.

html data attributes:
data-billing-country
data-billing-state
data-billing-city
data-billing-postcode
data-billing-street1
data-billing-street2

showBillingAddress Displays billing address fields. Fields are pre-filled form billingAddress object Default: false
mandatoryBillingFields Describe which billing fields cannot be empty. This option needs to be used with billingAddress option. Default: {country: true, state: true, city: true}
shipping

Information about the customer shipping address. It will be saved in the transaction. List of available fields.

html data attributes:
data-shipping-country
data-shipping-state
data-shipping-city
data-shipping-postcode
data-shipping-street1
data-shipping-street2
data-shipping-method
data-shipping-comment

customParameters Pass and object with any custom key/values. It will be saved in the transaction (each key will be prefixed with SHOPPER_)

Appearance parameters

popup Pass false to show a payment form directly on the page
name Product name in popup header
description Product description in popup header
checkoutText Checkout button text in popup mode, {amount} will be replaced with amount value with currency. Default: Pay {amount}
submitText Submit button text, {amount} will be replaced with amount value with currency. Default: Pay now
noEnhance Disables default styling for checkout button
showCardHolder Shows cardholder name input
forceCardHolderEqualsBillingName By default the cardholder is displayed as one field. If this option is set to true then the form displays a field for the given name and a separate field for the surname. The values entered here will be submitted both as card.holder and as customer.givenName and customer.surname. Only works if showCardHolder: true
showEmail Shows email input. If customer.email is provided input will be hidden automatically. Recommended. MONEI identifies customers by email. Default: true
locale Sets the language/country of the payment forms. Supported languages are: ar, be, bg, cn, cz, de, da, el, en, es, fi, fr, gr, hu, it, ja, ko, nl, no, pl, pt, ro, ru, sv, sk, sl, tr. By default detected by the browser.
autofocus Sets focus to the selected input/select element on the payment form upon loading. Example: autofocus: 'customer.email'
threeDIframeSize Sets size of the 3D secure iframe. This iframe will only be used in case a shopper has to enter 3D secure credentials on the bank's page. Example: {width: 100%, height: 580px}
threeDIframeFullscreen If true 3d secure frame will be rendered fullscreen. threeDIframeSize param will be ignored. Default: false
maskCvv Masks CVV field in payment form.
showCVVHint If set to true then the credit card form will display a hint on where the CVV is located when the mouse is hovering over the CVV field.
showLabels Shows input labels
showPlaceholders Shows input placeholders. Default: true
labels Overrides labels from the list of available labels.
errorMessages Overrides error messages from the list of available error messages.

Callback functions

If you are using advanced JavaScript mode it is possible to provide callback functions

onReady Triggers when all payment forms are ready
onError Callback that triggers if an error occurs during checkout.
onError: function(error){ /* function here */}
onAfterSubmit Triggers after the payment submission.
onBeforeSubmitCard Triggers before card payment submission. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.
onBeforeSubmitCard: function(event){ /* function here */}
onBeforeSubmitDirectDebit Triggers before direct debit payment submission. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.
onBeforeSubmitDirectDebit: function(event){ /* function here */}
onLoadThreeDIframe Triggers when the 3D secure targetIframe has loaded
onPaymentComplete Callback that triggers if payment is complete in asynchronous mode. Transaction data is passed as a first argument.
onPaymentComplete: function(data){ /* function here */}
onPaymentSuccess Callback that triggers if payment is successful in asynchronous mode. Transaction data is passed as a first argument.
onPaymentComplete: function(data){ /* function here */}
onPaymentError Callback that triggers if payment is not successful in asynchronous mode. Transaction data is passed as a first argument.
onPaymentComplete: function(data){ /* function here */}