About the Order Billing API

The Order Billing API allows you to manage payments and refunds for Wix eCommerce orders. The API centralizes all payment-related capabilities for eCommerce orders, supporting a wide range of business use cases, including charging unpaid orders with saved payment methods, capturing and voiding authorized payments, and processing refunds.

With the Order Billing API, you can:

• Authorize payments for orders with saved payment methods.
• Capture or void authorized payments.
• Retrieve the refundability status of an order and check the amounts available for refund.
• Calculate the refundable amount for specific items, shipping, or additional fees, including taxes and discounts.
• Issue refunds for supported payment providers, and mark refunds performed on systems other than Wix as externally refunded.

After capturing a payment or issuing a refund with the Order Billing API, you can manage the records of these payments and refunds with the Order Transactions API.

Before you begin

It’s important to note the following before starting to code:

• At the moment, this API only supports payments from payment service providers. Paying with a gift card or by using a membership is not yet supported.
• Charging payments with this API is limited to saved payment methods and authorized payments only.
• Authorizing payments (delayed capture) is only available for Wix Payments.
• Capturing or voiding authorized payments is only supported for the full authorized amount. Partial captures or voids are not currently available.
• Most payment providers can be automatically refunded using the Refund Payments method. For unsupported payment providers, use the API to manually mark the payments as externally refunded. This ensures alignment between Wix and external systems.

Use cases

• Authorization and capture with a saved payment method
• Process the refund of an entire order
• Process the partial refund of an order
• Record a refund made on an external system

Terminology

• Regular payment: A standard payment processed via supported payment providers. This represents only monetary transactions, not gift cards or memberships.

• Offline payment: A payment not processed by Wix, but still recorded by Wix.

• Saved payment method: Card tokenization replaces sensitive card details with a secure, unique token to protect data during transactions and enable safer digital payments. You can specify that an item requires a saved payment method at checkout with the Catalog Service Plugin.

• Payment authorization: Authorization is the process of reserving funds on a customer's payment method to ensure the payment can be completed, without immediately charging the amount.

• Delayed capture: Allows businesses to charge the authorized amount at a later date. This is typically used for security deposits or order verification.

• Capture: The process of transferring the reserved funds from the customer to the business.

• Void: Cancels an authorized payment, and releases the reserved funds back to the customer's payment method.

• Refundability: Whether an order/payment is refundable. Possible reasons why an order/payment is not refundable include pending/rejected orders, payment provider issues, and more.

• Shipping refund: Refunding the amount charged for shipping fees.

• Additional fee refund: Refunding the amount charged for extra fees. This may include handling fees, gift wrapping fees, or other supplementary charges.

• Refund statuses:

  • SCHEDULED - Refund request acknowledged, and will be performed soon.
  • STARTED - Refund initiated on the payment provider side.
  • PENDING - Refund initiated on the payment provider side. This status is assigned by the payment provider.
  • SUCCEEDED - Refund transaction succeeded.
  • FAILED - Refund transaction failed.