The eCommerce Order Transactions API concentrates records and details of payments and refunds associated with eCommerce orders.
With the Order Transactions API you can:
This article shares a possible use case your app could support, as well as an example flow. You're certainly not limited to this use case, but it can be a helpful jumping off point as you plan your app's implementation.
Your app can retrieve details about payments and refunds associated with an order. For example, you can check for payments that were made by credit-card, payments made by gift card, or orders that were not successfully refunded.
To retrieve info about an order's transactions:
If you are importing orders from other systems, you may want to add payment records to those orders. To add a payment record to an order that is already in the eCommerce system:
createdDate
, amount
, paymentMethod
, and any other payment details.Manage eCommerce order payments
Order ID.
Record of payments made to the merchant.
Record of refunds made to the buyer.
{
"orderTransactions": {
"orderId": "8d009fbe-6600-4c7a-ad23-37e9f0477947",
"payments": [
{
"id": "a335aebd-4688-437e-84c3-ebe947779bc1",
"giftcardPaymentDetails": {
"giftCardPaymentId": "ff3c2b57-2dc4-47de-a261-9ae00251a60b",
"giftCardId": "",
"appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27",
"voided": false
},
"createdDate": "2023-09-01T20:20:26.451Z",
"updatedDate": "2023-09-01T20:20:26.451Z",
"amount": {
"amount": "25.0",
"formattedAmount": "C$25.00"
},
"refundDisabled": false
},
{
"id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"regularPaymentDetails": {
"gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL",
"offlinePayment": false,
"status": "REFUNDED"
},
"createdDate": "2023-09-01T20:21:26.451Z",
"updatedDate": "2023-09-03T12:30:12.853Z",
"amount": {
"amount": "17.99",
"formattedAmount": "C$17,99"
},
"refundDisabled": false
}
],
"refunds": [
{
"id": "3cfa83af-94fe-4e02-a7c7-3a969557f697",
"transactions": [
{
"paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"amount": {
"amount": "17.99",
"formattedAmount": "C$17,99"
},
"refundStatus": "SUCCEEDED",
"gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e",
"providerRefundId": "re_3NmFQZINImlhPEm011HglMxH",
"externalRefund": false
}
],
"details": {
"items": [
{
"lineItemId": "00000000-0000-0000-0000-000000000001",
"quantity": 1
}
],
"shippingIncluded": true
},
"createdDate": "2023-09-03T12:30:12.853Z"
}
]
}
}
Retrieves information about payments and refunds associated with a specified order.
You can only call this method when authenticated as a Wix app or Wix user identity.
Order ID.
Order ID and its associated transactions.
curl -X GET 'https://www.wixapis.com/ecom/v1/payments/orders/8d009fbe-6600-4c7a-ad23-37e9f0477947' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"orderTransactions": {
"orderId": "8d009fbe-6600-4c7a-ad23-37e9f0477947",
"payments": [
{
"id": "a335aebd-4688-437e-84c3-ebe947779bc1",
"giftcardPaymentDetails": {
"giftCardPaymentId": "ff3c2b57-2dc4-47de-a261-9ae00251a60b",
"giftCardId": "",
"appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27",
"voided": false
},
"createdDate": "2023-09-01T20:20:26.451Z",
"updatedDate": "2023-09-01T20:20:26.451Z",
"amount": {
"amount": "25.0",
"formattedAmount": "C$25.00"
},
"refundDisabled": false
},
{
"id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"regularPaymentDetails": {
"gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL",
"offlinePayment": false,
"status": "REFUNDED"
},
"createdDate": "2023-09-01T20:21:26.451Z",
"updatedDate": "2023-09-03T12:30:12.853Z",
"amount": {
"amount": "17.99",
"formattedAmount": "C$17,99"
},
"refundDisabled": false
}
],
"refunds": [
{
"id": "3cfa83af-94fe-4e02-a7c7-3a969557f697",
"transactions": [
{
"paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"amount": {
"amount": "17.99",
"formattedAmount": "C$17,99"
},
"refundStatus": "SUCCEEDED",
"gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e",
"providerRefundId": "re_3NmFQZINImlhPEm011HglMxH",
"externalRefund": false
}
],
"details": {
"items": [
{
"lineItemId": "00000000-0000-0000-0000-000000000001",
"quantity": 1
}
],
"shippingIncluded": true
},
"createdDate": "2023-09-03T12:30:12.853Z"
}
]
}
}
Retrieves information about payments and refunds associated with all specified orders.
You can only call this method when authenticated as a Wix app or Wix user identity.
Order IDs for which to retrieve transactions.
List of order IDs and their associated transactions.
Retrieves transactions of the 2 requested order IDs
curl -X POST \
'https://www.wixapis.com/ecom/v1/payments/list-by-ids' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
--data-binary '{
"orderIds": [
"4bab5870-7943-4a9e-8d4e-96719b3e4f38",
"6ae38b2e-455b-4e20-b418-01fca82edaa8"
]
}'
{
"orderTransactions": [
{
"orderId": "4bab5870-7943-4a9e-8d4e-96719b3e4f38",
"payments": [
{
"id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"regularPaymentDetails": {
"gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL",
"offlinePayment": false,
"status": "REFUNDED"
},
"createdDate": "2023-09-03T12:29:21.284Z",
"updatedDate": "2023-09-03T12:30:12.853Z",
"amount": {
"amount": "17.99",
"formattedAmount": "17,99 €"
},
"refundDisabled": false
}
],
"refunds": [
{
"id": "3cfa83af-94fe-4e02-a7c7-3a969557f697",
"transactions": [
{
"paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac",
"amount": {
"amount": "17.99",
"formattedAmount": "17,99 €"
},
"refundStatus": "SUCCEEDED",
"gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e",
"providerRefundId": "re_3NmFQZINImlhPEm011HglMxH",
"externalRefund": false
}
],
"details": {
"items": [
{
"lineItemId": "00000000-0000-0000-0000-000000000001",
"quantity": 1
}
],
"shippingIncluded": true
},
"createdDate": "2023-09-03T12:30:12.853Z"
}
]
},
{
"orderId": "6ae38b2e-455b-4e20-b418-01fca82edaa8",
"payments": [
{
"id": "e2f17179-db73-46ef-8d8a-06de7158e43b",
"regularPaymentDetails": {
"gatewayTransactionId": "6bba8866-a3af-4404-9522-61be070e4715",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3NiMZkLpihTBGDpG0DewjotR",
"offlinePayment": false,
"status": "APPROVED"
},
"createdDate": "2023-08-23T19:18:46.135Z",
"updatedDate": "2023-08-23T19:18:46.135Z",
"amount": {
"amount": "0.5",
"formattedAmount": "0,50 €"
},
"refundDisabled": false
}
],
"refunds": []
}
]
}
Adds up to 50 payment records to an order.
Note: This does NOT perform the actual charging - the order is only updated with records of the payments.
You can only call this method when authenticated as a Wix app or Wix user identity.
Order ID.
Payments to be added to order.
Order ID and its associated transactions.
IDs of added order payments.
curl -X POST \
'https://www.wixapis.com/ecom/v1/payments/orders/6b51aac3-075c-4b4e-9e92-10c3730130ae/add-payment' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
--data-binary '{
"payments": [
{
"amount": {
"amount": "19.0"
},
"refundDisabled": false,
"regularPaymentDetails": {
"paymentOrderId": "356e3ba8-6ee9-4f30-9ce4-cf726e4fe6f2",
"gatewayTransactionId": "93eb1f1e-4c1b-4392-979c-a59d1ccf5912",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3Nma8hD7mauJ7ZJt0bKKZkRT",
"offlinePayment": false,
"status": "PENDING"
}
},
{
"amount": {
"amount": "20.0"
},
"refundDisabled": true,
"giftcardPaymentDetails": {
"giftCardPaymentId": "e38b2b8b-f416-49b2-bbf0-869712fb9a78",
"appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27"
}
}
]
}'
{
"orderTransactions": {
"orderId": "6b51aac3-075c-4b4e-9e92-10c3730130ae",
"payments": [
{
"id": "490fa480-414e-443a-befe-13cbb2772a2f",
"regularPaymentDetails": {
"paymentOrderId": "356e3ba8-6ee9-4f30-9ce4-cf726e4fe6f2",
"gatewayTransactionId": "93eb1f1e-4c1b-4392-979c-a59d1ccf5912",
"paymentMethod": "Stripe",
"providerTransactionId": "pi_3Nma8hD7mauJ7ZJt0bKKZkRT",
"offlinePayment": false,
"status": "PENDING"
},
"createdDate": "2023-11-21T09:31:07.806Z",
"updatedDate": "2023-11-21T09:31:07.806Z",
"amount": {
"amount": "19.0",
"formattedAmount": "$19.00"
},
"refundDisabled": false
},
{
"id": "dc67d010-529a-4cea-b78d-8283f3bd3f7b",
"giftcardPaymentDetails": {
"giftCardPaymentId": "e38b2b8b-f416-49b2-bbf0-869712fb9a78",
"giftCardId": "",
"appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27",
"voided": false
},
"createdDate": "2023-11-21T09:31:07.806Z",
"updatedDate": "2023-11-21T09:31:07.806Z",
"amount": {
"amount": "20.0",
"formattedAmount": "$20.00"
},
"refundDisabled": true
}
],
"refunds": []
},
"paymentsIds": [
"490fa480-414e-443a-befe-13cbb2772a2f",
"dc67d010-529a-4cea-b78d-8283f3bd3f7b"
]
}
Updates the status of an order's payment.
You can only call this method when authenticated as a Wix app or Wix user identity.
Order ID.
Payment ID.
Payment status.
Order ID and its associated transactions after update.
curl -X POST \
'https://www.wixapis.com/ecom/v1/payments/6ac204b6-d1df-44c7-ae84-aa08197380d8/orders/c7689f97-304f-425e-bbda-2451a32596c9/update-payment-transaction-status' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
--data-binary '{
"status": "APPROVED"
}'
{
"orderTransactions": {
"orderId": "c7689f97-304f-425e-bbda-2451a32596c9",
"payments": [
{
"id": "6ac204b6-d1df-44c7-ae84-aa08197380d8",
"regularPaymentDetails": {
"paymentOrderId": null,
"gatewayTransactionId": "47303d3c-5a0f-4e6f-87f4-891d89cd8203",
"paymentMethod": "WixPayments",
"providerTransactionId": "47303d3c-5a0f-4e6f-87f4-891d89cd8203",
"offlinePayment": false,
"status": "APPROVED"
},
"createdDate": "2023-11-17T15:00:27.293Z",
"updatedDate": "2023-11-17T15:02:10.890Z",
"amount": {
"amount": "99.0",
"formattedAmount": "$99.00"
},
"refundDisabled": false
}
],
"refunds": []
}
}
Updates multiple order payments with a specified status.
You can only call this method when authenticated as a Wix app or Wix user identity.
Order and payment IDs for which to update payment status.
Whether to return the full payment entity (results.item
) in the response.
Payment status.
Bulk operation results.
Bulk operation metadata.
curl -X POST \
'https://www.wixapis.com/ecom/v1/bulk/payments/update-payment-transaction-status' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
--data-binary '{
"paymentAndOrderIds": [
{
"orderId": "69c598e5-987f-4429-9b61-76aaf47efedc",
"paymentId": "770f8669-6ae7-47ed-a3fc-815ada5d86f9"
},
{
"orderId": "4f0cc39e-bb17-44be-bdbd-8331a5138987",
"paymentId": "21cc0ff7-7ff5-4931-9ef8-1ee3d84a2215"
}
],
"status": "CANCELED",
"returnFullEntity": false
}'
{
"results": [
{
"itemMetadata": {
"id": "770f8669-6ae7-47ed-a3fc-815ada5d86f9",
"originalIndex": 0,
"success": true
}
},
{
"itemMetadata": {
"id": "21cc0ff7-7ff5-4931-9ef8-1ee3d84a2215",
"originalIndex": 1,
"success": true
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 2,
"totalFailures": 0,
"undetailedFailures": 0
}
}
Triggered when a payment or refund is added to an order, or when an existing payment is updated.
The response contains the ID of the updated order and details of its associated transactions, as well as IDs of the updated payments and refunds.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.ecom.v1.order_transactions
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.ecom.v1.order_transactions_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "e883330e-6985-4b2c-b570-98260ffcf972",
"entityFqdn": "wix.ecom.v1.order_transactions",
"slug": "updated",
"entityId": "c759ec55-52e8-45a9-a04a-71670340641d",
"actionEvent": {
"body": {
"orderTransactions": {
"orderId": "c759ec55-52e8-45a9-a04a-71670340641d",
"payments": [
{
"id": "1baf0a11-0c05-4bd2-b6b2-56be85c910b1",
"regularPaymentDetails": {
"gatewayTransactionId": "e752e841-1f6a-464c-8087-06d290ef250f",
"paymentMethod": "WixPayments",
"providerTransactionId": "e752e841-1f6a-464c-8087-06d290ef250f",
"offlinePayment": false,
"status": "REFUNDED"
},
"createdDate": "2024-01-04T14:46:18.513Z",
"updatedDate": "2024-01-04T14:46:38.360Z",
"amount": {
"amount": "84.0",
"formattedAmount": "$84.00"
},
"refundDisabled": false
}
],
"refunds": [
{
"id": "961e217b-eede-4ecb-891b-8776da816074",
"transactions": [
{
"paymentId": "1baf0a11-0c05-4bd2-b6b2-56be85c910b1",
"amount": {
"amount": "84",
"formattedAmount": "$84.00"
},
"refundStatus": "SUCCEEDED",
"gatewayRefundId": "74c5a247-f8a4-431c-ba6c-ba7234465ea9",
"providerRefundId": "6728744f-6ec8-4533-b1dc-9e95ea2fd2c8",
"externalRefund": false
}
],
"details": {
"items": [],
"shippingIncluded": false
},
"createdDate": "2024-01-04T14:46:38.360Z"
}
]
},
"paymentIds": ["1baf0a11-0c05-4bd2-b6b2-56be85c910b1"],
"refundIds": ["961e217b-eede-4ecb-891b-8776da816074"]
}
},
"eventTime": "2024-01-04T14:46:38.377953757Z",
"triggeredByAnonymizeRequest": false
}