Go Headless

Build Apps

Client

API Preview

test

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

The payment ID returned by `createPayment()` or another app, such as Wix Pricing Plans' [`createOnlineOrder()`](pricing-plans/checkout/create-online-order).

paymentId

string

options

PaymentOptions

Starts a payment.

Before using the startPayment() function, you will need to set up your site to
 accept payments. To learn more, see [About Accepting Payments](https://support.wix.com/en/article/about-accepting-payments).
 When setting up your site to accept payments, be sure to select the payment
 methods you want to offer and [set your payment currency](https://support.wix.com/en/article/setting-your-currency-for-accepting-payments).

 The `startPayment()` function returns a Promise that resolves to a `PaymentResult`
 object when the user completes the payment process. Only use this result for display purposes.
 For business decisions, such as updating collection data, use the [`onPaymentUpdate`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/events/on-payment-update)
 event.

 Starting a payment prompts the user to select a payment method and continue the
 payment process with the options specified in the `options` parameter.

 Before calling `startPayment()`, create a payment and generate a value for the `paymentId` parameter. You can do this by calling [`createPayment()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/create-payment) from your site's backend.



 To understand how `startPayment()` is used in a typical payment lifecycle,
 see [Typical Payment Lifecycle](pay/introduction#typical-payment-lifecycle).

 Use the `options` parameter to:

 + Determine whether a user info page is shown at the beginning of the process.
 + Determine whether a thank you page is shown at the end of the process.
 + Determine whether a terms and conditions affirmation checkbox and link are shown.

> **Notes:**
> + To work with the Pay API, you need to save and publish your site.
>
> + The backend [`createPayment()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/create-payment) function
>   takes a `PaymentInfo` parameter that defines the information for a payment.
>   For security reasons you should always create the `PaymentInfo` object
>   in backend code. Do not pass payment information from client-side code.
>   Doing so opens a vulnerability that a malicious user can exploit to change
>   payment information, such as the price of an item being purchased.
>   To learn more about how to keep your payment code secure, see
>   [Security Considerations When Working with Wix Code](https://support.wix.com/en/article/security-considerations-when-working-with-wix-code#code-visibility).
>
> + The `showThankYouPage` option only applies to your Wix site's [Thank You page](https://www.wix.com/velo/reference/$w/thankyoupage). In-app browsers have their own separate Thank You pages which are unaffected by this setting.

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, () => {
  return wixPayBackend.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
});

/********************
 * client-side code *
 ********************/

import { createMyPayment } from 'backend/pay.web';
import { pay } from "@wix/site-pay";

const wixClient = createClient({ host: site.host(), modules: { pay } });

document.getElementById('myButton').addEventListener('click', async function(event) {
  const payment = await createMyPayment();
  await wixClient.pay.startPayment(payment.id);
});
```

Start a payment on button click

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, () => {
  return wixPayBackend.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99,
      quantity: 2
    }],
    amount: 19.98
  });
});

/********************
 * client-side code *
 ********************/

import { createMyPayment } from 'backend/pay.web';
import { pay } from "@wix/site-pay";

const wixClient = createClient({ host: site.host(), modules: { pay } });

document.getElementById('myButton').addEventListener('click', async function(event) {
  const payment = await createMyPayment();
  await wixClient.pay.startPayment(payment.id);
});
```

Start a payment on button click using quantity

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, () => {
  return wixPayBackend.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
});

/********************
 * client-side code *
 ********************/

import { createClient } from "@wix/sdk";
import { site } from "@wix/site";
import { pay } from "@wix/site-pay";

const wixClient = createClient({
  host: site.host(),
  modules: { pay }
});

import { createMyPayment } from 'backend/pay.web';

document.getElementById('myButton').addEventListener('click', async function(event) {
  try {
    const payment = await createMyPayment();
    const result = await wixClient.pay.startPayment(payment.id);
    if (result.status === "Successful") {
      // handle payment success
    } else if (result.status === "Failed") {
      // handle payment failure
    } else if (result.status === "Pending") {
      // handle payment pending
    } else if (result.status === "Cancelled") {
      // handle user closing payment panel
    }
  } catch (error) {
    // handle error
  }
});
```

Start a payment on button click and handle status possibilities

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, () => {
  return wixPayBackend.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
});

/********************
 * client-side code *
 ********************/

import { createClient } from "@wix/sdk";
import { site } from "@wix/site";
import { pay } from "@wix/site-pay";
import { window } from "@wix/site-window";
import { createMyPayment } from 'backend/pay.web';

const wixClient = createClient({ 
  host: site.host(), 
  modules: { pay, window } 
});

document.getElementById('myButton').addEventListener('click', async function(event) {
  try {
    const payment = await createMyPayment();
    const result = await wixClient.pay.startPayment(payment.id, { "showThankYouPage": false });
    if (result.status === "Successful") {
      await wixClient.window.openLightbox("Success Box");
    } else if (result.status === "Pending") {
      await wixClient.window.openLightbox("Pending Box");
    }
  } catch (error) {
    console.error("Payment process failed", error);
  }
});
```

Start a payment on button click with a custom thank you page

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, () => {
  return wixPayBackend.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
});

