Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

The payment ID returned by `createPayment()` or another app, such as Wix Pricing Plans' [`createOnlineOrder()`](wix-pricing-plans.html#createOnlineOrder).

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`](wix-pay-backend.Events.html#onPaymentUpdate)
 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()`](wix-pay-backend.html#createPayment) from your site's backend.
 
 

 To understand how `startPayment()` is used in a typical payment lifecycle,
 see [Typical Payment Lifecycle](wix-pay-frontend/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()`](wix-pay-backend.html#createPayment) 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.

/**************************
 * 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 wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  createMyPayment()
    .then((payment) => {
      wixPayFrontend.startPayment(payment.id);
    });
}

Start a payment on button click

/**************************
 * 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 wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  createMyPayment()
    .then((payment) => {
      wixPayFrontend.startPayment(payment.id);
    });
}

Start a payment on button click using quantity

/**************************
 * 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 wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  createMyPayment()
    .then((payment) => {
      wixPayFrontend.startPayment(payment.id)
        .then((result) => {
          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
          }
        });
    });
}

Start a payment on button click and handle status possibilities

/**************************
 * 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 wixPayFrontend from 'wix-pay-frontend';
import wixWindowFrontend from 'wix-window-frontend';

export function myButton_click(event, $w) {
  createMyPayment()
    .then( (payment) => {
      wixPayFrontend.startPayment(payment.id, {"showThankYouPage": false})
        .then( (result) => {
          if (result.status === "Successful") {
            wixWindowFrontend.openLightbox("Success Box");
          } else if (result.status === "Pending") {
            wixWindowFrontend.openLightbox("Pending Box");
          }
      } );
    } );
}

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

/**************************
 * 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 wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  createMyPayment()
    .then((payment) => {
      wixPayFrontend.startPayment(payment.id, {
        "termsAndConditionsLink": "https://mysite.com/terms"
      });
    });
}

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

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

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

export const createMyPayment = webMethod(Permissions.Anyone, async (productId) => {
  return wixData.get("productCollection", productId)
    .then( (product) => {
      return wixPayBackend.createPayment( {
        items: [{
          name: product.name,
          price: product.price
        }],
        amount: product.price
      } );
    } );
});

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

import { createMyPayment } from 'backend/pay.web';
import wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  createMyPayment(event.context.itemId)
    .then( (payment) => {
      wixPayFrontend.startPayment(payment.id);
    } );
}

Start a payment on button click using collection data

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

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

export const createMyPayment = webMethod(Permissions.Anyone, async (productId, quantity) => {
  return wixData.get("productCollection", productId)
    .then( (product) => {
      return wixPayBackend.createPayment( {
        items: [{
          name: product.name,
          price: product.price,
          quantity: quantity
        }],
        amount: product.price * quantity
      } );
    } );
});

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

import { createMyPayment } from 'backend/pay.web';
import wixPayFrontend from 'wix-pay-frontend';

export function myButton_click(event, $w) {
  let quantity = 2;

  createMyPayment(event.context.itemId, quantity)
    .then( (payment) => {
      wixPayFrontend.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](wix-pay-frontend.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()`](wix-pay-backend.html#createPayment) 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()`](wix-pay-frontend.html#startPayment)
    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()`](wix-pay-backend.Events.html#onPaymentUpdate) event.

 To use the Pay API, import `wixPayFrontend` from the `wix-pay-frontend` module:

   ```javascript
   import wixPayFrontend from 'wix-pay-frontend';
   ```

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

velo_wix-pay-frontend

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()`](wix-pay-frontend.Currencies.SiteSettings.html#getCurrencies) in that this function gets the complete list of all of the currencies that are supported on Wix sites. 
The [`siteSettings.getCurrencies()`](wix-pay-frontend.Currencies.SiteSettings.html#getCurrencies) function gets only the currencies that have been set for use in your site using the backend function [`siteSettings.setCurrencies()`](wix-pay-backend.Currencies.SiteSettings.html#setCurrencies).

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()`](wix-pay-frontend.Currencies.html#getAllCurrencies) to get a list of all the convertible currencies.


 + CurrencyConverter
   - Use [`convertAmounts()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-frontend/currencies/currency-converter/convert-amounts) to convert amounts between two currencies.
   - Use [`getConversionRate()`](wix-pay-frontend.Currencies.CurrencyConverter.html#getConversionRate) 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()`](wix-pay-backend.Currencies.SiteSettings.html#setCurrencies).
   - Use [`getCurrencies()`](https://dev.wix.com/docs/velo/api-reference/wix-pay-frontend/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

Gets conversion rates and converts amounts.

Use the CurrencyConverter object to get the currency conversion rates for any pair of supported currencies. You can also convert an array of amounts from one currency to another. 
The exchange rates are provided by [XE](https://www.xe.com/company/) on a daily basis and include the timestamp when they were set.

currencyConverter

Gets currencies that you set for your site.

You can get the currencies that you set your site to support using the backend function [`siteSetting.setCurrencies()`](wix-pay-backend.Currencies.html#sitesettings.setcurrencies). These are the currencies that are displayed in the [currency conversion](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores) element and used to convert currencies in your Wix Store.

The currency codes used must exist in the array returned by the [`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function.
> **Note:**  
For SiteSettings functions to work, your site must contain a Wix Stores page including the [currency conversion element](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores).

siteSettings

Contains functionality for displaying prices in your store in different currencies, getting exchange rates, and converting between currencies.

> **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.

To use the currencies functionality you must upgrade your site to a [Premium Plan](https://support.wix.com/en/article/upgrading-your-site-to-premium-3066683).

Currencies objects are used to convert from one currency to another, get exchange rates, and manage the currencies you want to work with on your site. The objects 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 objects 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()`](wix-pay-frontend.Currencies.html#getAllCurrencies) to get a list of all the convertible currencies.


 + CurrencyConverter
  - Use [`convertAmounts()`](wix-pay-frontend.Currencies.CurrencyConverter.html#convertAmounts) to convert amounts between two currencies.
   - Use [`getConversionRate()`](wix-pay-frontend.Currencies.CurrencyConverter.html#getConversionRate) 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()`](wix-pay-backend.Currencies.SiteSettings.html#setCurrencies).
   - Use [`getCurrencies()`](wix-pay-frontend.Currencies.SiteSettings.html#getCurrencies) to see the list of the currencies that you set.

   


> **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

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()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function.

from

Currency to convert to. The `to` currency code used must exist in the array returned by the [`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function.
> **Note:**
The `from` and `to` currency codes used must exist in the array returned by the 
[`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function.

ConvertedAmounts

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

Converts an array of amounts from one currency to another.

Use the `convertAmounts()` function to convert an array of one or more amounts between two currencies. 
The `convertAmounts()` function returns a Promise that resolves to a `ConvertedAmounts` object which contains an array of converted amounts and the timestamp for the conversion rate used. 
> **Note:**
The currency codes used must exist in the array returned by the 
[`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function.

convertAmounts

Fulfilled - The converted amounts and the timestamp for the conversion rate.

Gets a currency conversion rate.

The `getConversionRate()` function returns a Promise that resolves to a `ConversionRate` object, which contains the currency conversion rate between two currencies. The exchange rates are provided by [XE](https://www.xe.com/company/) on a daily basis and include the timestamp when they were set.
> **Note:** By using this function you agree to XE's [Terms of Use.](https://www.xe.com/en/legal/dfs.php)

getConversionRate

Fulfilled - The conversion rate between the source and target currencies and 
the timestamp when the rate was set.

CurrencyCode

Gets the list of supported currencies that you set for your site.

The `getCurrencies()` function returns a Promise that resolves to an array of currencies that were set for use in the site using the backend function [`siteSetting.setCurrencies()`](wix-pay-backend.Currencies.SiteSettings.html#setCurrencies). 
This function is different from the [`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function in that it gets only the currencies that have
been set for use in  this site using the [`siteSetting.setCurrencies()`](wix-pay-backend.Currencies.SiteSettings.html#setCurrencies) function.
The [`getAllCurrencies()`](wix-pay-frontend.Currencies.html#getAllCurrencies) function gets the complete list of all of the currencies that can be supported. 
> **Note:**
For SiteSettings functions to work, your site must contain a Wix Stores page including the [currency conversion element](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores).

getCurrencies

Fulfilled - The list of all currencies set for this site.

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()`](wix-pay-backend.html#createPayment) 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( )`](wix-pay-backend.html#createPayment) 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.

startPayment( )