CodeAPI

wix-pay

The wix-pay module contains functionality for working with payments from client-side code.

To process payments on your site, first set up your site to accept payments as described in About Accepting Payments.

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.
  2. The button's event handler calls a backend function.
  3. A PaymentRequest object containing information about the payment, such as the payment amount, is created in the backend function.
  4. The backend function calls createPayment() using the PaymentRequest object and returns the generated Payment object to the calling client-side event handler.
  5. The event handler then calls the startPayment() function with the id from the Payment object, which opens the payment popup on your site.
  6. The site visitor enters the payment information.
  7. The event handler optionally handles the returned PaymentResult.
  8. Handle additional status updates to the payment transaction using the onPaymentUpdate() event.

    To use the Pay API, import wixPay from the wix-pay module:

    import wixPay from 'wix-pay';

Table of Contents

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
PaymentAn object representing a payment.
PaymentItemAn object representing a payment item.
PaymentOptionsAn object representing the options of a payment.
PaymentResultAn object representing a payment result.
PaymentUserInfo

An object representing the user information entered in the payment dialog.

startPayment( )

Starts a payment.

Description

Before using the startPayment() function, you will need to set up your site to accept payments. To learn more, see About 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 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(), call createPayment() from your site's backend to create a payment and generate a value for the paymentId parameter.

To understand how startPayment() is used in a typical payment lifecycle, see Typical Payment Lifecycle.

Use the options parameter to:

  • 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.
  • Send additional customer information with the payment.

Note

The backend createPayment() function takes a PaymentRequest parameter that defines the information for a payment. For security reasons you should always create the PaymentRequest 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.

Syntax

function startPayment(paymentId: string, [options: PaymentOptions]): Promise<PaymentResult>
PARAMETERS
?
The kind of data the property stores.
paymentId
string
The payment ID from a createPayment() request.
options(Optional)
Payment process options.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<PaymentResult>
Fulfilled - The created payment.

Examples

Start a payment on button click

/**************************
 * backend code - pay.jsw *
 **************************/

import wixPay from 'wix-pay-backend';

export function createMyPayment() {
  return wixPay.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
}

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

import {createMyPayment} from 'backend/pay';
import wixPay from 'wix-pay';

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

Start a payment on button click and handle status possibilities

/**************************
 * backend code - pay.jsw *
 **************************/

import wixPay from 'wix-pay-backend';

export function createMyPayment() {
  return wixPay.createPayment( {
    items: [ {
      name: "Product Name",
      price: 9.99
    } ],
    amount: 9.99
  } );
}

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

import {createMyPayment} from 'backend/pay';
import wixPay from 'wix-pay';

export function myButton_click(event, $w) {
  createMyPayment()
    .then( (payment) => {
      wixPay.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 with a custom thank you page

/**************************
 * backend code - pay.jsw *
 **************************/

import wixPay from 'wix-pay-backend';

export function createMyPayment() {
  return wixPay.createPayment({
    items: [ {
      name: "Product Name",
      price: 9.99
    } ],
    amount: 9.99
  } );
}

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

import {createMyPayment} from 'backend/pay';
import wixPay from 'wix-pay';
import wixWindow from 'wix-window';

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

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

/**************************
 * backend code - pay.jsw *
 **************************/

import wixPay from 'wix-pay-backend';

export function createMyPayment() {
  return wixPay.createPayment({
    items: [{
      name: "Product Name",
      price: 9.99
    }],
    amount: 9.99
  });
}

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

import {createMyPayment} from 'backend/pay';
import wixPay from 'wix-pay';

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

Start a payment on button click using collection data

/**************************
 * backend code - pay.jsw *
 **************************/

import wixData from 'wix-data';
import wixPay from 'wix-pay-backend';

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

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

import {createMyPayment} from 'backend/pay';
import wixPay from 'wix-pay';

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

Payment

An object representing a payment.

See Also

startPayment( ), PaymentResult

Syntax

type Payment = {
  id: string
  amount: number
  currency: string
  items: Array<PaymentItem>
}
MEMBERS
?
The kind of data the property stores.
id
string
Payment transaction ID.
amount
number
Payment total amount.
currency
string

Payment currency. A three-letter ISO-4217 currency code.

items
Payment items.

PaymentItem

An object representing a payment item.

See Also

startPayment( )

Syntax

type PaymentItem = {
  name: string
  quantity: number
  price: number
}
MEMBERS
?
The kind of data the property stores.
name
string
Payment item name.
quantity
number
Payment item quantity.
price
number
Payment item price.

PaymentOptions

An object representing the options of a payment.

See Also

startPayment( )

Syntax

type PaymentOptions = {
  termsAndConditionsLink: string
  showThankYouPage: boolean
  userInfo: PaymentUserInfo
}
MEMBERS
?
The kind of data the property stores.
termsAndConditionsLink(Optional)
string

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

showThankYouPage(Optional)
boolean
Whether or not to show a thank you page. Defaults to true.
userInfo(Optional)
Information about the customer.

PaymentResult

An object representing a payment result.

See Also

startPayment( )

Syntax

type PaymentResult = {
  payment: Payment
  status: string
  transactionId: string
  userInfo: PaymentUserInfo
}
MEMBERS
?
The kind of data the property stores.
payment
The payment.
status
string

Payment status. One of: "Successful", "Pending", "Failed", "Chargeback", "Refunded", "Offline", "PartiallyRefunded", "Cancelled", "Undefined".

transactionId
string
ID of the payment transaction.
userInfo
User information.

PaymentUserInfo

An object representing the user information entered in the payment dialog.

See Also

startPayment( ), PaymentResult

Syntax

type PaymentUserInfo = {
  firstName: string
  lastName: string
  country: string
  phone: string
  email: string
}
MEMBERS
?
The kind of data the property stores.
firstName
string

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

lastName
string

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

country
string

User's country. A three-letter ISO-3166-1 country code. Value is null if there is no country information.

phone
string

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

email
string

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