CodeAPI

wix-pay-backend

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

To process payments on your site, first set up your site to accept payments as described in 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.

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-backend module:

    import wixPay from 'wix-pay-backend';

Note

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

Table of Contents

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
PaymentRequestAn object representing a payment request.

createPayment( )

Creates a new payment.

Description

Before using the createPayment() function, you need to set up your site to accept payments. To learn more, see 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.

The createPayment() function returns a Promise that resolves to a Payment object when the payment has been created.

Creating a payment is the first step in the process of accepting a payment from a user. After creating the payment, call startPayment() from your site's client-side code using the payment ID returned by createPayment. The startPayment() function prompts the user to select a payment method and continue the payment process.

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

Note

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

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 createPayment(paymentRequest: PaymentRequest): Promise<Payment>
PARAMETERS
?
The kind of data the property stores.
paymentRequest
The information for the payment being created.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Payment>
Fulfilled - The created payment.

Examples

Create a new payment

/**************************
 * 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);
    } );
}

Create a new payment with custom currency

/**************************
 * 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,
    currency: "USD"
  }) ;
}

/********************
 * 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);
    } );
}

Create a new payment 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);
    } );
}

PaymentRequest

An object representing a payment request.

See Also

createPayment( ), PaymentItem

Syntax

type PaymentRequest = {
  amount: number
  currency: string
  items: PaymentItem
}
MEMBERS
?
The kind of data the property stores.
amount
number

Total payment request amount. Must equal the sum of the price properties in the items list while taking the quantity into account.

currency(Optional)
string

Payment request currency. A three-letter ISO-4217 currency code. Defaults to the currency defined by the site's Regional Settings.

items
List of payment request items.