Search.../

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. 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 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 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() 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.

Syntax

function startPayment(paymentId: string, [options: PaymentOptions]): Promise<PaymentResult>

startPayment Parameters

NAME
TYPE
DESCRIPTION
paymentId

string

The payment ID returned by createPayment().

options
Optional

PaymentOptions

Payment process options.

Returns

Fulfilled - The created payment.

Return Type:

Promise<PaymentResult>
NAME
TYPE
DESCRIPTION
payment

Payment

The payment.

status

string

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.
transactionId

string

ID of the payment transaction.

userInfo

PaymentUserInfo

An object representing information about the user.

Was this helpful?

Start a payment on button click

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixPayBackend from 'wix-pay-backend';
6
7export function createMyPayment() {
8 return wixPayBackend.createPayment({
9 items: [{
10 name: "Product Name",
11 price: 9.99
12 }],
13 amount: 9.99
14 });
15}
16
17
18/********************
19 * client-side code *
20 ********************/
21
22import {createMyPayment} from 'backend/pay';
23import wixPay from 'wix-pay';
24
25export function myButton_click(event, $w) {
26 createMyPayment()
27 .then( (payment) => {
28 wixPay.startPayment(payment.id);
29 } );
30}
Start a payment on button click using quantity

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixPayBackend from 'wix-pay-backend';
6
7export function createMyPayment() {
8 return wixPayBackend.createPayment({
9 items: [{
10 name: "Product Name",
11 price: 9.99,
12 quantity: 2
13 }],
14 amount: 19.98
15 });
16}
17
18
19/********************
20 * client-side code *
21 ********************/
22
23import {createMyPayment} from 'backend/pay';
24import wixPay from 'wix-pay';
25
26export function myButton_click(event, $w) {
27 createMyPayment()
28 .then( (payment) => {
29 wixPay.startPayment(payment.id);
30 } );
31}
Start a payment on button click and handle status possibilities

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixPayBackend from 'wix-pay-backend';
6
7export function createMyPayment() {
8 return wixPayBackend.createPayment( {
9 items: [ {
10 name: "Product Name",
11 price: 9.99
12 } ],
13 amount: 9.99
14 } );
15}
16
17
18/********************
19 * client-side code *
20 ********************/
21
22import {createMyPayment} from 'backend/pay';
23import wixPay from 'wix-pay';
24
25export function myButton_click(event, $w) {
26 createMyPayment()
27 .then( (payment) => {
28 wixPay.startPayment(payment.id)
29 .then( (result) => {
30 if (result.status === "Successful") {
31 // handle payment success
32 } else if (result.status === "Failed") {
33 // handle payment failure
34 } else if (result.status === "Pending") {
35 // handle payment pending
36 } else if (result.status === "Cancelled") {
37 // handle user closing payment panel
38 }
39 } );
40 } );
41}
Start a payment on button click with a custom thank you page

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixPayBackend from 'wix-pay-backend';
6
7export function createMyPayment() {
8 return wixPayBackend.createPayment({
9 items: [ {
10 name: "Product Name",
11 price: 9.99
12 } ],
13 amount: 9.99
14 } );
15}
16
17
18/********************
19 * client-side code *
20 ********************/
21
22import {createMyPayment} from 'backend/pay';
23import wixPay from 'wix-pay';
24import wixWindow from 'wix-window';
25
26export function myButton_click(event, $w) {
27 createMyPayment()
28 .then( (payment) => {
29 wixPay.startPayment(payment.id, {"showThankYouPage": false})
30 .then( (result) => {
31 if (result.status === "Successful") {
32 wixWindow.openLightbox("Success Box");
33 } else if (result.status === "Pending") {
34 wixWindow.openLightbox("Pending Box");
35 }
36 } );
37 } );
38}
Start a payment on button click with a terms and conditions link

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixPayBackend from 'wix-pay-backend';
6
7export function createMyPayment() {
8 return wixPayBackend.createPayment({
9 items: [{
10 name: "Product Name",
11 price: 9.99
12 }],
13 amount: 9.99
14 });
15}
16
17
18/********************
19 * client-side code *
20 ********************/
21
22import {createMyPayment} from 'backend/pay';
23import wixPay from 'wix-pay';
24
25export function myButton_click(event, $w) {
26 createMyPayment()
27 .then( (payment) => {
28 wixPay.startPayment(payment.id, {
29 "termsAndConditionsLink": "https://mysite.com/terms"
30 } );
31 } );
32}
Start a payment on button click using collection data

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixData from 'wix-data';
6import wixPayBackend from 'wix-pay-backend';
7
8export async function createMyPayment(productId) {
9 return wixData.get("productCollection", productId)
10 .then( (product) => {
11 return wixPayBackend.createPayment( {
12 items: [{
13 name: product.name,
14 price: product.price
15 }],
16 amount: product.price
17 } );
18 } );
19}
20
21
22/********************
23 * client-side code *
24 ********************/
25
26import {createMyPayment} from 'backend/pay';
27import wixPay from 'wix-pay';
28
29export function myButton_click(event, $w) {
30 createMyPayment(event.context.itemId)
31 .then( (payment) => {
32 wixPay.startPayment(payment.id);
33 } );
34}
Start a payment on button click using collection data and a quantity

Code Example

Copy Code
1/**************************
2 * backend code - pay.jsw *
3 **************************/
4
5import wixData from 'wix-data';
6import wixPayBackend from 'wix-pay-backend';
7
8export async function createMyPayment(productId, quantity) {
9 return wixData.get("productCollection", productId)
10 .then( (product) => {
11 return wixPayBackend.createPayment( {
12 items: [{
13 name: product.name,
14 price: product.price,
15 quantity: quantity
16 }],
17 amount: product.price * quantity
18 } );
19 } );
20}
21
22
23/********************
24 * client-side code *
25 ********************/
26
27import {createMyPayment} from 'backend/pay';
28import wixPay from 'wix-pay';
29
30export function myButton_click(event, $w) {
31 let quantity = 2;
32
33 createMyPayment(event.context.itemId, quantity)
34 .then( (payment) => {
35 wixPay.startPayment(payment.id);
36 } );
37}