/********************
 * client-side code *
 ********************/

import { createClient } from "@wix/sdk";
import { site } from "@wix/site";
import { pay } from "@wix/site-pay";

const wixClient = createClient({ host: site.host(), modules: { pay } });

import { createMyPayment } from 'backend/pay.web';

document.getElementById('myButton').addEventListener('click', async function(event) {
  try {
    const payment = await createMyPayment();
    await wixClient.pay.startPayment(payment.id, {
      "termsAndConditionsLink": "https://mysite.com/terms"
    });
  } catch (error) {
    console.error('Payment initiation failed', error);
  }
});
```

Start a payment on button click with a terms and conditions link

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, async (productId) => {
  // Placeholder for wixData.get
  const product = { name: "Sample Product", price: 100 }; // Hardcoded values
  return wixPayBackend.createPayment( {
    items: [{
      name: product.name,
      price: product.price
    }],
    amount: product.price
  } );
});

/********************
 * client-side code *
 ********************/

import { createClient } from "@wix/sdk";
import { site } from "@wix/site";
import { pay } from "@wix/site-pay";

const wixClient = createClient({ 
  host: site.host(), 
  modules: { pay } 
});

import { createMyPayment } from 'backend/pay.web';

document.getElementById('myButton').addEventListener('click', async function(event) {
  const productId = event.target.getAttribute('data-item-id');
  const payment = await createMyPayment(productId);
  await wixClient.pay.startPayment(payment.id);
});
```

Start a payment on button click using collection data

```javascript
/**************************
 * backend code - pay.web.js *
 **************************/

import { Permissions, webMethod } from 'wix-web-module';
import wixPayBackend from 'wix-pay-backend';

export const createMyPayment = webMethod(Permissions.Anyone, async (productId, quantity) => {
  // Placeholder function to simulate fetching product data
  const getProduct = (productId) => {
    return new Promise((resolve) => {
      resolve({
        name: "Sample Product",
        price: 100
      });
    });
  };

  return getProduct(productId)
    .then((product) => {
      return wixPayBackend.createPayment({
        items: [{
          name: product.name,
          price: product.price,
          quantity: quantity
        }],
        amount: product.price * quantity
      });
    });
});

/********************
 * client-side code *
 ********************/

import { createClient } from "@wix/sdk";
import { site } from "@wix/site";
import { pay } from "@wix/site-pay";
import { createMyPayment } from 'backend/pay.web';

const wixClient = createClient({ host: site.host(), modules: { pay } });

document.getElementById('myButton').addEventListener('click', async (event) => {
  let quantity = 2;
  let productId = event.target.getAttribute('data-item-id'); // Assuming the product ID is stored in a data attribute

  const payment = await createMyPayment(productId, quantity);
  await wixClient.pay.startPayment(payment.id);
});
```

Start a payment on button click using collection data and a quantity

startPayment

PaymentResult

