About the Order Payment Requests API

The Order Payment Requests API allows you to create payment requests for existing eCommerce orders, enabling customers to pay an outstanding or partial balance. When you create a payment request, the response includes a payment page URL that you can share with the customer through your preferred channel.

With the Order Payment Requests API, you can:

• Create payment requests for existing orders and get a shareable payment page URL.
• Retrieve, update, and delete payment requests.
• Retrieve the payment page URL for an existing payment request at any time.
• Void payment requests that are no longer needed.
• Listen to webhooks when a payment request is paid, expired, or voided.

Payment request lifecycle

A new order payment request starts with a status of UNPAID. The status changes automatically based on the following:

• PAID: The customer completes payment on the payment page.
• EXPIRED: The expirationDate has passed. Expiration checks run periodically, so the status may change slightly after the expiration time.
• VOIDED: The payment request is voided using Void Order Payment Request.

If you don't set an expirationDate, the payment request never expires. If you set an expirationDate that's already in the past, the payment request is created immediately with a status of EXPIRED.

Only UNPAID payment requests can be updated or voided.

Before you begin

It's important to note the following points before starting to code:

• A Payment Request Page must be added and published on your site in the Wix Editor. Without it, calls to Create Order Payment Request fail with ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND.
• After creating a payment request, you're responsible for sharing the payment page URL with the customer. The URL is returned in the orderPaymentRequestUrl field of the create response. You can also retrieve it later using Get Order Payment Request URL.
• Payment request currency always matches the order's currency and can't be changed.

Use cases

• Send a payment request for an order balance
• Retrieve and resend a payment URL

Terminology

• Order payment request: A request for a customer to pay an outstanding or partial balance for an existing order. Associated with a payment page URL that the customer uses to complete payment.
• Payment Request Page: A page on the site where customers land when they open a payment request URL. Must be added and published in the Wix Editor before payment requests can be created.
• externalId: A reference to a record in the calling app's system (for example, a paylink ID or invoice ID). Required when creating a payment request.
• blockedPaymentMethods: A list of payment methods that can't be used to pay the request. Currently supports MANUAL only, which prevents customers from paying with manual payment methods.

See also

• eCommerce Orders API