site-level/Payments/Payment-Links/create id: site-level/Payments/Payment-Links/create metadata:

Resource: Wix Payment Links for Bookings

Description: This recipe provides specific implementation details for creating a payment link for a booking or order on a Wix site, focusing on critical requirements not explicitly covered in the standard documentation.

Documentation Links:

• REST API: https://dev.wix.com/api/rest/wix-payments/payment-links/create-payment-link
• SDK: https://dev.wix.com/api/sdk/wix-get-paid/paymentlinks
• Knowledge Base: https://dev.wix.com/docs/kb-only/payment-links-resources

Article: Best Practices for Booking Payment Links

This recipe focuses on specific implementation details and requirements for creating payment links for Wix Bookings that are not explicitly covered in the standard SDK documentation.

Critical Requirements:

• Correct AppId Usage:

  • You MUST use the eCommerce appDefId (1380b703-ce81-ff05-f115-39571d94dfcd) in the source.appId field.
  • Using any other ID (including the booking appDefId) will result in payment link creation failure.

• Payment Link Type:

  • You MUST set type: "ECOM_ORDER" for payment links related to bookings.
  • Using "ECOM" instead of "ECOM_ORDER" will prevent proper processing.

• Required Fields:

  • You MUST include paymentsLimit: 1 to limit the payment link to single use.
  • You MUST include displayData: {} as an empty object, unless specified otherwise.
  • You MUST use ecomOrderPaymentLink format rather than ecomPaymentLink.

• Price Formatting:

  • You MUST format amounts without unnecessary decimal places (e.g., "5" instead of "5.00").
  • Create a utility function to convert "5.00" to "5" while preserving necessary decimals.

• Two-Step Process Required:

  • You MUST use both createPaymentLink and sendPaymentLink methods in sequence.
  • First create the payment link with paymentLinks.createPaymentLink() to get a payment link ID.
  • Then send it to the contact using paymentLinks.sendPaymentLink(paymentLinkId, sendOptions).
  • The payment link will not be delivered to the customer without explicitly calling the send method.

Conditional Logic for Parameters:

• Order Integration:
  • "If an order exists related to the booking, you MUST use the order ID and order price."
  • "If an order exists, you MUST also use the order's currency instead of any default currency."
  • "If no order exists, you MUST create a custom payment link with the necessary details."

Error Handling:

• If the user reports errors when creating or sending payment links, you SHOULD first verify if the required permission "SCOPE.RESTAURANTS.MEGA-SCOPES" is added to the app.
• Common errors include authentication issues or insufficient permissions which can be resolved by adding the required permission.

IMPORTANT NOTES FOR THE CONSUMING LLM:

1. Correct AppId is Crucial:

   • You MUST use the eCommerce appDefId (1380b703-ce81-ff05-f115-39571d94dfcd) in the source.appId field.
   • Using any other ID will result in payment link creation failure.

2. Price Formatting:

   • You MUST format prices without unnecessary decimal places (e.g., "5" instead of "5.00").
   • This improves readability and user experience.

3. ECOM_ORDER Type:

   • You MUST use "ECOM_ORDER" as the type value, not "ECOM".
   • This ensures proper processing in the Wix payment system.

4. Required Fields:

   • You MUST include paymentsLimit: 1 and displayData: {} even if they seem optional.
   • These fields are required for proper functioning.

5. Order References:

   • When an order exists, you MUST reference it in both the ecomOrderPaymentLink.orderId and source.ecomReference.orderId.
   • When an order exists, you MUST use the order's currency (foundOrder.currency) for consistency.
   • When no order exists, you MUST omit these references.

6. Permissions:

   • The app MUST have "SCOPE.RESTAURANTS.MEGA-SCOPES" permission for complete functionality.
   • This permission is necessary for the payment link creation and sending process to work properly.
   • You SHOULD suggest to the user that they add this permission if they report errors related to payment link creation or sending.

7. No Order Status Updates Needed:

   • You should NOT manually update order status after sending a payment link.
   • The Wix payment system handles status updates automatically.