# Introduction
To process payments on your site, first set up your site to accept payments
 as described in [About Accepting Payments](https://support.wix.com/en/article/about-accepting-payments).
 When setting up your site to accept payments, be sure to select the payment
 methods you want to offer and [set your payment currency](https://support.wix.com/en/article/setting-your-currency-for-accepting-payments). 
You can also set up a list of alternative currencies to display your prices in. Use the [currency objects](pay.Currencies.html) and the [currency conversion dropdown element](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores) to set up and display product prices in different currencies.

 ### Typical Payment Lifecycle

 The following list outlines the steps taken in a typical payment lifecycle:

 1. A site visitor clicks a button to start the payment process.
 1. The button's event handler calls a backend function.
 1. A `PaymentInfo` object containing information about
    the payment, such as the payment amount, is created in the backend function.
 1. The backend function calls [`createPayment()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/create-payment) using the
    `PaymentInfo` object and returns the generated
    `Payment` object to the calling client-side event handler.
 1. The event handler then calls the [`startPayment()`](pay/start-payment)
    function with the id from the `Payment` object, which opens
    the payment popup on your site.
 1. The site visitor enters the payment information.
 1. The event handler optionally handles the returned `PaymentResult`.
 1. Handle additional status updates to the payment transaction using the
    [`onPaymentUpdate()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/events/on-payment-update) event.

 To use the Pay API, import `wixPayFrontend` from the `@wix/site-pay` module:

   ```javascript
   import wixPayFrontend from '@wix/site-pay';
   ```

> **Note:**
 To work with the Pay API, you need to save and publish your site.

site-pay

Gets the list of all currencies for which Wix supports conversion.

The `getAllCurrencies()` function returns a Promise that resolves to an array of currencies.
The array lists all currencies for which Wix supports conversion and their symbols.
> **Note:** The `getAllCurrencies()` function is different from [`siteSettings.getCurrencies()`](pay/currencies/site-settings/get-currencies) in that this function gets the complete list of all of the currencies that are supported on Wix sites.
The [`siteSettings.getCurrencies()`](pay/currencies/site-settings/get-currencies) function gets only the currencies that have been set for use in your site using the backend function [`siteSettings.setCurrencies()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/currencies-site-settings/set-currencies).

getAllCurrencies

Fulfilled - The list of all supported currencies.

# Introduction
> **Note**: There is a [new version](https://www.wix.com/velo/reference/wix-ecom-v2/currencies) of the Currencies API. If you're already using this module in your code, it will continue to work.

The Currency API is used to convert from one currency to another, get exchange rates, and manage the currencies you want to work with on your site. The API can be used with the [currency conversion dropdown](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores) element on your Wix Stores page to display prices in a range of different currencies. 
Selecting a different currency from the dropdown on a Wix Stores page, automatically updates all of the prices displayed on your store's page to the selected currency. While the currency converter dropdown works with your Wix Stores pages, the Currencies API can be used on any page.
Currency rates are provided by [XE](https://www.xe.com/company/) and are updated on a daily basis. Rates are provided together with the timestamp when they were set.

 The currency API contains the following objects:

 + Currencies
	  - Use [`getAllCurrencies()`](pay/currencies/get-all-currencies) to get a list of all the convertible currencies.


 + CurrencyConverter
   - Use [`convertAmounts()`](pay/currencies/currency-converter/convert-amounts) to convert amounts between two currencies.
   - Use [`getConversionRate()`](pay/currencies/currency-converter/get-conversion-rate) to get today’s conversion rate for a pair of currencies.  


 + SiteSettings
   - Set the currencies to appear in your currency conversion dropdown using the backend function [`setCurrencies()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/currencies/site-settings/set-currencies).
   - Use [`getCurrencies()`](pay/currencies/site-settings/get-currencies) to see the list of the currencies that you set.

To use the Currencies API you must upgrade your site to a [Premium Plan](https://support.wix.com/en/article/upgrading-your-site-to-premium-3066683). 


> **Note:** 
> + The currency converter changes the displayed prices in your store for different currencies but does not change the payment currency. 
>   The payment is always made in the [currency set in your site's dashboard](https://support.wix.com/en/article/setting-your-currency-for-accepting-payments).
>        
>
> + By using these objects you agree to XE's [Terms of Use.](https://www.xe.com/en/legal/dfs.php)

Currencies

CurrencyConverter

SiteSettings

Currency

A 3-letter
 [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.

code

symbol

ConversionRate

The conversion rate between the source and target currencies.

rate

number

timestamp

ConvertAmountsOptions

amounts

Currency to convert from.  The `from` currency code used must exist in the array returned by the [`getAllCurrencies()`](pay/Currencies/get-All-Currencies) function.

from

Currency to convert to. The `to` currency code used must exist in the array returned by the [`getAllCurrencies()`](pay/currencies/get-all-currencies) function.
> **Note:**
The `from` and `to` currency codes used must exist in the array returned by the
[`getAllCurrencies()`](pay/currencies/get-all-currencies) function.

ConvertedAmounts

The date and time when the currency exchange rate was set.

CurrencyCode

Payment

amount

Payment currency. A three-letter
 [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.

currency

items

PaymentItem

name

price

quantity

Whether to show your site's [Thank You page](https://www.wix.com/velo/reference/$w/thankyoupage). Does not apply to Thank You pages for in-app browsers. Defaults to `true`.

showThankYouPage

boolean

Whether to skip the user info page. Defaults to `false`.
 The page will be skipped only if user info was passed to [`createPayment()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/create-payment) as
 a part of the `PaymentInfo` object.

skipUserInfoPage

Absolute URL of a terms and conditions
 page. If a link is present, an agreement checkbox will be presented alongside the link.

termsAndConditionsLink

An object representing information about the user. It will be used to prefill
 user info form during payment process.

 Deprecation note: Pass user information to [`createPayment( )`](https://dev.wix.com/docs/velo/api-reference/wix-pay-backend/create-payment) instead.

userInfo

PaymentUserInfo

payment

Payment status. One of:

 + "`Successful`": Payment was successfully received.
 + "`Pending`": Payment is pending payment provider approval.
 + "`Failed`": Payment has failed.
 + "`Chargeback`": Payment is chargeback.
 + "`Refunded`": Payment was fully refunded.
 + "`Offline`": Payment will be executed offline.
 + "`PartiallyRefunded`": Payment was partially refunded.
 + "`Cancelled`": Payment was cancelled and was not processed.
 + "`Undefined`": Payment status is pending payment provider input.

status

transactionId

An object representing information about the user.

User's country code. A three-letter
 [ISO-3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. Value
 is `null` if there is no country information.

country

User's email address. Value is `null` if
 there is no email address information.

email

User's first name. Value is `null` if
 there is no first name information.

firstName

User's last name. Value is `null` if
 there is no last name information.

lastName

User's phone number. Value is `null` if
 there is no phone number information.

convertAmounts( )