How to Build a Wix Payment Integrations in Wix Studio

If you are building an eCommerce website in Wix Studio and your preferred payment gateway is not available in the default Wix payment providers list, you are not stuck. Wix provides a powerful extensibility layer through Velo and Service Plugins that makes it possible to connect a third-party payment provider to the native Wix checkout flow.

In this article, I will show how we built a working custom payment provider integration for Wix Studio using Plata by Mono (Monobank Acquiring) as a real example. The same approach can be adapted for other gateways as well, which makes this useful for anyone researching Wix integrations, Wix payments API, Wix Studio custom development, or custom payment providers for Wix Stores.

Why This Matters for Wix Studio Projects

A lot of merchants use Wix Studio for design flexibility, CMS control, and fast deployment. However, when it comes to payments, not every local or regional payment gateway is supported out of the box.

That creates a common problem:

• the merchant wants to keep using the native Wix checkout

• the preferred gateway is not listed in Accept Payments

• the business still needs refunds, transaction status updates, and a proper redirect-based payment flow

This is exactly where the Wix Payment Provider Service Plugin becomes valuable.

What We Built

For this implementation, we connected Plata by Mono to a Wix Studio store using a custom payment provider plugin. The result was:

• the payment method appeared inside the Wix dashboard

• the provider became available in native checkout

• Wix redirected the buyer to the Monobank payment page

• a webhook updated the transaction status after successful payment

• refunds could be initiated through the provider logic

In other words, this was not a fake button or external workaround. It was a real Wix payment integration built into the platform flow.

The Architecture

At a high level, the integration has four parts:

1. a payment provider service plugin config

2. a payment provider logic file

3. a backend wrapper that talks to the gateway API

4. a webhook endpoint that sends payment status back into Wix

This pattern is reusable for many other gateways, not only Monobank.

---

Step 1: Create a Payment Provider Service Plugin in Wix Studio

In Wix Studio, go to Public & Backend and add a new Service Plugin of type Payment.

This creates two main files:

• plugin-name-config.js

• plugin-name.js

The config file tells Wix how the provider should appear in the dashboard and checkout UI.

Example:

export function getConfig() {
  return {
    title: 'Plata by Mono',
    paymentMethods: [{
      hostedPage: {
        title: 'Plata by Mono',
        billingAddressMandatoryFields: ['EMAIL'],
        logos: {
          white: {
            svg: 'https://static.wixstatic.com/shapes/94b5e2_403ceb582027431cb92f38fd18d1843c.svg',
            png: 'https://www.monobank.ua/resources/img/favicon/favicon-32x32.png'
          },
          colored: {
            svg: 'https://static.wixstatic.com/shapes/94b5e2_403ceb582027431cb92f38fd18d1843c.svg',
            png: 'https://www.monobank.ua/resources/img/favicon/favicon-32x32.png'
          }
        }
      }
    }],
    credentialsFields: [{
      simpleField: {
        name: 'accountLabel',
        label: 'Account name (e.g. Main)'
      }
    }]
  };
}

This is the part that makes your provider show up in the Wix payment setup flow.

---

Step 2: Add the Payment Provider Logic

The main plugin file contains the logic Wix calls during payment operations. For a basic redirect-based gateway flow, the most important functions are:

• connectAccount()

• createTransaction()

• refundTransaction()

Here is the simplified structure:

export const connectAccount = async (options, context) => {
  return {
    accountId: 'Plata by Mono',
    accountName: 'Plata by Mono',
    credentials: { accountLabel: (options && options.credentials && options.credentials.accountLabel) || 'Main' }
  };
}

export const createTransaction = async (options, context) => {
  return await createMonoCheckout(options);
}

export const refundTransaction = async (options, context) => {
  return await createMonoRefund(options);
}

This is the bridge between Wix checkout and the external gateway.

---

Step 3: Call the Gateway API from Backend Code

Instead of putting API logic directly into the service plugin file, it is cleaner to use a backend wrapper. This keeps the code modular and easier to reuse for other Wix API integrations.

For Monobank, we used a backend helper like this:

import { fetch } from 'wix-fetch';

export async function monoRequest(method, endpoint, xToken, body = null) {
  const options = {
    method,
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      'X-Token': xToken,
      'X-Cms': 'Wix',
      'X-Cms-Version': '1.0'
    }
  };
  if (body && method !== 'GET') {
    options.body = JSON.stringify(body);
  }
  const response = await fetch(`https://api.monobank.ua${endpoint}`, options);
  const text = await response.text();
  let data = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch (e) {
    data = { raw: text };
  }
  return { ok: response.ok, status: response.status, data };
}

This wrapper is then used to create a payment invoice:

export async function createInvoice(xToken,payload){
return monoRequest('POST','/api/merchant/invoice/create',xToken,payload);}

---

Step 4: Create the Redirect Payment Session

When the buyer submits checkout, Wix calls createTransaction(). In our integration, we used that step to create a Monobank invoice and return the hosted payment page URL.

Example:

