> 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 # RefundPayments # Package: orders # Namespace: OrderBillingService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/refund-payments.md ## Permission Scopes: Manage Orders: SCOPE.DC-STORES.MANAGE-ORDERS ## Introduction Processes payment refunds by calling payment providers and creating refund transactions. Supports two refund methods: - **Automatic refunds**: Calls the payment provider's API to process the refund. - **External refunds**: Marks payments as refunded without calling providers (for manual provider-side refunds). Set `paymentRefunds.externalRefund = true` for external refunds when you've manually processed the refund and only need to update the order's transaction records. The method also handles restocking inventory and sending customer notifications when specified in `sideEffects`. --- ## REST API ### Schema ``` Method: refundPayments Description: Processes payment refunds by calling payment providers and creating refund transactions. Supports two refund methods: - **Automatic refunds**: Calls the payment provider's API to process the refund. - **External refunds**: Marks payments as refunded without calling providers (for manual provider-side refunds). Set `paymentRefunds.externalRefund = true` for external refunds when you've manually processed the refund and only need to update the order's transaction records. The method also handles restocking inventory and sending customer notifications when specified in `sideEffects`. URL: https://www.wixapis.com/ecom/v1/order-billing/refund-payments Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: orderId, paymentRefunds, paymentRefunds.paymentId, refundItems.lineItems.lineItemId, refundItems.lineItems.quantity, refundItems.additionalFees.additionalFeeId, sideEffects.restock.lineItems.lineItemId, sideEffects.restock.lineItems.quantity Method parameters: param name: customerReason | type: customerReason | description: Optional customer-provided reason for the refund for record-keeping purposes. param name: orderId | type: orderId | description: Order GUID to process refunds for. | required: true param name: paymentRefunds | type: array | description: Payment refunds specifying which payments to refund and their amounts. Set `externalRefund` to `true` for manual refunds processed outside the system. | required: true - name: paymentId | type: string | description: GUID of the payment to refund from the order's payment transactions. | required: true - name: amount | type: Price | description: Amount to refund from this payment. Not applicable for membership payments and gift card refunds where the full credit is refunded. - name: amount | type: string | description: Amount. - name: externalRefund | type: boolean | description: Whether this refund is processed externally through the payment provider's dashboard. + **Automatic refund** (`false`, default): Calls the payment provider's API to process the refund. The system handles the refund transaction and updates the payment status automatically. + **External refund** (`true`): Marks the payment as refunded without calling the provider's API. Use this when you've manually processed the refund and only need to update the order records. param name: refundItems | type: RefundItems - name: lineItems | type: array | description: Line items and their quantities to refund. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity of this product to refund. Cannot exceed the available refund quantity for this line item. - name: additionalFees | type: array | description: Additional fees and their amounts to refund. - name: additionalFeeId | type: string | description: Additional fee GUID to refund. - name: amount | type: Price | description: Amount of the additional fee to refund. If not specified, the full remaining refundable amount for this fee will be refunded. - name: shipping | type: ShippingRefund | description: Shipping amount to refund. - name: amount | type: Price | description: Amount of shipping charges to refund. If not specified, the full remaining refundable shipping amount will be refunded. param name: sideEffects | type: RefundSideEffects - name: restock | type: RestockSideEffects | description: Inventory restocking actions to perform alongside the refund. - name: lineItems | type: array | description: Items to add back to inventory when processing the refund. Use this to automatically restock returned items. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity to add back to inventory. Cannot exceed the quantity being refunded for this line item. - name: notifications | type: NotificationSideEffects | description: Customer notification actions for the refund. - name: sendCustomerEmail | type: boolean | description: Whether to send a refund confirmation email to the customer. The email includes refund details and any custom message provided. Default: `false` - name: customMessage | type: string | description: Custom message to include in the refund confirmation email sent to the customer. Use this to provide additional context about the refund, return instructions, or customer service information. Return type: RefundPaymentsResponse - name: refund | type: Refund | description: Complete refund information including refund GUID, status, and amounts processed. - name: id | type: string | description: Refund GUID. - name: transactions | type: array | description: List of transactions. - name: paymentId | type: string | description: GUID of the payment associated with this refund. - name: amount | type: Price | description: Refund amount. - name: amount | type: string | description: Amount. - name: formattedAmount | type: string | description: Amount formatted with currency symbol. - name: refundStatus | type: RefundStatus | description: Refund status. - enum: - PENDING: Refund was initiated on payment provider side. PENDING status was assigned by provider. - SUCCEEDED: Refund transaction succeeded. - FAILED: Refund transaction failed. - SCHEDULED: Refund request acknowledged, and will be executed soon. - STARTED: Refund was initiated on payment provider side. - name: refundStatusInfo | type: RefundStatusInfo | description: Optional details of current refund status. - name: paymentGatewayReasonCode | type: string | description: Reason code for the refund's current status. Learn more about [reason codes](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md). - name: description | type: string | description: Free text explanation of current refund status. - name: gatewayRefundId | type: string | description: Payment gateway's refund GUID. This field is only returned when the value of `external_refund` is `false`. - name: providerRefundId | type: string | description: GUID of the refund in the payment provider's system. For example, at PayPal, Square, Stripe, etc. Not returned for external refunds. - name: externalRefund | type: boolean | description: Whether refund was made externally and manually on the payment provider's side. - name: details | type: RefundDetails | description: Refund business details. - name: items | type: array | description: Order line item GUIDs and quantities that were refunded. - name: lineItemId | type: string | description: Line item GUID the refunded line item. - name: quantity | type: integer | description: Line item quantity refunded. - name: shippingIncluded | type: boolean | description: Whether the shipping fee was also refunded. - name: reason | type: string | description: Reason for the refund, provided by customer (optional). - name: lineItems | type: array | description: Line items that were refunded. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Refund quantity. - name: additionalFees | type: array | description: Additional fees that were refunded. - name: additionalFeeId | type: string | description: Additional fee GUID. - name: amount | type: Price | description: Refund amount. - name: shipping | type: ShippingRefund | description: Shipping amount that was refunded. - name: amount | type: Price | description: Refund amount. - name: createdDate | type: string | description: Date and time the refund was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: summary | type: AggregatedRefundSummary | description: Aggregated refund summary. - name: requestedRefund | type: Price | description: Total amount requested for refund. - name: pendingRefund | type: Price | description: Pending refund amount - the portion of `requestedRefund` that is still pending. - name: refunded | type: Price | description: Refunded amount - the portion of `requestedRefund` that refunded successfully. - name: failedRefundAmount | type: Price | description: Failed refund amount - the portion of `requestedRefund` that failed. - name: pending | type: boolean | description: Whether at least one refund transaction is still in `"PENDING"` status. - name: breakdown | type: RefundItemsBreakdown | description: Breakdown of refunded items. Available only after refund is complete. - name: lineItems | type: array | description: Refunded line items and the amount refunded for each. - name: lineItemId | type: string | description: GUID of the refunded line item. - name: totalRefundedAmount | type: Price | description: Total refunded amount for the line item. - name: requestingServiceAppId | type: string | description: GUID of the app that initiated this refund. - name: orderTransactions | type: OrderTransactions | description: Updated order transaction history reflecting all payments and refunds after processing. - name: orderId | type: string | description: Order GUID. - name: payments | type: array | description: Record of payments made to the merchant. - ONE-OF: - name: regularPaymentDetails | type: RegularPaymentDetails | description: Regular payment details. - ONE-OF: - name: creditCardDetails | type: CreditCardPaymentMethodDetails | description: Credit card details. - name: lastFourDigits | type: string | description: The last 4 digits of the card number. - name: brand | type: string | description: Card issuer's brand. - name: paymentOrderId | type: string | description: Wix Payments order GUID. - name: gatewayTransactionId | type: string | description: Payment gateway's transaction GUID. This field is only returned when the value of `offline_payment` is `false`. - name: providerTransactionId | type: string | description: Transaction GUID in the payment provider's system. For example, at PayPal, Square, Stripe, etc. Not returned for offline payments. - name: offlinePayment | type: boolean | description: Whether the payment was made offline. For example, when using cash or when marked as paid in the Business Manager. - name: status | type: TransactionStatus | description: Payment status. - enum: UNDEFINED, APPROVED, PENDING, PENDING_MERCHANT, CANCELED, DECLINED, REFUNDED, PARTIALLY_REFUNDED, AUTHORIZED, VOIDED - name: savedPaymentMethod | type: boolean | description: Whether there is a payment agreement that allows for future charges. - name: authorizationDetails | type: AuthorizationDetails | description: Authorization details. - name: delayedCapture | type: boolean | description: Whether the authorized payment is of a delayed capture. - name: authorizedDate | type: string | description: Date and time the payment was authorized in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: captures | type: array | description: List of captures associated with payment In case of failed it can be replaced with new one with PENDING or SUCCESS statuses - name: id | type: string | description: Capture GUID. - name: status | type: AuthorizationCaptureStatus | description: Status of this capture action - enum: - PENDING: Capture operation still in progress. - SUCCEEDED: Capture operation succeeded. - FAILED: Capture operation failed. - name: amount | type: Price | description: Amount of this capture - name: createdDate | type: string | description: Date and time the capture was initiated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: failureDetails | type: AuthorizationActionFailureDetails | description: In case of status is FAILED may contain failure details - name: failureCode | type: string | description: - name: void | type: AuthorizationVoid | description: Void associated with payment - name: status | type: AuthorizationVoidStatus | description: Status of this void action - enum: - PENDING: Void operation still in progress. - SUCCEEDED: Void operation succeeded. - FAILED: Void operation failed. - name: voidedDate | type: string | description: Date and time the void was initiated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: failureDetails | type: AuthorizationActionFailureDetails | description: In case of status is FAILED may contain failure details - name: reason | type: Reason | description: Reason of void action - enum: - MANUAL: Authorization was voided by user. - SCHEDULED: Authorization passed execution date. - name: scheduledAction | type: ScheduledAction | description: Scheduled action for this transaction - name: actionType | type: ActionType | description: Type of the action. - enum: VOID, CAPTURE - name: executionDate | type: string | description: The date and time of the action. - name: chargebacks | type: array | description: Record of chargebacks made by the buyer. - name: id | type: string | description: Chargeback GUID. - name: createdDate | type: string | description: Date and time the chargeback was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: updatedDate | type: string | description: Date and time the chargeback was updated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: amount | type: Price | description: Amount. - name: reversalAmount | type: Price | description: Reversal amount. Present only when status is REVERSED. - name: status | type: ChargebackStatus | description: Status. Default: `"APPROVED"`. - enum: - APPROVED: Chargeback was approved. - REVERSED: Chargeback was reversed. - name: externalId | type: string | description: External chargeback GUID. - name: platformFee | type: Price | description: Platform fee amount associated with this payment. - name: paymentMethodName | type: PaymentMethodName | description: Payment method with buyer and optional owner translations. Non-exhaustive list of supported values: + `CreditCard`, `Alipay`, `AstropayCash`, `AstropayDBT`, `AstropayMBT`, `Bitcoin`, `BitPay`, `Cash`, `ConvenienceStore`, `EPay`, `Fake`, `Giropay`, `IDeal`, `InPerson`, `Klarna`, `MercadoPago`, `Netpay`, `NordeaSolo`, `Offline`, `PagSeguro`, `PayEasy`, `PayPal`, `Paysafecard`, `Paysafecash`, `PointOfSale`, `Poli`, `Privat24`, `Przelewy24`, `RapidTransfer`, `Sepa`, `Skrill`, `Sofort`, `Trustly`, `Neteller`, `Unionpay`, `UniPay`, `Yandex` - name: buyerLanguageName | type: string | description: Translated payment method name in buyer language. - name: siteLanguageName | type: string | description: Translated payment method name in site owner language. - name: userDefinedName | type: UserDefinedPaymentMethodName | description: User-provided payment method name. When set, takes precedence over `buyerLanguageName` and `siteLanguageName`. - ONE-OF: - name: predefined | type: PredefinedPaymentMethod | description: Predefined payment method. - enum: - CASH: Cash payment. - BANK_TRANSFER: Bank transfer. - CHECK: Payment by check. - name: custom | type: string | description: Custom payment method name provided by user. For example, `"Wire transfer"`, `"Money order"`, `"Venmo"` or any other custom name. - name: giftcardPaymentDetails | type: GiftCardPaymentDetails | description: Gift card payment details. - name: giftCardPaymentId | type: string | description: Gift card payment GUID. - name: appId | type: string | description: GUID of the app that created the gift card. - name: voided | type: boolean | description: Whether the gift card is voided. - name: id | type: string | description: Payment GUID. - name: createdDate | type: string | description: Date and time the payment was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: updatedDate | type: string | description: Date and time the payment was last updated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: amount | type: Price | description: Payment amount. - name: refundDisabled | type: boolean | description: Whether refunds for this payment are disabled. + `true`: This payment is not refundable. + `false`: This payment may be refunded. However, this ultimately depends on the payment provider. - name: refunds | type: array | description: Record of refunds made to the buyer. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: PARTIAL_REFUND_FOR_MULTIPLE_LOCATIONS_NOT_ALLOWED | Description: Partial refunds with restocking aren't allowed for items with multiple inventory locations. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_RESTOCK_QUANTITY | Description: Line item restock quantity exceeds the available restock quantity. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_REFUND_QUANTITY | Description: Line item refund quantity exceeds the available refund quantity. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_SHIPPING_REFUND_AMOUNT | Description: Shipping refund amount exceeds the available refund amount. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_ADDITIONAL_FEE_REFUND_AMOUNT | Description: Additional fee refund amount exceeds the available refund amount. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_PAYMENT_REFUND_AMOUNT | Description: Payment refund amount exceeds the available refund amount. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SHIPPING_NOT_FOUND | Description: Couldn't find the shipping. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: ADDITIONAL_FEE_NOT_FOUND | Description: Couldn't find the additional fee. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: LINE_ITEM_NOT_FOUND | Description: Couldn't find the line item. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: PAYMENT_NOT_FOUND | Description: Couldn't find the payment. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: EXTERNAL_REFUND_EXPECTED | Description: Payment requires an external refund. Set `externalRefund` to `true` in the `paymentRefunds` array. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PAYMENT_NOT_REFUNDABLE | Description: Payment can't be refunded. ``` ### Examples ### Refund Payments Partial refund of payment ```curl curl -X POST \ 'https://www.wixapis.com/ecom/v1/order-billing/refund-payments' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "orderId": "585daa0c-08d2-42ae-bd6b-18fe59c75836", "paymentRefunds": [ { "paymentId": "c5e3f495-7de2-4033-9bd0-7eef76700d00", "amount": { "amount": "23.00" } } ], "sideEffects": { "restock": { "lineItems": [ { "lineItemId": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ] }, "notifications": { "sendCustomerEmail": true, "customMessage": "Sorry <3" } }, "refundItems": { "lineItems": [ { "lineItemId": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "additionalFees": [ { "additionalFeeId": "d3d9cafb-9e2d-4dae-8129-091df0a6c24f", "amount": { "amount": "1" } } ] } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.orders.OrderBillingService.refundPayments(orderId, options) Description: Processes payment refunds by calling payment providers and creating refund transactions. Supports two refund methods: - **Automatic refunds**: Calls the payment provider's API to process the refund. - **External refunds**: Marks payments as refunded without calling providers (for manual provider-side refunds). Set `paymentRefunds.externalRefund = true` for external refunds when you've manually processed the refund and only need to update the order's transaction records. The method also handles restocking inventory and sending customer notifications when specified in `sideEffects`. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: orderId, options.paymentRefunds, options.paymentRefunds.paymentId, options.refundItems.lineItems.lineItemId, options.refundItems.lineItems.quantity, options.refundItems.additionalFees.additionalFeeId, options.sideEffects.restock.lineItems.lineItemId, options.sideEffects.restock.lineItems.quantity, options Method parameters: param name: options | type: RefundPaymentsOptions none | required: true - name: paymentRefunds | type: array | description: Payment refunds specifying which payments to refund and their amounts. Set `externalRefund` to `true` for manual refunds processed outside the system. | required: true - name: paymentId | type: string | description: GUID of the payment to refund from the order's payment transactions. - name: amount | type: Price | description: Amount to refund from this payment. Not applicable for membership payments and gift card refunds where the full credit is refunded. - name: amount | type: string | description: Amount. - name: externalRefund | type: boolean | description: Whether this refund is processed externally through the payment provider's dashboard. + **Automatic refund** (`false`, default): Calls the payment provider's API to process the refund. The system handles the refund transaction and updates the payment status automatically. + **External refund** (`true`): Marks the payment as refunded without calling the provider's API. Use this when you've manually processed the refund and only need to update the order records. - name: sideEffects | type: RefundSideEffects | description: Additional actions to perform alongside the refund, such as restocking inventory or sending notifications. - name: restock | type: RestockSideEffects | description: Inventory restocking actions to perform alongside the refund. - name: lineItems | type: array | description: Items to add back to inventory when processing the refund. Use this to automatically restock returned items. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity to add back to inventory. Cannot exceed the quantity being refunded for this line item. - name: notifications | type: NotificationSideEffects | description: Customer notification actions for the refund. - name: sendCustomerEmail | type: boolean | description: Whether to send a refund confirmation email to the customer. The email includes refund details and any custom message provided. Default: `false` - name: customMessage | type: string | description: Custom message to include in the refund confirmation email sent to the customer. Use this to provide additional context about the refund, return instructions, or customer service information. - name: refundItems | type: RefundItems | description: Specific items being refunded including line items, shipping, and additional fees. - name: lineItems | type: array | description: Line items and their quantities to refund. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity of this product to refund. Cannot exceed the available refund quantity for this line item. - name: additionalFees | type: array | description: Additional fees and their amounts to refund. - name: additionalFeeId | type: string | description: Additional fee GUID to refund. - name: amount | type: Price | description: Amount of the additional fee to refund. If not specified, the full remaining refundable amount for this fee will be refunded. - name: shipping | type: ShippingRefund | description: Shipping amount to refund. - name: amount | type: Price | description: Amount of shipping charges to refund. If not specified, the full remaining refundable shipping amount will be refunded. - name: customerReason | type: string | description: Optional customer-provided reason for the refund for record-keeping purposes. param name: orderId | type: string | description: Order GUID to process refunds for. | required: true Return type: PROMISE - name: refund | type: Refund | description: Complete refund information including refund GUID, status, and amounts processed. - name: _id | type: string | description: Refund GUID. - name: transactions | type: array | description: List of transactions. - name: paymentId | type: string | description: GUID of the payment associated with this refund. - name: amount | type: Price | description: Refund amount. - name: amount | type: string | description: Amount. - name: formattedAmount | type: string | description: Amount formatted with currency symbol. - name: refundStatus | type: RefundStatus | description: Refund status. - enum: - PENDING: Refund was initiated on payment provider side. PENDING status was assigned by provider. - SUCCEEDED: Refund transaction succeeded. - FAILED: Refund transaction failed. - SCHEDULED: Refund request acknowledged, and will be executed soon. - STARTED: Refund was initiated on payment provider side. - name: refundStatusInfo | type: RefundStatusInfo | description: Optional details of current refund status. - name: paymentGatewayReasonCode | type: string | description: Reason code for the refund's current status. Learn more about [reason codes](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md). - name: description | type: string | description: Free text explanation of current refund status. - name: gatewayRefundId | type: string | description: Payment gateway's refund GUID. This field is only returned when the value of `external_refund` is `false`. - name: providerRefundId | type: string | description: GUID of the refund in the payment provider's system. For example, at PayPal, Square, Stripe, etc. Not returned for external refunds. - name: externalRefund | type: boolean | description: Whether refund was made externally and manually on the payment provider's side. - name: details | type: RefundDetails | description: Refund business details. - name: items | type: array | description: Order line item GUIDs and quantities that were refunded. - name: lineItemId | type: string | description: Line item GUID the refunded line item. - name: quantity | type: integer | description: Line item quantity refunded. - name: shippingIncluded | type: boolean | description: Whether the shipping fee was also refunded. - name: reason | type: string | description: Reason for the refund, provided by customer (optional). - name: lineItems | type: array | description: Line items that were refunded. - name: lineItemId | type: string | description: Line item GUID. - name: quantity | type: integer | description: Refund quantity. - name: additionalFees | type: array | description: Additional fees that were refunded. - name: additionalFeeId | type: string | description: Additional fee GUID. - name: amount | type: Price | description: Refund amount. - name: shipping | type: ShippingRefund | description: Shipping amount that was refunded. - name: amount | type: Price | description: Refund amount. - name: _createdDate | type: Date | description: Date and time the refund was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: summary | type: AggregatedRefundSummary | description: Aggregated refund summary. - name: requestedRefund | type: Price | description: Total amount requested for refund. - name: pendingRefund | type: Price | description: Pending refund amount - the portion of `requestedRefund` that is still pending. - name: refunded | type: Price | description: Refunded amount - the portion of `requestedRefund` that refunded successfully. - name: failedRefundAmount | type: Price | description: Failed refund amount - the portion of `requestedRefund` that failed. - name: pending | type: boolean | description: Whether at least one refund transaction is still in `"PENDING"` status. - name: breakdown | type: RefundItemsBreakdown | description: Breakdown of refunded items. Available only after refund is complete. - name: lineItems | type: array | description: Refunded line items and the amount refunded for each. - name: lineItemId | type: string | description: GUID of the refunded line item. - name: totalRefundedAmount | type: Price | description: Total refunded amount for the line item. - name: requestingServiceAppId | type: string | description: GUID of the app that initiated this refund. - name: orderTransactions | type: OrderTransactions | description: Updated order transaction history reflecting all payments and refunds after processing. - name: orderId | type: string | description: Order GUID. - name: payments | type: array | description: Record of payments made to the merchant. - ONE-OF: - name: regularPaymentDetails | type: RegularPaymentDetails | description: Regular payment details. - ONE-OF: - name: creditCardDetails | type: CreditCardPaymentMethodDetails | description: Credit card details. - name: lastFourDigits | type: string | description: The last 4 digits of the card number. - name: brand | type: string | description: Card issuer's brand. - name: paymentOrderId | type: string | description: Wix Payments order GUID. - name: gatewayTransactionId | type: string | description: Payment gateway's transaction GUID. This field is only returned when the value of `offline_payment` is `false`. - name: providerTransactionId | type: string | description: Transaction GUID in the payment provider's system. For example, at PayPal, Square, Stripe, etc. Not returned for offline payments. - name: offlinePayment | type: boolean | description: Whether the payment was made offline. For example, when using cash or when marked as paid in the Business Manager. - name: status | type: TransactionStatus | description: Payment status. - enum: UNDEFINED, APPROVED, PENDING, PENDING_MERCHANT, CANCELED, DECLINED, REFUNDED, PARTIALLY_REFUNDED, AUTHORIZED, VOIDED - name: savedPaymentMethod | type: boolean | description: Whether there is a payment agreement that allows for future charges. - name: authorizationDetails | type: AuthorizationDetails | description: Authorization details. - name: delayedCapture | type: boolean | description: Whether the authorized payment is of a delayed capture. - name: authorizedDate | type: Date | description: Date and time the payment was authorized in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: captures | type: array | description: List of captures associated with payment In case of failed it can be replaced with new one with PENDING or SUCCESS statuses - name: _id | type: string | description: Capture GUID. - name: status | type: AuthorizationCaptureStatus | description: Status of this capture action - enum: - PENDING: Capture operation still in progress. - SUCCEEDED: Capture operation succeeded. - FAILED: Capture operation failed. - name: amount | type: Price | description: Amount of this capture - name: _createdDate | type: Date | description: Date and time the capture was initiated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: failureDetails | type: AuthorizationActionFailureDetails | description: In case of status is FAILED may contain failure details - name: failureCode | type: string | description: - name: void | type: AuthorizationVoid | description: Void associated with payment - name: status | type: AuthorizationVoidStatus | description: Status of this void action - enum: - PENDING: Void operation still in progress. - SUCCEEDED: Void operation succeeded. - FAILED: Void operation failed. - name: voidedDate | type: Date | description: Date and time the void was initiated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: failureDetails | type: AuthorizationActionFailureDetails | description: In case of status is FAILED may contain failure details - name: reason | type: Reason | description: Reason of void action - enum: - MANUAL: Authorization was voided by user. - SCHEDULED: Authorization passed execution date. - name: scheduledAction | type: ScheduledAction | description: Scheduled action for this transaction - name: actionType | type: ActionType | description: Type of the action. - enum: VOID, CAPTURE - name: executionDate | type: Date | description: The date and time of the action. - name: chargebacks | type: array | description: Record of chargebacks made by the buyer. - name: _id | type: string | description: Chargeback GUID. - name: _createdDate | type: Date | description: Date and time the chargeback was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: _updatedDate | type: Date | description: Date and time the chargeback was updated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: amount | type: Price | description: Amount. - name: reversalAmount | type: Price | description: Reversal amount. Present only when status is REVERSED. - name: status | type: ChargebackStatus | description: Status. Default: `"APPROVED"`. - enum: - APPROVED: Chargeback was approved. - REVERSED: Chargeback was reversed. - name: externalId | type: string | description: External chargeback GUID. - name: platformFee | type: Price | description: Platform fee amount associated with this payment. - name: paymentMethodName | type: PaymentMethodName | description: Payment method with buyer and optional owner translations. Non-exhaustive list of supported values: + `CreditCard`, `Alipay`, `AstropayCash`, `AstropayDBT`, `AstropayMBT`, `Bitcoin`, `BitPay`, `Cash`, `ConvenienceStore`, `EPay`, `Fake`, `Giropay`, `IDeal`, `InPerson`, `Klarna`, `MercadoPago`, `Netpay`, `NordeaSolo`, `Offline`, `PagSeguro`, `PayEasy`, `PayPal`, `Paysafecard`, `Paysafecash`, `PointOfSale`, `Poli`, `Privat24`, `Przelewy24`, `RapidTransfer`, `Sepa`, `Skrill`, `Sofort`, `Trustly`, `Neteller`, `Unionpay`, `UniPay`, `Yandex` - name: buyerLanguageName | type: string | description: Translated payment method name in buyer language. - name: siteLanguageName | type: string | description: Translated payment method name in site owner language. - name: userDefinedName | type: UserDefinedPaymentMethodName | description: User-provided payment method name. When set, takes precedence over `buyerLanguageName` and `siteLanguageName`. - ONE-OF: - name: predefined | type: PredefinedPaymentMethod | description: Predefined payment method. - enum: - CASH: Cash payment. - BANK_TRANSFER: Bank transfer. - CHECK: Payment by check. - name: custom | type: string | description: Custom payment method name provided by user. For example, `"Wire transfer"`, `"Money order"`, `"Venmo"` or any other custom name. - name: giftcardPaymentDetails | type: GiftCardPaymentDetails | description: Gift card payment details. - name: giftCardPaymentId | type: string | description: Gift card payment GUID. - name: appId | type: string | description: GUID of the app that created the gift card. - name: voided | type: boolean | description: Whether the gift card is voided. - name: _id | type: string | description: Payment GUID. - name: _createdDate | type: Date | description: Date and time the payment was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Defaults to current time when not provided. - name: _updatedDate | type: Date | description: Date and time the payment was last updated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: amount | type: Price | description: Payment amount. - name: refundDisabled | type: boolean | description: Whether refunds for this payment are disabled. + `true`: This payment is not refundable. + `false`: This payment may be refunded. However, this ultimately depends on the payment provider. - name: refunds | type: array | description: Record of refunds made to the buyer. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: PARTIAL_REFUND_FOR_MULTIPLE_LOCATIONS_NOT_ALLOWED | Description: Partial refunds with restocking aren't allowed for items with multiple inventory locations. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_RESTOCK_QUANTITY | Description: Line item restock quantity exceeds the available restock quantity. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_LINE_ITEM_REFUND_QUANTITY | Description: Line item refund quantity exceeds the available refund quantity. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_SHIPPING_REFUND_AMOUNT | Description: Shipping refund amount exceeds the available refund amount. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_ADDITIONAL_FEE_REFUND_AMOUNT | Description: Additional fee refund amount exceeds the available refund amount. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_PAYMENT_REFUND_AMOUNT | Description: Payment refund amount exceeds the available refund amount. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SHIPPING_NOT_FOUND | Description: Couldn't find the shipping. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: ADDITIONAL_FEE_NOT_FOUND | Description: Couldn't find the additional fee. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: LINE_ITEM_NOT_FOUND | Description: Couldn't find the line item. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: PAYMENT_NOT_FOUND | Description: Couldn't find the payment. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: EXTERNAL_REFUND_EXPECTED | Description: Payment requires an external refund. Set `externalRefund` to `true` in the `paymentRefunds` array. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PAYMENT_NOT_REFUNDABLE | Description: Payment can't be refunded. ``` ### Examples ### refundPayments ```javascript import { orderBilling } from '@wix/ecom'; async function refundPayments(orderId,options) { const response = await orderBilling.refundPayments(orderId,options); }; ``` ### refundPayments (with elevated permissions) ```javascript import { orderBilling } from '@wix/ecom'; import { auth } from '@wix/essentials'; async function myRefundPaymentsMethod(orderId,options) { const elevatedRefundPayments = auth.elevate(orderBilling.refundPayments); const response = await elevatedRefundPayments(orderId,options); } ``` ### refundPayments (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 { orderBilling } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { orderBilling }, // Include the auth strategy and host as relevant }); async function refundPayments(orderId,options) { const response = await myWixClient.orderBilling.refundPayments(orderId,options); }; ``` ---