# About the Order Payment Requests API

The Order Payment Requests API allows you to create payment requests for existing [eCommerce orders](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/sample-flows#send-a-payment-request-for-an-order-balance)
- [Retrieve and resend a payment URL](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/sample-flows#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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders)

@sdk_package_setup

# Order Payment Requests: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Send a payment request for an order balance

A customer placed an order but hasn't completed payment yet. You want to send them a payment link so they can pay the outstanding balance.

> **Prerequisite:** Add and publish a Payment Request Page on the site in the Wix Editor before using this flow.

To send a payment request for an order balance:

1. Call [Create Order Payment Request](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/create-order-payment-request) with the order ID, the amount to collect, a title, and a unique `source.externalId` that identifies this payment request in your system.
1. Save the `orderPaymentRequestUrl` from the response.
1. Send the URL to the customer through your preferred channel (for example, email or SMS).
1. Listen to the [Order Payment Request Paid](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/order-payment-request-paid) webhook to be notified when the customer completes payment.

## Retrieve and resend a payment URL

A customer tells you they lost the payment link you sent them. You want to retrieve the original URL and send it again.

To retrieve and resend a payment URL:

1. Call [Query Order Payment Requests](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/query-order-payment-requests) filtering by `orderId` and `status: "UNPAID"` to find the relevant payment request.
1. Save the `id` from the matching payment request.
1. Call [Get Order Payment Request URL](fallback::https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/get-order-payment-request-url) with the payment request ID.
1. Send the returned `orderPaymentRequestUrl` to the customer again.

Coding Examples

Sled Tests

Go Headless

Extend Websites with SDK

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

GraphQL (Alpha)