> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # CreateOrderPaymentRequest # Package: orders # Namespace: OrderPaymentRequestsService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/create-order-payment-request.md ## Permission Scopes: Manage eCommerce - all permissions: SCOPE.DC-ECOM-MEGA.MANAGE-ECOM ## Introduction Creates an order payment request. The response includes the payment page URL, which you can share with the customer. To retrieve the URL later, call [Get Order Payment Request URL](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/get-order-payment-request-url.md). Creation fails with `ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND` if the site doesn't have a Payment Request Page added and published. --- ## REST API ### Schema ``` Method: createOrderPaymentRequest Description: Creates an order payment request. The response includes the payment page URL, which you can share with the customer. To retrieve the URL later, call [Get Order Payment Request URL](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/get-order-payment-request-url.md). Creation fails with `ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND` if the site doesn't have a Payment Request Page added and published. URL: https://www.wixapis.com/ecom/v1/order-payment-requests Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: orderPaymentRequest.title, orderPaymentRequest.orderId, orderPaymentRequest.amount Method parameters: param name: orderPaymentRequest | type: OrderPaymentRequest - name: source | type: Source | description: Details about the source that created the order payment request. | validation: immutable - name: appId | type: string | description: GUID of the app that created the order payment request. | validation: minLength 1, maxLength 100, format GUID, immutable - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID. | validation: minLength 1, maxLength 100, immutable - name: orderId | type: string | description: Order GUID. | required: true | validation: format GUID, immutable - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward. | required: true | validation: immutable - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: title | type: string | description: Title displayed to the customer on the payment page. | required: true | validation: minLength 1, maxLength 200 - name: description | type: string | description: Description displayed to the customer on the payment page. | validation: maxLength 300 - name: expirationDate | type: string | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire. | validation: format date-time, immutable - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: image | type: Image | description: Image to display to the customer on the payment page. - name: id | type: string | description: WixMedia image GUID. | validation: maxLength 200 - name: altText | type: string | description: Image alt text. | validation: maxLength 200 - name: blockedPaymentMethods | type: array | description: List of payment methods that can't be used for this order payment request. | validation: maxItems 1 - enum: - MANUAL: Manual payment. Return type: CreateOrderPaymentRequestResponse - name: orderPaymentRequest | type: OrderPaymentRequest | description: Created order payment request. - name: id | type: string | description: Order payment request GUID. | validation: format GUID - name: source | type: Source | description: Details about the source that created the order payment request. | validation: immutable - name: appId | type: string | description: GUID of the app that created the order payment request. | validation: minLength 1, maxLength 100, format GUID, immutable - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID. | validation: minLength 1, maxLength 100, immutable - name: status | type: Status | description: Payment request status. Set by the system. A new order payment request starts as `UNPAID`, unless `expirationDate` is already in the past at creation time, in which case it is created as `EXPIRED`. The system sets the status to `PAID` once payment is collected, `EXPIRED` when the expiration date passes, or `VOIDED` when the request is voided. - enum: - UNPAID: Payment is owed but hasn't been collected yet. - PAID: Payment has been collected. - EXPIRED: The order payment request has passed its `expirationDate` without being paid. - name: orderId | type: string | description: Order GUID. | validation: format GUID, immutable - name: orderNumber | type: string | description: Order number. | validation: maxLength 100 - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward. | validation: immutable - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: formattedAmount | type: string | description: Amount formatted with currency symbol. - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic format](http://en.wikipedia.org/wiki/ISO_4217). Always matches the order's currency. | validation: format CURRENCY - name: paymentGatewayOrderId | type: string | description: Payment gateway order GUID associated with this payment request. | validation: minLength 1, maxLength 100 - name: title | type: string | description: Title displayed to the customer on the payment page. | validation: minLength 1, maxLength 200 - name: description | type: string | description: Description displayed to the customer on the payment page. | validation: maxLength 300 - name: expirationDate | type: string | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire. | validation: format date-time, immutable - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: createdDate | type: string | description: Date and time the order payment request was created. | validation: format date-time - name: updatedDate | type: string | description: Date and time the order payment request was last updated. | validation: format date-time - name: image | type: Image | description: Image to display to the customer on the payment page. - name: id | type: string | description: WixMedia image GUID. | validation: maxLength 200 - name: height | type: integer | description: Original image height. - name: width | type: integer | description: Original image width. - name: altText | type: string | description: Image alt text. | validation: maxLength 200 - name: filename | type: string | description: Image filename. | validation: maxLength 200 - name: blockedPaymentMethods | type: array | description: List of payment methods that can't be used for this order payment request. | validation: maxItems 1 - enum: - MANUAL: Manual payment. - name: orderPaymentRequestUrl | type: string | description: Payment page URL for the order payment request. Share this URL with the customer so they can complete the payment. | validation: minLength 1, maxLength 100 Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND | Description: The Payment Request Page isn't published on the site. Add and publish a Payment Request Page in the Wix Editor. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_ORDER_STATUS_FOR_SUBSCRIPTION | Description: The order must have a status of `INITIALIZED` to create a payment request for a subscription order. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PARTIAL_PAYMENT_NOT_SUPPORTED_FOR_SUBSCRIPTION | Description: Partial payment isn't supported for orders with subscriptions. The `amount` must equal the order total. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SITE_NOT_PUBLISHED | Description: The site isn't published. ``` ### Examples ### Create Order Payment Request Creates an order payment request for an existing order, generating a payment page URL to share with the customer. ```curl curl -X POST \ 'https://www.wixapis.com/ecom/v1/order-payment-requests' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "orderPaymentRequest": { "orderId": "a931e280-254a-49a7-9641-22ef64c444ae", "amount": { "amount": "15.50" }, "title": "Balance Due for Order #10052", "description": "Remaining balance for your recent purchase", "expirationDate": "2026-07-15T23:59:59.000Z" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.ecom.orderPaymentRequests.createOrderPaymentRequest(options) Description: Creates an order payment request. The response includes the payment page URL, which you can share with the customer. To retrieve the URL later, call [Get Order Payment Request URL](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-payment-requests/get-order-payment-request-url.md). Creation fails with `ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND` if the site doesn't have a Payment Request Page added and published. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: options.orderPaymentRequest.title, options.orderPaymentRequest.orderId, options.orderPaymentRequest.amount Method parameters: param name: options | type: CreateOrderPaymentRequestOptions none - name: orderPaymentRequest | type: OrderPaymentRequest | description: Order payment request to create. - name: source | type: Source | description: Details about the source that created the order payment request. | validation: immutable - name: appId | type: string | description: GUID of the app that created the order payment request. | validation: minLength 1, maxLength 100, format GUID, immutable - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID. | validation: minLength 1, maxLength 100, immutable - name: orderId | type: string | description: Order GUID. | required: true | validation: format GUID, immutable - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward. | required: true | validation: immutable - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: title | type: string | description: Title displayed to the customer on the payment page. | required: true | validation: minLength 1, maxLength 200 - name: description | type: string | description: Description displayed to the customer on the payment page. | validation: maxLength 300 - name: expirationDate | type: Date | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire. | validation: immutable - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: image | type: string | description: Image to display to the customer on the payment page. - name: blockedPaymentMethods | type: array | description: List of payment methods that can't be used for this order payment request. | validation: maxItems 1 - enum: - MANUAL: Manual payment. Return type: PROMISE - name: _id | type: string | description: Order payment request GUID. | validation: format GUID - name: source | type: Source | description: Details about the source that created the order payment request. | validation: immutable - name: appId | type: string | description: GUID of the app that created the order payment request. | validation: minLength 1, maxLength 100, format GUID, immutable - name: externalId | type: string | description: Reference to a record in the source system. For example, if the payment request was created from a paylink or invoice, use this field to store the paylink GUID or invoice GUID. | validation: minLength 1, maxLength 100, immutable - name: status | type: Status | description: Payment request status. Set by the system. A new order payment request starts as `UNPAID`, unless `expirationDate` is already in the past at creation time, in which case it is created as `EXPIRED`. The system sets the status to `PAID` once payment is collected, `EXPIRED` when the expiration date passes, or `VOIDED` when the request is voided. - enum: - UNPAID: Payment is owed but hasn't been collected yet. - PAID: Payment has been collected. - EXPIRED: The order payment request has passed its `expirationDate` without being paid. - name: orderId | type: string | description: Order GUID. | validation: format GUID, immutable - name: orderNumber | type: string | description: Order number. | validation: maxLength 100 - name: amount | type: Price | description: Amount to collect. Set when the order payment request is created and can't be changed afterward. | validation: immutable - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: formattedAmount | type: string | description: Amount formatted with currency symbol. - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic format](http://en.wikipedia.org/wiki/ISO_4217). Always matches the order's currency. | validation: format CURRENCY - name: paymentGatewayOrderId | type: string | description: Payment gateway order GUID associated with this payment request. | validation: minLength 1, maxLength 100 - name: title | type: string | description: Title displayed to the customer on the payment page. | validation: minLength 1, maxLength 200 - name: description | type: string | description: Description displayed to the customer on the payment page. | validation: maxLength 300 - name: expirationDate | type: Date | description: Date and time the order payment request expires. If not provided, the order payment request doesn't expire. | validation: immutable - name: extendedFields | type: ExtendedFields | description: Custom field data for this order payment request. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: _createdDate | type: Date | description: Date and time the order payment request was created. - name: _updatedDate | type: Date | description: Date and time the order payment request was last updated. - name: image | type: string | description: Image to display to the customer on the payment page. - name: blockedPaymentMethods | type: array | description: List of payment methods that can't be used for this order payment request. | validation: maxItems 1 - enum: - MANUAL: Manual payment. Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: ORDER_PAYMENT_REQUEST_PAGE_NOT_FOUND | Description: The Payment Request Page isn't published on the site. Add and publish a Payment Request Page in the Wix Editor. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_ORDER_STATUS_FOR_SUBSCRIPTION | Description: The order must have a status of `INITIALIZED` to create a payment request for a subscription order. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PARTIAL_PAYMENT_NOT_SUPPORTED_FOR_SUBSCRIPTION | Description: Partial payment isn't supported for orders with subscriptions. The `amount` must equal the order total. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SITE_NOT_PUBLISHED | Description: The site isn't published. ``` ### Examples ### Create an order payment request Creates an order payment request for an existing order and returns the payment page URL to share with the customer. ```javascript import { orderPaymentRequests } from '@wix/ecom'; const newOrderPaymentRequest = { orderId: 'a931e280-254a-49a7-9641-22ef64c444ae', amount: { amount: '15.50', }, title: 'Balance Due for Order #10052', description: 'Remaining balance for your recent purchase', expirationDate: '2026-07-15T23:59:59.000Z', }; export async function myCreateOrderPaymentRequestFunction() { try { const response = await orderPaymentRequests.createOrderPaymentRequest(newOrderPaymentRequest); console.log('Success! Created order payment request:', response.orderPaymentRequest); console.log('Payment URL:', response.orderPaymentRequestUrl); return response; } catch (error) { console.error(error); // Handle the error } } /* Promise resolves to: * { * "orderPaymentRequest": { * "_id": "3c8f1a2e-7b4d-4f9e-8c61-5d2e9a0b1c3f", * "status": "UNPAID", * "orderId": "a931e280-254a-49a7-9641-22ef64c444ae", * "orderNumber": "10052", * "amount": { * "amount": "15.50", * "formattedAmount": "$15.50" * }, * "currency": "USD", * "paymentGatewayOrderId": "e7a4b2c9-1f3d-4a8e-9b6c-2d5f8a1e4c7b", * "title": "Balance Due for Order #10052", * "description": "Remaining balance for your recent purchase", * "expirationDate": "2026-07-15T23:59:59.000Z", * "_createdDate": "2026-06-01T14:22:18.456Z", * "_updatedDate": "2026-06-01T14:22:18.456Z" * }, * "orderPaymentRequestUrl": "https://www.examplestore.com/payment-request-page/3c8f1a2e-7b4d-4f9e-8c61-5d2e9a0b1c3f" * } */ ``` ### createOrderPaymentRequest (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { orderPaymentRequests } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { orderPaymentRequests }, // Include the auth strategy and host as relevant }); async function createOrderPaymentRequest(options) { const response = await myWixClient.orderPaymentRequests.createOrderPaymentRequest(options); }; ``` ---