From 51d8871588d3347257079d44ef8e5a83fc1d6a69 Mon Sep 17 00:00:00 2001 From: Jan Vlnas Date: Fri, 17 Jul 2026 12:07:42 +0200 Subject: [PATCH 1/7] Payment automation rewrite --- connector-api/changelog/README.md | 8 + connector-api/use-cases/payment-automation.md | 504 ++++++++++++++++-- 2 files changed, 472 insertions(+), 40 deletions(-) diff --git a/connector-api/changelog/README.md b/connector-api/changelog/README.md index c6f043ff..3591ed79 100644 --- a/connector-api/changelog/README.md +++ b/connector-api/changelog/README.md @@ -1,6 +1,14 @@ # Changelog {% updates format="full" %} +{% update date="2026-07-22" %} + +## Payment automation use case documents Mews Payments Checkout + +- [Payment automation use case](../use-cases/payment-automation.md): + - Rewritten to document Mews Payments Checkout, the embeddable checkout for collecting payments and payment methods directly in your application. Covers the payment request and payment method request flows, loading configuration, callback events, styling, and testing. Documentation-only, no change to API. + +{% endupdate %} {% update date="2026-07-03" %} ## Clarified RollingReleaseOffset in availability blocks diff --git a/connector-api/use-cases/payment-automation.md b/connector-api/use-cases/payment-automation.md index 8247fef5..ae258dfe 100644 --- a/connector-api/use-cases/payment-automation.md +++ b/connector-api/use-cases/payment-automation.md @@ -1,65 +1,489 @@ # Payment automation -This section describes how to use automated payments processing. We also provide links to information on Mews PCI compliance, including current certification. For connecting to Mews Payment Terminals to take payments from customers, please refer to [Mews Payment Terminals](../use-cases/mews-terminals.md). +This section describes how to use Mews Payments Checkout, an embeddable checkout application that enables you to collect payments and payment methods directly within your own application, eliminating the need to redirect users to a separate Mews payment request page. The checkout handles all API communication for processing payments and recording data in Mews, including PCI-DSS compliant capture of payment card details. For connecting to Mews Payment Terminals to take payments from customers, please refer to [Mews Payment Terminals](../use-cases/mews-terminals.md). -> ### PCI Compliance +> #### PCI Compliance +> > * [Mews PCI compliance](https://help.mews.com/s/article/pci-compliance?language=en_US) > * [Mews PCI certificate](https://www.mews.com/en/platform-documentation) -## Using tokenized credit cards +## How it works -If the user interface of your solution involves the collection and storage of credit card details in a secure manner against the customer's profile in Mews, you can use [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card) and then [Charge credit card](../operations/creditcards.md#charge-credit-card) to securely take and post a payment into Mews. -The workflow mimics the result of a user manually [adding a new payment card](https://mews.force.com/s/article/add-a-new-payment-card?language=en_US) in Mews Operations and then [charging the card via the Mews payment gateway](https://help.mews.com/s/article/take-a-payment?language=en_US). +Mews Payments Checkout is a JavaScript SDK that renders a fully responsive payment experience inside an iframe injected into a container element on your page. You use the Mews Connector API to create a [payment request](../operations/paymentrequests.md#add-payment-requests) or a [payment method request](../operations/paymentmethodrequests.md#add-payment-method-request), then pass the returned identifier to the checkout application, which takes care of the rest – payment method selection, card data capture, 3D Secure authentication, and posting the resulting payment or payment method into Mews. -|
'How to' use case
| API Operations | -| :-- | :-- | -| How to add a credit card to the guest profile | [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card) | -| How to charge a guest credit card using Mews Payments | [Charge credit card](../operations/creditcards.md#charge-credit-card) | +Supported payment methods include payment cards, Apple Pay, Google Pay, iDEAL, and SEPA Direct Debit. -## Retrieving tokenized credit cards +The checkout supports two integration goals: -To check if a user's credit card is already attached to their customer profile, call [Get all credit cards](../operations/creditcards.md#get-all-credit-cards) to search for credit cards by the `CreditCardId` or `CustomerId`. The credit cards tokenized via the Mews Payment Gateway (PCI Proxy) can be identified by the [`Credit card kind`](../operations/creditcards.md#credit-card-kind) property, with the corresponding value being "Gateway". +* **Collect a payment** – charge the guest a specific amount, either against a pre-created payment request or directly with just an enterprise ID and amount. +* **Collect a payment method** – store a payment card or SEPA Direct Debit mandate against the guest profile, with consent, for future charges. -|
'How to' use case
| API Operations | -| :-- | :-- | -| How to check if a credit card is stored against a guest profile | [Get all credit cards](../operations/creditcards.md#get-all-credit-cards) | +Application updates are deployed automatically without requiring configuration changes on your side. -## Adding a tokenized credit card +## Step 1: Add the checkout loading script -### 1. Retrieve PublicKey +Add the Mews Payments Checkout script to your page. The script loads asynchronously and initializes the global `Mews.PaymentCheckout` object. -As an integration partner, you will not need to set up your own Payment Gateway account. Rather, when automating payments via the __Mews Connector API__, you should work with Mews' own account. To do so, call [Get configuration](../operations/configuration.md#get-configuration) to obtain the `PublicKey` value, found within the [payment card storage](../operations/configuration.md#payment-card-storage) object. This value will be used as the `merchantId` with the Mews Payment Gateway (PCI Proxy). +Script URL: `https://cdn.mews.com/payments/checkout-embed.js` -|
'How to' use case
| API Operations | -| :-- | :-- | -| How to get the merchant ID for the Mews Payment Gateway | [Get configuration](../operations/configuration.md#get-configuration) | +Place the following ` + ... + +``` -Refer to the [PCI Proxy documentation on Secure Fields](https://docs.pci-proxy.com/docs/secure-fields) for collecting card number, CVV and expiration date\* through the Secure Fields payment form. -Implement Quick Start Step 1 [Set up your Payment Form](https://docs.pci-proxy.com/docs/secure-fields-quick-start) and follow the **Secure Fields Form** recipe. As part of this process, you will use the Mews `PublicKey` (obtained in the step above) as the `merchantId`. -Take note of `data.transactionId` in the response, which looks like a series of numbers (e.g. `201028230732590232`). -For further assistance, see [Integration Examples](https://docs.pci-proxy.com/docs/secure-fields-examples). -Note you do _not_ need to follow Step 2 [Obtain the tokens](https://docs.pci-proxy.com/docs/secure-fields-quick-start), this step is performed instead by the Mews back-end. +## Step 2: Choose your payment flow -> **Expiration date:** -> Though not required by PCI Proxy, credit card expiration date is listed as a mandatory parameter on the [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card) endpoint so that it can be displayed within the customer profile in Mews. This can also be used as an additional validation method for the property to know if there is an expired card on file. -> To handle this, we recommend that the payment form includes a field for users to input their credit card expiration date, which need not be sent to PCI Proxy, but should be cached, so that the information can be included in the [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card) API request. +### Flow 1: Capture a payment request -### 3. Add the tokenized credit card to a customer profile in Mews +If you already have a guest profile in Mews, or guest details are collected before displaying the checkout and you don't want the guest to resubmit their information, use this flow to charge them a specific amount. The checkout renders only payment-related fields, as all guest details are already known. -Add the tokenized credit card to a customer profile in Mews by calling [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card). Enter the `transactionId` and obfuscated credit card details in the [credit card data](../operations/creditcards.md#credit-card-data) object. Take note of the `CreditCardId` in the API response. +To proceed, create a payment request for the desired amount and currency using [Add payment requests](../operations/paymentrequests.md#add-payment-requests). Take note of the payment request `Id` in the API response. -> **Obfuscated number:** -> `ObfuscatedNumber` should only contain at most the first six digits and last four digits of a credit card. Alternatively replacing the entire string value with 16 asterisks `*` is also acceptable. +When a payment request is created, by default Mews sends an email to the guest to fulfill the payment request. For the checkout use case, the guest sees the checkout immediately, so there's usually no need to send an additional email. To skip sending the email, set the `SendPaymentRequestEmails` property to `false` in the request. -The credit card will now be visible in the customer profile in Mews, under the __Payments > Credit cards__ section. -Note that while customer profiles are shared across all properties in a chain, credit card details are not. +```javascript +{ + "PaymentRequests": [ + { + ...payment request parameters... + } + ], + "SendPaymentRequestEmails": false +} +``` -## Charging the tokenized credit card +| 'How to' use case | API Operations | +| ----------------- | -------------- | +| How to create a payment request for the checkout | [Add payment requests](../operations/paymentrequests.md#add-payment-requests) | +| How to check the state of a payment request | [Get all payment requests](../operations/paymentrequests.md#get-all-payment-requests) | +| How to cancel an unfulfilled payment request | [Cancel payment requests](../operations/paymentrequests.md#cancel-payment-requests) | -Now that you have the `CreditCardid`, you can use the [Charge credit card](../operations/creditcards.md#charge-credit-card) endpoint to charge the customer. +### Flow 2: Capture a payment -> **Charge credit card:** -> Note the [Charge credit card](../operations/creditcards.md#charge-credit-card) operation actually charges the customer's credit card, whereas the [Add credit card payment](../operations/payments.md#add-credit-card-payment) operation does NOT. -> The latter simply records a credit card payment in Mews and does not trigger any additional action beyond Mews - suitable for when the customer's credit card has already been charged from your solution. +This flow removes the dependency on pre-creating a payment request and guest account in Mews. It is sufficient to provide an enterprise ID and the desired amount and currency to the checkout's loading configuration; the checkout application then collects the payer details automatically. After the guest clicks the pay button, a guest account is created in Mews, the payment method is collected, and the payment is created and linked to the guest's account. + +* **Option A: Express checkout** – a one-click payment option available for Apple Pay and Google Pay. The guest simply confirms the payment in their device's native interface, and the payment is created. All details are captured automatically. +* **Option B: Payment method selection** – for other payment methods (payment card, SEPA Direct Debit, iDEAL, etc.), the guest provides their payment method and billing details. A guest account is then created in Mews, and the payment is linked to it. + +## Step 3: Load the checkout application + +Once the `Mews.PaymentCheckout` object is initialized (Step 1) and the payment collection flow is selected (Step 2), load the checkout application using either the payment request ID from the API response (Flow 1) or a `context` object (Flow 2). + +Method: `Mews.PaymentCheckout.load(configuration)` + +### Configuration + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `containerId` | yes | string | The ID of the DOM element where the checkout application will be injected. | +| `requestId` | yes (for Flow 1) | GUID string | Payment request ID from [Flow 1: Capture a payment request](#flow-1-capture-a-payment-request), or payment method request ID when [collecting a payment method](#collecting-a-payment-method-for-future-charges). | +| `context` | yes (for Flow 2) | object | See [Context](#context). | +| `dataBaseUrl` | no | string | Use `https://app.mews-demo.com` for testing in the demo environment. See [Testing](#testing). | +| `onSuccess` | no | function | Callback invoked when a successful event occurs. See [Callback events](#callback-events). | +| `onFailure` | no | function | Callback invoked when a failure event occurs. See [Callback events](#callback-events). | +| `enableTracking` | no | boolean | When a guest declines cookies or tracking, set to `false` to prevent interaction tracking. Defaults to `true`. | +| `idealRedirectUrl` | no | string | Redirect URL after completing an iDEAL payment. Defaults to the current URL where the checkout is displayed. Must match the origin of the embedding site. | +| `paymentId` | no | GUID string | When provided, the application displays the current payment state. Used primarily for iDEAL payments after redirect upon guest confirmation. See [iDEAL payments](#ideal-payments). | +| `enabledPaymentMethods` | no | array | Limits available payment methods. Possible values: `paymentCard`, `ideal`, `sepaDirectDebit`, `applePay`, `googlePay`. See [Limit available payment methods](#limit-available-payment-methods). | +| `styles` | no | object | See [Style customization](#style-customization). | +| `layout` | no | object | See [Layout customization](#layout-customization). | +| `languageCode` | no | string | See [Language customization](#language-customization). | +| `multicurrency` | no | object | See [Multicurrency](#multicurrency). | +| `payer` | no | object | See [Billing details form display options](#billing-details-form-display-options). | +| ~~`paymentRequestId`~~ | no | GUID string | **Deprecated!** Use `requestId` instead. | +| ~~`onPaymentSuccess`~~ | no | function | **Deprecated!** Use `onSuccess` instead. Callback invoked when a payment is charged (or submitted, for SEPA payments). Receives the Mews payment ID (GUID string) as an argument. | +| ~~`onPaymentFailure`~~ | no | function | **Deprecated!** Use `onFailure` instead. Callback invoked when a payment error occurs. | + +#### Context + +Required for [Flow 2: Capture a payment](#flow-2-capture-a-payment). + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `enterpriseId` | yes | GUID string | The unique identifier of the enterprise (property) in Mews. | +| `amount` | yes | object | The amount to be charged. See [Amount](#amount). | + +#### Amount + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `currency` | yes | string | The currency of the payment, in ISO 4217 format (e.g. `USD`, `EUR`, `GBP`). The currency must be accepted by your property's configuration in Mews. | +| `value` | yes | number | The amount to be charged in the specified currency (e.g. `49.99`). | + +### Callback events + +The `onSuccess` callback is invoked when a payment or payment method collection succeeds. + +| Type | Parameter shape | Description | +| ---- | --------------- | ----------- | +| `payment-charged` | `{ type: "payment-charged", paymentId: string, paymentMethodId: string }` | Payment was charged successfully. | +| `payment-submitted` | `{ type: "payment-submitted", paymentId: string, paymentMethodId: string }` | Payment was submitted for processing. Only for SEPA Direct Debit payments. | +| `payment-method-collected` | `{ type: "payment-method-collected", paymentMethodId: string }` | Payment method was collected successfully. | + +The `onFailure` callback is invoked when a payment or payment method collection fails. + +| Type | Parameter shape | Description | +| ---- | --------------- | ----------- | +| `payment-failure` | `{ type: "payment-failure", error: string }` | Payment charge or submission failed. | +| `payment-method-collection-failure` | `{ type: "payment-method-collection-failure", error: string }` | Payment method collection failed. | + +### Examples + +Loading configuration example – Flow 1: Capture a payment request: + +```html + + + + ... + + + +
+ + + +``` + +Loading configuration example – Flow 2: Capture a payment: + +```javascript +window.Mews.PaymentCheckout.load({ + containerId: 'payment-checkout-container', + context: { + enterpriseId: 'fb4ac177-7829-4d63-9999-b003008db555', + amount: { + currency: 'EUR', + value: 100, + } + }, +}); +``` + +Example in a React application: + +```jsx +export const MewsPaymentCheckout = ({ paymentRequestId }: { paymentRequestId: string }) => { + const checkoutContainerRef = useRef(null); + + useEffect(() => { + if (!checkoutContainerRef.current) { + return; + } + window.Mews.PaymentCheckout.load({ + containerId: checkoutContainerRef.current.id, + requestId: paymentRequestId, + }); + }, [paymentRequestId]); + + return ( +
+ ); +}; +``` + +## Step 4: All done + +Setup is complete. The Mews Payments Checkout application handles all API communication for processing payments and recording data in Mews. + +The application renders inside an iframe injected into the container element specified in Step 3. The application is fully responsive and adapts to its container dimensions. If initialization or communication is blocked, please [contact support](../contact-support/README.md). + +## Testing + +To test the checkout application, set the `dataBaseUrl` configuration parameter in Step 3 to `https://app.mews-demo.com`. This loads the application in the Mews demo environment. + +> **Demo environment:** If you chose [Flow 1: Capture a payment request](#flow-1-capture-a-payment-request), the payment request (Step 2) must also be created in the Mews [demo environment](../guidelines/environments.md). + +## Collecting a payment method for future charges + +Instead of collecting a payment, you can use the checkout to collect a payment method with the guest's consent for future charges. The payment method is stored against the guest profile in Mews and can later be charged manually in Mews Operations, automatically via Mews automation, or programmatically via the Connector API. + +Currently supported payment methods for collection: payment card and SEPA Direct Debit. + +### 1. Create a payment method request + +Instead of creating a payment request, create a payment method request using [Add payment method request](../operations/paymentmethodrequests.md#add-payment-method-request). Take note of the `PaymentMethodRequestId` in the API response. + +> **Restricted!** The [Add payment method request](../operations/paymentmethodrequests.md#add-payment-method-request) operation is currently in beta-test and as such is subject to change. + +```javascript +{ + "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", + "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", + "Client": "Sample Client 1.0.0", + "AccountId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", + "ExpirationUtc": "2026-12-29T12:00:00Z", + "Description": "Payment method required", + "Notes": "Internal notes", + "PaymentMethods": ["PaymentCard", "SepaDirectDebit"], + "EmailsToSend": [] +} +``` + +> **Emails to send:** When a payment method request is created, Mews can email the guest to fulfill it. To disable all emails, send an empty list in `EmailsToSend`. Because the guest sees the checkout immediately, an empty array is the preferred value when collecting payment methods using the checkout. + +### 2. Load the checkout application + +Use the `PaymentMethodRequestId` from the API response as the `requestId` in the loading configuration, exactly as in [Step 3](#step-3-load-the-checkout-application). When the guest's payment method is successfully collected and stored in Mews, the `onSuccess` callback is triggered with type `payment-method-collected` and the `paymentMethodId` of the newly created payment method. + +```javascript +window.Mews.PaymentCheckout.load({ + containerId: 'payment-checkout-container', + requestId: 'd6737f7a-3244-4e9d-9790-b3fa00b21433', + onSuccess: (event) => { /* event.paymentMethodId */ } +}); +``` + +### 3. Charge the collected payment method + +Once collected, the payment method becomes available in the guest profile in Mews Operations, under **Payments > Payment methods**, and can be charged in three ways: + +* **Manually in Mews Operations** – property staff charge the stored payment method directly from the guest profile. +* **Automatically with Mews automation** – create a reservation using [Add reservations](../operations/reservations.md#add-reservations) and set `CreditCardId` in the [reservation parameters](../operations/reservations.md#reservation-parameters) to the received payment method ID. The payment method is then charged automatically by Mews according to the rate's [payment policy schedule](https://help.mews.com/s/article/how-to-set-up-payment-automation). +* **Programmatically via the Connector API** – charge the payment method directly using [Charge credit card](../operations/creditcards.md#charge-credit-card). This is currently supported only for collected payment cards. + +| 'How to' use case | API Operations | +| ----------------- | -------------- | +| How to request a payment method from a guest | [Add payment method request](../operations/paymentmethodrequests.md#add-payment-method-request) | +| How to charge a collected payment method on a reservation schedule | [Add reservations](../operations/reservations.md#add-reservations) | +| How to charge a collected payment card using Mews Payments | [Charge credit card](../operations/creditcards.md#charge-credit-card) | +| How to check if a payment method is stored against a guest profile | [Get all credit cards](../operations/creditcards.md#get-all-credit-cards) | + +> **Charge credit card:** Note the [Charge credit card](../operations/creditcards.md#charge-credit-card) operation actually charges the guest's payment card, whereas the [Add credit card payment](../operations/payments.md#add-credit-card-payment) operation does NOT. The latter simply records a credit card payment in Mews and does not trigger any additional action beyond Mews – suitable for when the guest's card has already been charged from your solution. + +## Additional use cases + +### Reloading + +To load a new payment request ID, call `Mews.PaymentCheckout.load(configuration)` with the updated configuration. The application detects changes and reloads the relevant parts automatically. + +### Removing the application + +To fully remove the checkout application from the screen, use the `Mews.PaymentCheckout.destroy()` method. + +### Displaying Apple Pay and Google Pay + +To enable Apple Pay in the checkout application, please [contact support](../contact-support/README.md) with the URL of the site embedding the application. Mews will configure this payment method for your site. Google Pay requires no configuration and is displayed automatically. + +Conditions that the guest's browser needs to fulfill to display these payment methods: + +| Payment method | Condition | +| -------------- | --------- | +| Apple Pay | Safari browser with a card in its Wallet | +| Google Pay | Chrome browser with an activated Google Pay card | + +### iDEAL payments + +When an iDEAL payment is selected, the guest is redirected to complete the payment. After completion, the guest returns to the embedding URL by default. The checkout application automatically uses a `paymentId` query parameter to display the payment result. + +To redirect to a different URL, set `idealRedirectUrl` when loading the application. The URL must match the origin of the embedding site. + +### Content Security Policy + +If a Content Security Policy (CSP) is configured on your site, enable the following domains for the checkout application to function correctly: + +* `*.mews.com` +* `https://www.recaptcha.net` +* `https://www.google.com/recaptcha/` +* `https://recaptcha.google.com/recaptcha/` +* `https://www.gstatic.com/recaptcha/` +* `https://pay.datatrans.com/upp/payment/js/secure-fields-2.0.0.min.js` + +> **PCI Proxy:** The `pay.datatrans.com` domain is required for PCI Proxy, the PCI-DSS compliant solution used by Mews Payments to process payment cards. + +### Language customization + +By default, the checkout displays text in the property's default language. To customize the application's language, load it with a specified language code from the [supported language codes](https://docs.mews.com/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes). + +```javascript +window.Mews.PaymentCheckout.load({ + containerId: 'payment-checkout-container', + requestId: '148f529f-d6e1-487d-9876-b369008af249', + languageCode: "es-ES", // Spanish localization +}); +``` + +### Limit available payment methods + +By default, all available payment methods are detected from the property's configuration in Mews, making them available for any checkout instance. To limit payment methods, load the checkout with the `enabledPaymentMethods` array. Possible values: `paymentCard`, `ideal`, `sepaDirectDebit`, `applePay`, `googlePay`. + +The checkout still verifies that each payment method is correctly configured and enabled in Mews, but limits the payment method selection to the specified setting. + +```javascript +window.Mews.PaymentCheckout.load({ + containerId: 'payment-checkout-container', + requestId: '148f529f-d6e1-487d-9876-b369008af249', + enabledPaymentMethods: ["paymentCard"], // offers only a payment card as an available payment method +}); +``` + +### Layout customization + +Layout customization is limited, as most elements are part of the Mews product, which ensures consistency and best practices across all implementations. + +| Configuration property | Expected value | Description | +| ---------------------- | -------------- | ----------- | +| `layout.hidden.surchargeSummary` | boolean | Hides the surcharge summary section. | +| `layout.hidden.paymentMethodHeader` | boolean | Hides the "Payment method" header. | + +### Multicurrency + +The Multicurrency (MCCY) feature allows guests to pay in their preferred currency rather than the property's default currency, helping to increase conversion rates and enhance the overall payment journey. + +When a guest opens the checkout, the currency is pre-selected – either automatically detected based on their location, or defaulting to the property's currency. If this currency differs from the guest's preferred one, they can change it at any time using the currency picker; the exchange rate and any applicable fees are transparently displayed before completing payment, and the displayed amount updates immediately, so what the guest sees is exactly what they pay. + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `multicurrency.enabled` | no | boolean | Enables multicurrency support, allowing the guest to see and pay in a currency different from the payment gateway account currency. | +| `multicurrency.autoDetect` | no | boolean | Enables automatic detection of the guest's local currency via their IP address. When enabled, the detected currency is pre-selected automatically. | + +> **Prerequisites:** Multicurrency can only be enabled in the checkout if the [multicurrency feature](https://help.mews.com/s/article/Multicurrency-by-Mews-Payments-FAQ) is enabled for the property in Mews. Currently, multicurrency is available only for [Flow 1: Capture a payment request](#flow-1-capture-a-payment-request). + +### Billing details form display options + +The billing details form is displayed automatically for [Flow 2: Capture a payment](#flow-2-capture-a-payment) to collect the payer details. The payer details are collected from this form, and when the guest clicks the pay button, a guest account is first created in Mews and a payment is then created for that account. + +If the guest details are known before loading the checkout, they can be passed to the loading configuration to avoid asking the guest for the same details twice. In this case, the billing details form is automatically hidden, as all details are already known. To display the provided details in the form instead, enable the `prefillDetails` option; the form is pre-filled so the guest can make any adjustments. + +The `payer` object: + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `details` | yes | object | The payer's billing information. When provided, the billing details form is not displayed. See [Details](#details). | +| `prefillDetails` | no | boolean | When enabled, the provided details are pre-filled into the form. | + +#### Details + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `lastName` | yes | string | The payer's last name (surname). | +| `firstName` | no | string | The payer's first name (given name). | +| `email` | yes | string | The payer's email address. Must be a valid email. | +| `telephone` | no | string | The payer's phone number. Must be a valid phone number when provided. | +| `address` | no | object | The payer's billing address. See [Address](#address). | + +#### Address + +| Parameter | Required | Type | Description | +| --------- | -------- | ---- | ----------- | +| `addressLine1` | no | string | First line of the billing address (street name and number). | +| `addressLine2` | no | string | Second line of the billing address (apartment, suite, unit, etc.). | +| `city` | no | string | City of the billing address. | +| `postalCode` | no | string | Postal / ZIP code of the billing address. | +| `countryCode` | no | string | Country of the billing address, as an ISO country code. | + +## Style customization + +To customize the visual appearance of the checkout application to align with your site's branding and theme, include a `styles` object within the configuration object when loading the application. + +```javascript +window.Mews.PaymentCheckout.load({ + containerId: 'payment-checkout-container', + requestId: '148f529f-d6e1-487d-9876-b369008af249', + styles: { /* style customization */ }, +}); +``` + +Style overrides are organized into sections, each enabling granular customization of specific components. All style overrides are optional; configure as many or as few properties as needed. All color overrides support hex values (3, 6, or 8 digits). The 8-digit hex format (`#RRGGBBAA`) includes an alpha/transparency channel, where the last two digits represent opacity (`00` = fully transparent, `FF` = fully opaque). + +> **Global application:** Styles are applied globally across the application. For example, modifying a text color affects all elements using that token throughout the application. Changing a single style property applies consistently across all related elements without requiring multiple configurations, but changes propagate throughout the application, so consider the effect of each modification carefully. + +### Global styles + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Text color primary | `global.textColorPrimary` | color hex value | +| Text color secondary | `global.textColorSecondary` | color hex value | +| Text color tertiary | `global.textColorTertiary` | color hex value | +| Border radius | `global.borderRadius` | number, 0–100 | +| Background color | `global.backgroundColor` | color hex value | +| Container min-width (default `320px`) | `global.container.minWidth` | px, rem, em, %, vw, vh | +| Container max-width (default `640px`) | `global.container.maxWidth` | px, rem, em, %, vw, vh | +| Container width (default `100%`) | `global.container.width` | px, rem, em, %, vw, vh | +| Container min-height (default `750px`) | `global.container.minHeight` | px, rem, em, %, vw, vh | + +### Payment method selection styles + +Payment method selection styles are organized into two groups: **selected** applies styling to the currently selected payment method, and **unselected** applies styling to all non-selected payment methods, allowing you to create visual contrast between available and active options. + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Selected: background color | `paymentMethodsSelection.selected.backgroundColor` | color hex value | +| Selected: border color | `paymentMethodsSelection.selected.borderColor` | color hex value | +| Selected: background color, hover state | `paymentMethodsSelection.selected.hover.backgroundColor` | color hex value | +| Selected: border color, hover state | `paymentMethodsSelection.selected.hover.borderColor` | color hex value | +| Selected: background color, active state | `paymentMethodsSelection.selected.active.backgroundColor` | color hex value | +| Unselected: border color | `paymentMethodsSelection.unselected.borderColor` | color hex value | +| Unselected: border color, hover state | `paymentMethodsSelection.unselected.hover.borderColor` | color hex value | +| Unselected: border color, active state | `paymentMethodsSelection.unselected.active.borderColor` | color hex value | + +### Button styles + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Background color | `button.backgroundColor` | color hex value | +| Text color | `button.textColor` | color hex value | +| Background color, hover state | `button.hover.backgroundColor` | color hex value | +| Background color, active state | `button.active.backgroundColor` | color hex value | +| Background color, disabled state | `button.disabled.backgroundColor` | color hex value | + +### Input styles + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Border color | `input.borderColor` | color hex value | +| Text color, error state | `input.error.textColor` | color hex value | +| Border color, error state | `input.error.borderColor` | color hex value | +| Border color, hover state | `input.hover.borderColor` | color hex value | +| Border color, focus state | `input.focus.borderColor` | color hex value | + +### Loading spinner styles + +The loading spinner component is composed of three distinct color properties that together form the visual indicator. Each color can be customized independently to match your brand palette. + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Primary color | `spinner.primaryColor` | color hex value | +| Secondary color | `spinner.secondaryColor` | color hex value | +| Tertiary color | `spinner.tertiaryColor` | color hex value | + +### Info banner styles + +The info banner displayed for certain payment methods, such as Apple Pay, Google Pay, iDEAL, and SEPA Direct Debit, can be customized to better match your theme. + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Background color | `infoBanner.backgroundColor` | color hex value | +| Icon color | `infoBanner.iconColor` | color hex value | + +### Status card styles + +The status card is displayed when the guest clicks the pay button, showing the current state of the payment. + +| Style property | Configuration property | Expected value | +| -------------- | ---------------------- | -------------- | +| Icon background color | `statusCard.iconBackgroundColor` | color hex value | + +### Out of scope for style customization + +The following aspects are not currently configurable via the public `styles` object: + +* **Layout and structure** – page layout, component positioning, and the overall flow of the checkout are fixed. The `styles` object only affects visual tokens (colors, border radius), not the layout engine. +* **Copy and content** – text labels, helper copy, error messages, and legal text. +* **Payment method behavior and ordering** – the order, visibility, and grouping of payment methods (e.g. cards vs. wallets vs. SEPA) are defined by business rules and product configuration, not theming. +* **Typography** – font family, size, and weight. + +### Design and accessibility best practices + +Aim for at least WCAG AA contrast (4.5:1) between `global.textColorPrimary` and `global.backgroundColor`, and between `button.textColor` and `button.backgroundColor`. Use `textColorPrimary` for primary information and labels, reserving `textColorSecondary` and `textColorTertiary` for supporting information, to avoid low-contrast UIs. + +Make sure hover and active states visibly differ from the default state, keep disabled buttons clearly distinguishable from active ones without resembling error states, and map the pay button to your brand's primary button style. Choose spinner colors that are clearly visible on the background and avoid pure red or error colors, to prevent implying a failure state while the payment is still processing. From 204a147c1709419b6461991d107b71c9008e2c8a Mon Sep 17 00:00:00 2001 From: Jan Vlnas Date: Fri, 17 Jul 2026 12:08:51 +0200 Subject: [PATCH 2/7] Update agents instructions on en dashes --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 31bcb52b..7db6a46a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,7 @@ Examples: - Remove filler words ("basically", "actually", "really", "in order to" → "to"). - Avoid words that downplay difficulty or assume something is obvious, such as "just", "simply", "obviously", "of course", "clearly", "easy", "everyone knows", and similar. - Prefer one precise sentence over two vague ones. +- Use **en dashes** (–), not em dashes (—), for parenthetical breaks and separators in prose and lists. ### 4. Structure and consistency From 1b38d7b1be2690013f141dc001eb73e6a5f4bc84 Mon Sep 17 00:00:00 2001 From: Jan Vlnas Date: Fri, 17 Jul 2026 12:09:27 +0200 Subject: [PATCH 3/7] Update how-to --- connector-api/use-cases/how-to.md | 1 - 1 file changed, 1 deletion(-) diff --git a/connector-api/use-cases/how-to.md b/connector-api/use-cases/how-to.md index 9a345754..c5d60978 100644 --- a/connector-api/use-cases/how-to.md +++ b/connector-api/use-cases/how-to.md @@ -39,7 +39,6 @@ This page summarises all of our 'how to' use cases, together with the main use c | How to add a credit card to the guest profile | [Add tokenized credit card](../operations/creditcards.md#add-tokenized-credit-card) | [Kiosk](kiosk.md), [Payment automation](payment-automation.md) | | How to get details of stored credit cards | [Get all credit cards](../operations/creditcards.md#get-all-credit-cards) | [Kiosk](kiosk.md), [Payment automation](payment-automation.md) | | How to check if a credit card is stored against a guest profile | [Get all credit cards](../operations/creditcards.md#get-all-credit-cards) | [Kiosk](kiosk.md), [Payment automation](payment-automation.md) | -| How to get the merchant ID for the Mews Payment Gateway | [Get configuration](../operations/configuration.md#get-configuration) | [Payment automation](payment-automation.md) | | How to record an external card payment | [Add credit card payment](../operations/payments.md#add-credit-card-payment) | [Kiosk](kiosk.md) | | How to record a general external payment | [Add external payment](../operations/payments.md#add-external-payment) | [Kiosk](kiosk.md) | | How to record an alternative external payment | [Add alternative payment](../operations/payments.md#add-alternative-payment) | [Kiosk](kiosk.md) | From 9f8e50c5c85d15ba0832513a1fbb6a11e97501ab Mon Sep 17 00:00:00 2001 From: Jan Vlnas Date: Fri, 17 Jul 2026 12:28:25 +0200 Subject: [PATCH 4/7] Fix formatting --- connector-api/use-cases/payment-automation.md | 125 ++++++++++++++---- 1 file changed, 100 insertions(+), 25 deletions(-) diff --git a/connector-api/use-cases/payment-automation.md b/connector-api/use-cases/payment-automation.md index ae258dfe..a6d41e56 100644 --- a/connector-api/use-cases/payment-automation.md +++ b/connector-api/use-cases/payment-automation.md @@ -2,10 +2,14 @@ This section describes how to use Mews Payments Checkout, an embeddable checkout application that enables you to collect payments and payment methods directly within your own application, eliminating the need to redirect users to a separate Mews payment request page. The checkout handles all API communication for processing payments and recording data in Mews, including PCI-DSS compliant capture of payment card details. For connecting to Mews Payment Terminals to take payments from customers, please refer to [Mews Payment Terminals](../use-cases/mews-terminals.md). -> #### PCI Compliance -> -> * [Mews PCI compliance](https://help.mews.com/s/article/pci-compliance?language=en_US) -> * [Mews PCI certificate](https://www.mews.com/en/platform-documentation) +{% hint style="info" %} + +#### PCI Compliance + +* [Mews PCI compliance](https://help.mews.com/s/article/pci-compliance?language=en_US) +* [Mews PCI certificate](https://www.mews.com/en/platform-documentation) + +{% endhint %} ## How it works @@ -20,7 +24,12 @@ The checkout supports two integration goals: Application updates are deployed automatically without requiring configuration changes on your side. -## Step 1: Add the checkout loading script +## Integration steps + +{% stepper %} +{% step %} + +### Step 1: Add the checkout loading script Add the Mews Payments Checkout script to your page. The script loads asynchronously and initializes the global `Mews.PaymentCheckout` object. @@ -35,9 +44,12 @@ Place the following `