/wix-manage

Create Payment Links

This recipe shows how to create and manage payment links using the current Payment Links REST API.

Prerequisites

1. Site is premium.
2. Site is published.
3. Site is set up to accept payments (Wix Payments onboarding completed).
4. App has payment-link permissions.
5. Wix Stores is installed if you plan to charge for catalog products.

Required APIs

• Payment Links API: REST
• Products API: REST

Overview

Payment links are created at:

• POST https://www.wixapis.com/payment-links/v1/payment-links

Use one of these payment-link types:

• ECOM: charge for custom or catalog line items.
• ECOM_ORDER: collect payment for an existing unpaid eCommerce order.

Step 1: Retrieve product details (optional)

If you plan to use catalog items, fetch the product first.

Examples:

• Catalog V1: GET https://www.wixapis.com/stores/v1/products/{productId}
• Catalog V1 query: POST https://www.wixapis.com/stores/v1/products/query

{
  "query": {
    "paging": {
      "limit": 50,
      "offset": 0
    }
  }
}

Step 2: Create an ECOM payment link with custom line items

{
  "paymentLink": {
    "title": "Business Listing Fee",
    "description": "One-time listing fee",
    "currency": "USD",
    "type": "ECOM",
    "ecomPaymentLink": {
      "lineItems": [
        {
          "type": "CUSTOM",
          "customItem": {
            "name": "Listing Fee",
            "quantity": 1,
            "price": "200.00"
          }
        }
      ]
    }
  }
}

Step 3: Create an ECOM payment link with catalog items

{
  "paymentLink": {
    "title": "Product Payment",
    "currency": "USD",
    "type": "ECOM",
    "ecomPaymentLink": {
      "lineItems": [
        {
          "type": "CATALOG",
          "catalogItem": {
            "quantity": 1,
            "catalogReference": {
              "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
              "catalogItemId": "PRODUCT_ID",
              "options": {
                "variantId": "VARIANT_ID"
              }
            }
          }
        }
      ]
    }
  }
}

Step 4: Create an ECOM_ORDER payment link for an existing order

{
  "paymentLink": {
    "title": "Order Balance",
    "currency": "USD",
    "type": "ECOM_ORDER",
    "paymentsLimit": 1,
    "ecomOrderPaymentLink": {
      "orderId": "ORDER_ID",
      "amount": "50"
    }
  }
}

Step 5: Send payment link to recipients

Use:

• POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/send

Request body:

{
  "paymentLinkId": "PAYMENT_LINK_ID",
  "recipients": [
    {
      "contactId": "CONTACT_ID",
      "sendMethods": ["EMAIL_METHOD"]
    }
  ]
}

Step 6: Query and manage payment links

Query:

• POST https://www.wixapis.com/payment-links/v1/payment-links/query

{
  "query": {
    "filter": {
      "status": "ACTIVE"
    },
    "cursorPaging": {
      "limit": 50
    }
  }
}

Get one:

• GET https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}

Deactivate:

• POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/deactivate

Activate:

• POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/activate

Delete (only when no payments were received):

• DELETE https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}

Payment Link Statuses

Common Errors

Best Practices

1. Validate prerequisites first (premium, published, payments enabled).
2. Use ECOM for line-item collection and ECOM_ORDER for existing unpaid orders.
3. Use IDs from real entities (products, variants, contacts, orders).
4. Keep currency aligned with your business/order currency rules.
5. Persist payment-link IDs and monitor status via query/get methods.

Related Documentation

• Payment Links API Reference
• Payments Overview
• Products API Reference
• Send Payment Link