export async function createMonoCheckout(transactionRequest) {

const token = await getSecret('MONO');

const order = transactionRequest.order?.description || {};

const returnUrls = transactionRequest.order?.returnUrls || {};

const redirectUrl = returnUrls.successUrl || returnUrls.errorUrl || returnUrls.cancelUrl;

const webHookUrl = `${new URL(redirectUrl).origin}/_functions/updateMonoTransaction?wixTransactionId=${encodeURIComponent(transactionRequest.wixTransactionId)}`;

const body = {
amount: parseInt(order.totalAmount, 10),
ccy: 980,
paymentType: 'debit',
redirectUrl,
webHookUrl,
merchantPaymInfo: {
reference: transactionRequest.wixTransactionId,
destination: order.description || 'Wix Store order'
	}
};

const result = await createInvoice(token, body);
if (result.ok && result.data && result.data.invoiceId && result.data.pageUrl) {
return {

pluginTransactionId: result.data.invoiceId,
redirectUrl: result.data.pageUrl
	};
}

return {
reasonCode: 6000,
errorCode: 'GENERAL_ERROR',
errorMessage: 'Monobank create invoice failed'
	};
}

This is the core of the redirect flow. Wix gets a redirectUrl, sends the buyer to the payment page, and waits for the status update.

---

Step 5: Handle Webhooks and Push Status Back to Wix

This is one of the most important parts of any Wix payment API integration. After the buyer pays on the external gateway page, Wix still needs to know whether the transaction succeeded.

That is done with an HTTP function and submitEvent().

Example webhook handler:

import wixPaymentProviderBackend from 'wix-payment-provider-backend'; 
import { ok,badRequest } from 'wix-http-functions';

export async function post_updateMonoTransaction(request){

const response={headers:{'Content-Type':'application/json'}};
try{
const body=await request.body.json();
const wixTransactionId=(body&&body.reference)||(request.query&&request.query.wixTransactionId);
const pluginTransactionId=body&&body.invoiceId;
const status=body&&body.status; 

if(!wixTransactionId||!pluginTransactionId){response.body={error:'Missing wixTransactionId or invoiceId'};
return badRequest(response);}

if(status==='success'){await wixPaymentProviderBackend.submitEvent({event:{transaction:{wixTransactionId,pluginTransactionId}}});

response.body={ok:true};
return ok(response);}
response.body={ok:true,ignoredStatus:status};
return ok(response);}
catch(err){response.body={error:'Webhook handling failed'};
return badRequest(response);}}

Without this part, the buyer might complete payment but the order would not be properly marked as paid inside Wix.

---

Step 6: Add Refund Support

For a real production-ready integration, refund support matters. In our case, we mapped Wix refund requests to the Monobank cancel endpoint.

Example:

export async function createMonoRefund(refundRequest){

const token=await getSecret('MONO');
const payload={invoiceId:refundRequest.pluginTransactionId,extRef:refundRequest.wixRefundId};

if(refundRequest.refundAmount){payload.amount=parseInt(refundRequest.refundAmount,10);}

const result=await cancelInvoice(token,payload); if(result.ok){return
{pluginRefundId:refundRequest.wixRefundId||`mono-refund-${refundRequest.pluginTransactionId}`};}
return{reasonCode:6000,errorCode:'GENERAL_ERROR',errorMessage:'Monobank refund failed'};}

That makes the solution much closer to a complete Wix custom payment provider implementation.

Handling Currency for International Buyers

One challenge we ran into was currency handling. Plata by Mono settles in UAH, but the storefront was displaying prices in USD.

The practical solution was:

• keep storefront pricing in USD

• convert the order amount to UAH before creating the payment invoice

• let the buyer’s card issuer handle the final foreign exchange conversion

That way, the user can browse in dollars while the actual gateway payment still works in the provider’s required currency.

---

What We Learned

There are a few important takeaways from this build:

• Wix Studio is flexible enough to support custom payment providers

• the Wix Payment Provider Service Plugin is the right tool for native checkout integrations

• you do not need to rebuild checkout from scratch just because your gateway is not listed by default

• a well-structured backend wrapper plus webhook flow makes the integration maintainable

• the same architecture can be adapted to other regional or specialized gateways

---

Can This Be Turned Into a Wix App for Everyone?

This is an important distinction.

A custom Velo payment provider plugin like the one above works for a specific site implementation. It is perfect for custom client projects. However, if a payment provider wants all Wix merchants to see that gateway natively in their dashboards without manual code installation, the provider needs a different path through the official Wix Payment Service Provider integration route rather than just shipping a site-specific Velo implementation.

So the approach shown here is ideal for:

• custom Wix Studio development

• agency work

• one-off merchant integrations

• building proof-of-concept gateway support

---

Final Thoughts

If you are exploring Wix integrations, Wix payments API, or custom payment gateway integration for Wix Studio, this implementation shows that it is absolutely possible to bridge Wix checkout with a provider that is not available out of the box.

The key is understanding the Service Plugin architecture, the redirect transaction flow, and the webhook callback that returns payment status to Wix.

Once you understand that pattern, many gateways can be integrated in a similar way.

---

Need a Custom Payment Provider Integration for Wix?

Planning to use a payment provider that is not natively supported in Wix or Wix Studio?

We help businesses build custom Wix payment integrations, Wix API integrations, and Wix Studio checkout solutions tailored to their payment stack.

Need a custom integration for your payment provider? Contact us and let’s build it for your Wix site.

Contact US