API reference transactions - WEBSALE Dokumentation

The transactions/ endpoint provides an interface for retrieving and managing payment information from the shop system. For each transaction you can view details such as the payment method, status, amounts and timing. In addition, the interface supports updating the status as well as actions such as capture, refund or cancellation.

Supported methods

List of all supported methods.

Command/Info	Endpoints	DELETE	GET	POST	PUT
Transactions	transactions/

Data fields of a transaction

Name	Type	Meaning
`accountId`	Integer	ID of the customer account that performed the payment.
`amount`	String	Amount of the transaction (in the respective currency).
`clearerId`	String	ID of the payment service provider (e.g. PayPal, Klarna).
`createdAt`	String	Time of creation (ISO 8601 format, UTC).
`currency`	String	ISO currency code (e.g. “EUR”).
`id`	String	Unique ID of the transaction.
`orderId`	String	ID of the order to which the transaction belongs.
`payedAt`	String	Time of payment (ISO 8601 format, UTC).
`paymentMethod`	String	Identifier of the chosen payment method (e.g. “paypalCheckout”).
`paymentStatus`	Integer	Status of the payment (e.g. open, paid, failed). Possible values: `0 = Pending` `1 = Finished` `2 = Error` `3 = Redirected` `4 = Canceled` `5 = Rejected` `6 = CanceledByAdmin` `7 = Refunded` `8 = RefundedPartially`
`refundedAt`	String	Time of the refund (if performed).
`sandboxPayment`	Boolean	Indicates whether the transaction was executed with a payment method that was configured in sandbox/test mode. Possible values: `true` = payment method in sandbox mode `false` = payment method in live mode
`sessionId`	String	ID of the session in which the payment was made.
`subshopId`	String	ID of the subshop in which the payment took place.
`updatedAt`	String	Time of the last update (ISO 8601 format, UTC).

Example

{
    "accountId": 4,
    "amount": "23.940000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-20T15:20:26Z",
    "currency": "EUR",
    "id": "7RL91160EW951091F",
    "orderId": "1501",
    "payedAt": "2025-03-20T15:20:26Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "8ed8455230bf1920dda6fe73c550d72620647ff35cec4fe3cfe6c410fa487cc0",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-20T15:20:26Z"
}

Methods for transactions

The following methods let you manage transactions in the shop system. A transaction records the payment movement for an order and contains information such as amount, status, payment method and times of payment or refund. Through the API, transactions can be read, their status updated, refunded, canceled or captured. For all methods, the corresponding permissions to read or write transaction data must be available.

GET transactions

The transactions endpoint lets you access a list of completed transactions in the shop. The API lets you filter and sort transactions by various criteria such as time ranges, payment status or subshop. Transactions contain information about amounts, payment methods, associated orders and customer accounts, among other things. To access this endpoint, the corresponding permissions to read transaction data must be available.

Example

The example shows a query of up to 100 transactions created in the period from 2025-03-23 to 2025-04-22 inclusive.

http://www.<your-shop>.de/admin/api/v1/transactions?size=100&filter_gte[createdAt]=2025-03-23T00:00:00.360Z
&filter_lte[createdAt]=2025-04-22T23:59:59.360Z

Response

{
    "endReached": true,
    "items": [
        {
            "accountId": 4,
            "amount": "12.950000",
            "clearerId": "paypal-checkout",
            "createdAt": "2025-03-24T08:08:16Z",
            "currency": "EUR",
            "id": "86T19828EK510721G",
            "orderId": "1553",
            "payedAt": "2025-03-24T08:08:16Z",
            "paymentMethod": "paypalCheckout",
            "paymentStatus": 1,
            "refundedAt": "0000-00-00T00:00:00Z",
            "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
            "subshopId": "deutsch",
            "sandboxPayment": 0,
            "updatedAt": "2025-03-24T08:08:16Z"
        },
        {
            "accountId": 117,
            "amount": "12.950000",
            "clearerId": "paypal-checkout",
            "createdAt": "2025-03-24T13:15:25Z",
            "currency": "EUR",
            "id": "27V62418RL450684B",
            "orderId": "1688",
            "payedAt": "2025-03-24T13:15:25Z",
            "paymentMethod": "paypalCheckout",
            "paymentStatus": 1,
            "refundedAt": "0000-00-00T00:00:00Z",
            "sessionId": "3bd02f1620965216cefd91eee7c55dba5bf3d036386f40a519304fdeef94dc21",
            "subshopId": "deutsch",
            "sandboxPayment": 0,
            "updatedAt": "2025-03-24T13:15:25Z"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}

Filter fields

id, createdAt, payedAt, refundedAt, paymentStatus, subshopId, accountId, sandboxPayment

Sort fields

id, createdAt, updatedAt, payedAt, refundedAt, paymentStatus, subshopId, accountId, orderId, sessionId, clearerId, currency, amount, paymentMethod, sandboxPayment

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to read transactions.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
503 Service Unavailable	”internalError”	Reading data failed.

GET transactions/{id}

This method loads the complete details of a single transaction based on its unique ID. You can use it to retrieve transaction information such as payment status, addresses and additional data. To use this method, the required permissions to read transactions must be available.

Example

http://www.<your-shop>.de/admin/api/v1/transactions/86T19828EK510721G

Response

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to read transactions.
404 Not Found		The transaction was not found.
400 Bad Request	”missing”	`id` is missing.

PUT transactions/{id}/refresh

This method queries the current status of an existing transaction with the connected payment service provider and updates it. It can be used when the status of a transaction no longer appears up to date (e.g. for pending payments or refunds). The corresponding permissions to write transaction data must be available.

Example

http://www.<your-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refresh

Response

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to write transactions.
400 Bad Request	”missing”	`id` is missing.
404 Not Found		The transaction data could not be read after the update.

PUT transactions/{id}/cancel

This method attempts to cancel a transaction with the connected payment service provider. This is required, for example, for payments that have not yet been completed or that contain errors. After a successful cancellation, the updated transaction is returned. The corresponding permissions to write transactions must be available.

Example

http://www.<your-shop>.de/admin/api/v1/transactions/86T19828EK510721G/cancel

Response

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 4,
    "refundedAt": "2025-04-24T10:30:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-04-24T10:30:00Z"
}

After a successful cancellation the paymentStatus is usually set to 4 (Canceled) or 6 (CanceledByAdmin). The exact value depends on the payment service provider.

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to write transactions.
404 Not Found		The transaction was not found. The transaction data could not be read after the update.
400 Bad Request	”missing”	`id` is missing.
503 Service Unavailable	”internalError”	The cancellation failed. The transaction could not be loaded after the update.

PUT transactions/{id}/refund

This method triggers a refund of an already paid amount for the specified transaction. Optionally, a partial amount (amount) and a refund reason (reason) can be provided in the request body. If no amount is specified, the entire amount is refunded. After a successful refund, the updated transaction is returned. For this action, the corresponding permissions to write transactions must be available.

Example

http://www.<your-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refund

Request body

{
    "amount": "5",
    "reason": "Mein Grund"
}

Response

{
    "accountId": 2,
    "amount": "30.990000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-18T14:37:51Z",
    "currency": "EUR",
    "id": "1MV26007FY832013B",
    "orderId": "1330",
    "payedAt": "2025-03-18T14:37:51Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 7,
    "refundedAt": "2025-03-18T15:16:59Z",
    "sessionId": "ba068bace905c4ce9a32219e2170af2f69a959dd6a59d7b9909718885d259c4a",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-18T15:16:59Z"
}

After a successful refund the paymentStatus is set to 7 (Refunded) or 8 (RefundedPartially), depending on whether the entire amount or a partial amount was refunded.

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to write transactions.
400 Bad Request		Request body could not be loaded.
404 Not Found		The transaction was not found. The transaction data could not be read after the update.
400 Bad Request	”missing”	`id` is missing.
400 Bad Request	”invalidValue”	`amount` is ≤ 0 or greater than the transaction amount.
400 Bad Request	”invalidFormat”	`amount` or `reason` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
503 Service Unavailable	”internalError”	The refund failed. The transaction could not be loaded after the update.

PUT transactions/{id}/capture

This method is used to capture a reserved transaction, i.e. the amount that was only earmarked is finally debited from the customer account. This function is mainly needed for payment providers where authorization and a separate capture are required (e.g. credit card). The updated transaction is then returned. For this action, the corresponding permissions to write transactions must be available.

Example

http://www.<your-shop>.de/admin/api/v1/transactions/86T19828EK510721G/capture

Response

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-04-24T11:05:00Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 2,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "sandboxPayment": 0,
    "updatedAt": "2025-04-24T11:05:00Z"
}

After a successful capture the paymentStatus is usually set to 1 (Finished). In case of an error it is set to 2 (Error).

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or you do not have the required permissions to write transactions.
404 Not Found		The transaction was not found. The transaction data could not be read after the update.
400 Bad Request	”missing”	`id` is missing.
503 Service Unavailable	”internalError”	The capture failed. The transaction could not be loaded after the update.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields of a transaction

​Example

​Methods for transactions

​GET transactions

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET transactions/{id}

​Example

​Response

​Error codes

​PUT transactions/{id}/refresh

​Example

​Response

​Error codes

​PUT transactions/{id}/cancel

​Example

​Response

​Error codes

​PUT transactions/{id}/refund

​Example

​Request body

​Response

​Error codes

​PUT transactions/{id}/capture

​Example

​Response

​Error codes

​Support

Supported methods

Data fields of a transaction

Example

Methods for transactions

GET transactions

Example

Response

Filter fields

Sort fields

Error codes

GET transactions/{id}

Example

Response

Error codes

PUT transactions/{id}/refresh

Example

Response

Error codes

PUT transactions/{id}/cancel

Example

Response

Error codes

PUT transactions/{id}/refund

Example

Request body

Response

Error codes

PUT transactions/{id}/capture

Example

Response

Error codes

Support