{ "openapi": "3.1.1", "info": { "title": "Walley API", "version": "v1", "description": "APIs for integrating with Walley's payment products. Authenticate with a bearer token from the OAuth2 client credentials flow. See [Authentication](https://dev.walleypay.com/docs/manage/getting-started/authentication) to get started." }, "tags": [ { "name": "Auth", "description": "Obtain an OAuth2 access token.\n\n**Response envelope:** none. The token endpoint returns the OAuth2 token object directly.", "x-displayName": "Auth" }, { "name": "Checkout", "description": "Use the Checkout API to initialize and configure a Walley Checkout session, then guide it through the purchase. Set the cart, fees, shipping, and order references, retrieve the current checkout state, send pay-by-link invitations, and abort sessions you no longer need.\n\n**Response envelope:** successful responses are wrapped as `{ \"id\": …, \"data\": … }`. The payload is in `data`. A `context` field echoes the request's context when one was supplied.", "x-displayName": "Checkout" }, { "name": "Order Management", "x-displayName": "Order Management", "description": "Manage orders after the purchase is placed. Search and inspect orders, then drive them through their lifecycle: **activate** (capture) to ship and invoice, **cancel** before activation, **return** (refund) activated articles, **reauthorize** to change not-yet-captured items or the order amount, and **extend** an invoice’s due date. Order actions require `write` permission on the order’s store, and reads require `read`. Actions are processed asynchronously (`202`), so poll the order for the result.\n\n**Response envelope:** successful responses are wrapped as `{ \"data\": …, \"links\": …, \"metaData\": … }`. The payload is in `data`." }, { "name": "Settlements", "description": "Retrieve settlement reports for reconciliation. A settlement groups the transactions Walley paid out together in a single remittance. Search and page settlements, download one as a PDF, or list the transactions that make up a settlement.\n\nA settlement covers the captures and refunds for one store over a settlement period (daily on business days, weekly, or monthly depending on the agreement). Activations add to the payout and returns are deducted from it. Depending on the agreement, fees are either deducted from the payout or invoiced separately.\n\n**Response envelope:** successful responses are wrapped as `{ \"data\": …, \"links\": …, \"metaData\": … }`. The payload is in `data`.", "x-displayName": "Settlements" }, { "name": "Widgets", "description": "Use the Widget API to show Walley payment information outside of a checkout session, such as part-payment costs or the available payment-method logos on a product page. The merchant backend calls Initialize Widget to obtain a widget token, which is then passed to the Walley widget loader script that renders the widget on the page.\n\n**Response envelope:** successful responses are wrapped as `{ \"id\": …, \"data\": … }`. The payload is in `data`. A `context` field echoes the request's context when one was supplied.", "x-displayName": "Widgets" }, { "name": "Customer Tokens", "description": "Authorize payments against a buyer's stored customer token and manage those tokens.\n\nA customer token represents a saved payment method: card, credit/invoice, or Swish. Create authorizations (asynchronous by default, or synchronous when you need the outcome inline), look up a token's status and payment method, update the buyer's contact details, or cancel a token.\n\n**Response envelope:** successful responses are wrapped as `{ \"id\": …, \"data\": … }`. The payload is in `data`. Error responses are wrapped as `{ \"id\": …, \"error\": { \"code\": …, \"message\": …, \"errors\": [ … ] } }`.\n\n**Null handling:** properties without a value are omitted from responses rather than returned as `null`. Treat an absent property as null.\n\n**Correlation:** send an optional `CorrelationId` request header to correlate your request with ours. When the value is a GUID it is returned as the response `id`. When it is any other non-empty string, a new `id` is generated and your value is returned in a `context` field instead. When the header is omitted, `id` is generated and `context` is absent.", "x-displayName": "Customer Tokens" } ], "paths": { "/oauth2/v2.0/token": { "post": { "tags": [ "Auth" ], "operationId": "getOAuth2Token", "summary": "Request an OAuth2 access token", "description": "Exchanges client credentials for an OAuth2 access token using the client credentials grant. Send the parameters as `application/x-www-form-urlencoded`.", "parameters": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "client_id": "your-client-id", "client_secret": "your-client-secret", "grant_type": "client_credentials", "scope": "705798e0-8cef-427c-ae00-6023deba29af/.default" } } } }, "responses": { "200": { "description": "Access token issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "token_type": "Bearer", "expires_in": 3599, "access_token": "bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE..." } } } }, "400": { "description": "Invalid or missing request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenErrorResponse" } } } }, "401": { "description": "Invalid client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenErrorResponse" } } } } }, "security": [] } }, "/widgets": { "post": { "tags": [ "Widgets" ], "summary": "Initialize widget", "description": "Create a widget session so you can show Walley payment information outside a checkout, such as part-payment costs on a product page. Your backend calls this to get a token, which you then hand to the Walley widget loader script in the browser.", "operationId": "initializeWidget", "requestBody": { "content": { "application/json": { "schema": { "description": "Request to initialize a widget session for a store and obtain a widget token.", "$ref": "#/components/schemas/InitializeWidgetRequest" }, "example": { "storeId": 123 } } }, "required": true }, "responses": { "200": { "description": "The widget was initialized. Returns the token to pass to the Walley widget loader script.", "content": { "application/json": { "schema": { "description": "Response envelope; the `data` property holds the response data.", "$ref": "#/components/schemas/InitializeWidgetResponseEnvelope" }, "example": { "data": { "widgetToken": "widget-SE-EXAMPLEWIDGETTOKEN0000000000000000000000000000000000000000000000000000000000000000", "expiresAt": "2026-12-07T07:16:49.8098107+00:00" }, "id": "91714012-6ae9-4780-a927-fe459bc95bf6" } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts": { "post": { "tags": [ "Checkout" ], "summary": "Initialize checkout", "description": "Create a checkout session for a cart. This is the first call in every purchase flow: send the cart, the market and your notification URI, and Walley returns the private id your backend uses for later calls together with the public token that renders the checkout in the customer's browser.", "operationId": "initializeCheckout", "requestBody": { "content": { "application/json": { "schema": { "description": "Request to initialize a new checkout.", "$ref": "#/components/schemas/InitializeCheckoutRequest" }, "examples": { "minimal": { "summary": "Minimal request", "value": { "countryCode": "SE", "storeId": 123, "cart": { "items": [ { "description": "Product Name", "id": "10001", "quantity": 1, "unitPrice": 100, "vat": 25 } ] }, "notificationUri": "https://example.com/notifications", "merchantTermsUri": "https://example.com/terms" } }, "allFeatures": { "summary": "Request using the optional features", "value": { "countryCode": "SE", "reference": "123456789", "settlementReference": "shop1", "actionReference": "MyActionReference", "storeId": 123, "externalStoreId": "shop1", "cart": { "shippingProperties": { "height": "10", "width": "20", "isBulky": "true" }, "items": [ { "description": "A product description", "id": "10001", "quantity": 1, "unitPrice": 95, "unitWeight": 0.3, "vat": 25, "requiresElectronicId": true, "sku": "a unique alphanumeric code for article identification" }, { "description": "Gift Card", "id": "10002", "type": "GiftCard", "quantity": 1, "unitPrice": -100, "vat": 0 } ] }, "upsell": { "items": [ { "description": "Gift wrapping", "id": "20001", "quantity": 1, "unitPrice": 29, "vat": 25, "sku": "a unique alphanumeric code for article identification", "imageUrl": "https://example.com/images/gift-wrapping.png" } ], "timeLimitInSeconds": 120 }, "notificationUri": "https://example.com/my-notification-endpoint", "redirectPageUri": "https://example.com/purchase-completed-confirmation-page", "checkoutAbortedRedirectPageUri": "https://example.com/back-to-your-shop", "validationUri": "https://example.com/my-validation-endpoint", "callback": { "callbackUri": "https://example.com/my-callback-endpoint", "callbackTypes": [ "ValidateOrder", "PaymentFailed" ] }, "merchantTermsUri": "https://example.com/merchant-purchase-terms", "fees": { "shipping": { "description": "Shipping cost (incl. VAT)", "id": "shipping001", "unitPrice": 59, "vat": 25 } }, "privateCustomerPrefill": { "email": "test@example.com", "mobilePhoneNumber": "+46701234567", "nationalIdentificationNumber": "19510731-2323", "deliveryAddress": { "firstName": "Test", "lastName": "Testsson", "coAddress": "c/o Test Testsson", "address": "Test Street 1", "address2": "Another address line if needed", "postalCode": "12345", "city": "Test City", "countryCode": "SE" } }, "businessCustomerPrefill": { "buyer": { "firstName": "Test", "lastName": "Testsson", "email": "test@example.com", "mobilePhoneNumber": "+46701234567" }, "invoiceReference": "ref", "invoiceTag": "tag", "deliveryAddress": { "companyName": "Test Company AB", "coAddress": "c/o Test Testsson", "address": "Test Street 2", "address2": "Another address line if needed", "postalCode": "12345", "city": "Test City" } }, "businessCustomerPreset": { "organizationNumber": "556026-9986" }, "profileName": "MyExampleProfile", "metadata": { "administrator": "Test Testsson", "someOtherData": [ 1, { "myObj": { "key": 1 } } ] }, "customFields": [ { "id": "group1", "fields": [ { "id": "newsConsent", "name": "I agree to receive marketing communications", "type": "Checkbox", "value": true, "localizations": { "fi-FI": { "name": "Hyväksyn markkinointiviestinnän vastaanottamisen", "value": false, "metadata": { "field1Meta": "fi-field-newsletter-consent" } } }, "metadata": { "field1Meta": "field-newsletter-consent" } }, { "id": "comments", "name": "Any additional comments?", "type": "Text" } ], "metadata": { "groupMeta": "content" } } ] } } } } }, "required": true }, "responses": { "200": { "description": "The checkout session was created. Returns its private id and the public token used to render the checkout.", "content": { "application/json": { "schema": { "description": "Response envelope; the `data` property holds the response data.", "$ref": "#/components/schemas/InitializeCheckoutResponseEnvelope" }, "example": { "data": { "privateId": "1eec44b5-66d3-4058-a31f-3444229fb727", "publicToken": "public-SE-EXAMPLEPUBLICTOKEN000000000000000000000000000000000", "expiresAt": "2025-12-07T07:16:49.8098107+00:00", "paymentUri": "https://checkout.uat.walleydev.com/p/npBc87EFB", "paymentQrCodeUri": "https://api.uat.walleydev.com/checkouts/paylinks/npBc87EFB/qrcode" }, "id": "91714012-6ae9-4780-a927-fe459bc95bf6" } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}": { "get": { "tags": [ "Checkout" ], "summary": "Get checkout information", "description": "Read the current state of a checkout session: the identified customer, the cart, fees, shipping and the purchase result once the customer has paid. Call this from your backend after the customer returns from the checkout, or when your notification endpoint is triggered.", "operationId": "getMerchantInformation", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The current state of the checkout session: customer, cart, fees, shipping and purchase status.", "content": { "application/json": { "schema": { "description": "Response envelope; the `data` property holds the response data.", "$ref": "#/components/schemas/GetMerchantCheckoutInformationResponseEnvelope" }, "examples": { "privateCustomer": { "summary": "Private customer (B2C), strongly identified with a national identification number", "value": { "data": { "customerType": "PrivateCustomer", "customer": { "email": "test@example.com", "mobilePhoneNumber": "+46701234567", "nationalIdentificationNumber": "19510731-2323", "deliveryContactInformation": { "email": "delivery@example.com", "mobilePhoneNumber": "+46709876543" }, "deliveryAddress": { "firstName": "Test", "lastName": "Testsson", "address": "Test Street 1", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" }, "billingAddress": { "firstName": "Test", "lastName": "Testsson", "address": "Test Street 2", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" } }, "businessCustomer": null, "countryCode": "SE", "status": "PurchaseCompleted", "paymentName": null, "reference": "123456789", "cart": null, "fees": null, "purchase": { "amountToPay": 159, "paymentName": "Account", "purchaseIdentifier": "640173", "result": "Preliminary", "decisionCategory": "Yellow" }, "order": { "orderId": "0466ffb4-80d8-4c55-bd74-af400166b3d7", "totalAmount": 159, "customerToken": null, "items": [ { "id": "1", "description": "Some product", "unitPrice": 200, "quantity": 1, "vat": 20 }, { "id": "998", "description": "Shipping cost (incl. VAT)", "unitPrice": 59, "quantity": 1, "vat": 25 }, { "id": "10003", "description": "Gift Card 100", "type": "GiftCard", "unitPrice": -100, "quantity": 1, "vat": 0, "usedAmount": 100 } ] }, "shipping": { "provider": "MyShippingProvider", "shippingFee": 59, "shipments": [ { "id": "delivery", "feeItemId": "998", "bookedShipmentId": "SHP-8842119", "externalShipmentId": "delivery", "metadata": null, "shippingChoice": { "id": "999900201010", "name": "Postnord Ombud", "fee": 59, "vat": 25, "metadata": null, "destination": { "id": "240361", "name": "Coop Gamlestaden", "description": "Treriksgatan 2, 41514 GÖTEBORG", "fee": 0, "metadata": null, "deliveryDate": null }, "options": null } } ] }, "customFields": [ { "id": "group1", "fields": [ { "id": "newsConsent", "name": "I agree to receive marketing communications", "type": "Checkbox", "value": false, "metadata": { "field1Meta": "field-newsletter-consent" } }, { "id": "comments", "name": "Any additional comments?", "type": "Text", "value": "no nothing noteworthy" } ], "metadata": { "groupMeta": "content" } } ], "hasSessionExpired": false }, "id": "9eec015f-4b97-44be-a711-d22f3af75069" } }, "businessCustomer": { "summary": "Business customer (B2B)", "value": { "data": { "customerType": "BusinessCustomer", "customer": null, "businessCustomer": { "companyName": "Test Company AB", "organizationNumber": "556026-9986", "invoiceReference": "Reparation dusch", "email": "test@example.com", "firstName": "Test", "lastName": "Testsson", "mobilePhoneNumber": "+46701234567", "invoiceTag": "Fakturamärkning: 5678", "invoiceAddress": { "companyName": "Test Company AB", "address": "Test Street 1", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" }, "deliveryAddress": { "companyName": "Test Company AB", "address": "Test Street 2", "address2": "att: Test Testsson", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" }, "validatedVatNumber": null }, "countryCode": "SE", "status": "PurchaseCompleted", "paymentName": null, "reference": "1231", "cart": null, "fees": { "shipping": { "id": "Frakt", "description": "DHL Ombud", "unitPrice": 19, "vat": 25 } }, "purchase": { "amountToPay": 377, "paymentName": "DirectInvoice", "purchaseIdentifier": "33074878", "result": "Preliminary" }, "order": { "orderId": "0466ffb4-80d8-4c55-bd74-af400166b3d7", "totalAmount": 377, "customerToken": null, "items": [ { "id": "scap001", "description": "Shower Cap", "unitPrice": 10, "quantity": 1, "vat": 25 }, { "id": "shipping001", "description": "Shipping fee (incl. vat)", "unitPrice": 59, "quantity": 1, "vat": 25 }, { "id": "dirfee001", "description": "Order administration fee (incl. vat)", "unitPrice": 299, "quantity": 1, "vat": 25 } ] }, "hasSessionExpired": false, "metadata": { "administrator": "John Doe", "someOtherData": [ 1, { "myObj": { "key": 1 } } ] } }, "id": "80a0b38b-2f8b-47db-81a5-8b56baa4ad84" } }, "agreementRegistered": { "summary": "Private customer (B2C) onboarded to a credit agreement through a RegisterAgreement checkout, no purchase", "value": { "data": { "customerType": "PrivateCustomer", "customer": { "email": "test@example.com", "mobilePhoneNumber": "+46701234567", "nationalIdentificationNumber": "19510731-2323", "deliveryAddress": { "firstName": "Test", "lastName": "Testsson", "address": "Test Street 1", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" }, "billingAddress": { "firstName": "Test", "lastName": "Testsson", "address": "Test Street 1", "postalCode": "12345", "city": "Test City", "country": "Sverige", "countryCode": "SE" } }, "businessCustomer": null, "countryCode": "SE", "status": "AgreementRegistered", "paymentName": null, "reference": null, "cart": null, "fees": null, "purchase": null, "order": null, "hasSessionExpired": false }, "id": "3f7a9c2e-6d14-4b0b-9a58-1e2c7d4f8b96" } } } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Checkout" ], "summary": "Abort checkout", "description": "Abort a checkout session that will not be completed, for example when the customer leaves the basket or your stock check fails. The session can no longer be paid, so start a new checkout if the customer returns.", "operationId": "abortCheckout", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The checkout session was aborted and can no longer be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "409": { "description": "The request could not be completed due to a conflict with the current state of the target resource.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Checkout" ], "summary": "Update checkout", "description": "Update the configuration of an existing checkout session, such as the customer details you prefill or the URIs Walley calls back. Use the dedicated endpoints instead when you only need to change the cart, the fees, the shipping properties or the order reference.", "operationId": "setCheckout", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set up or update a checkout.", "$ref": "#/components/schemas/SetCheckoutRequest" }, "example": { "cart": [ { "description": "A product description", "id": "10001", "quantity": 1, "unitPrice": 95, "unitWeight": 0.3, "vat": 25, "requiresElectronicId": true, "sku": "a unique alphanumeric code for article identification" }, { "description": "Gift Card", "id": "10002", "type": "GiftCard", "quantity": 1, "unitPrice": -100, "vat": 0 } ], "fees": { "shipping": { "description": "Shipping cost (incl. VAT)", "id": "shipping001", "unitPrice": 59, "vat": 25 } }, "shippingProperties": { "height": "10", "width": "20", "isBulky": "true" }, "reference": "ABCDEFGHJIKLMNOP", "settlementReference": "shop1", "metadata": { "administrator": "Test Testsson", "someOtherData": [ 1, { "myObj": { "key": 1 } } ] } } } }, "required": true }, "responses": { "200": { "description": "The checkout session was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The request contains properties with invalid values. Details are provided in the `errors` property.\n- `Cart_Articles_Required`: The cart must contain at least one item that is not a gift card and that has a non-negative amount, for a checkout session that results in an order.\n- `Cart_Articles_Not_Allowed`: The cart must be empty for the intent of this checkout session.\n- `Fees_Not_Allowed`: Fees are not allowed for the intent of this checkout session.\n- `Upsell_Items_Not_Allowed`: Upsell items are not allowed for the intent of this checkout session.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Purchase_Commitment_Found`: The customer has clicked the Complete Purchase button and the checkout is therefore locked for modifications.\n- `Purchase_Completed`: The purchase is already completed.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/paylink": { "post": { "tags": [ "Checkout" ], "summary": "Send pay link", "description": "Send the customer a link to an existing checkout session so they can pay it later, by SMS or as a push notification in the Walley app. Useful for orders taken over the phone or in a store.", "operationId": "sendPayLink", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to send a payment link to the customer, specifying the recipient destination.", "$ref": "#/components/schemas/SendPayLinkRequest" }, "example": { "destination": { "mobilePhoneNumber": "+46701234567" } } } }, "required": true }, "responses": { "200": { "description": "The payment link was sent to the destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/cart": { "put": { "tags": [ "Checkout" ], "summary": "Update cart", "description": "Replace the cart of a checkout session. Send the complete set of articles, not a delta: whatever you send becomes the cart, and Walley recalculates the totals and the available payment options.", "operationId": "setCart", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set the cart for a checkout, containing the cart items and optional shipping properties.", "$ref": "#/components/schemas/SetCartRequest" }, "example": { "shippingProperties": { "height": "10", "width": "20", "isBulky": "true" }, "items": [ { "description": "A product description", "id": "10001", "quantity": 1, "unitPrice": 95, "unitWeight": 0.3, "vat": 25, "requiresElectronicId": true, "sku": "a unique alphanumeric code for article identification" }, { "description": "Gift Card", "id": "10002", "type": "GiftCard", "quantity": 1, "unitPrice": -100, "vat": 0 } ] } } }, "required": true }, "responses": { "200": { "description": "The cart was replaced and the checkout totals were recalculated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The request contains properties with invalid values. Details are provided in the `errors` property.\n- `Cart_Articles_Required`: The cart must contain at least one item that is not a gift card and that has a non-negative amount, for a checkout session that results in an order.\n- `Cart_Articles_Not_Allowed`: The cart must be empty for the intent of this checkout session.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Purchase_Commitment_Found`: The customer has clicked the Complete Purchase button and the checkout is therefore locked for modifications.\n- `Purchase_Completed`: The purchase is already completed.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/metadata": { "put": { "tags": [ "Checkout" ], "summary": "Update metadata", "description": "Attach your own key/value metadata to a checkout session. Walley stores it and returns it when you read the checkout, so you can carry your own identifiers through the purchase without keeping a separate lookup.", "operationId": "setCheckoutMetadata", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set or update the custom metadata associated with a checkout.", "$ref": "#/components/schemas/CheckoutMetadataRequest" }, "example": { "metadata": { "myCustomKey": 1234, "myComplexObject": { "firstKey": true, "CasingIsKept": [ 1, 2, 3 ] } } } } }, "required": true }, "responses": { "200": { "description": "The metadata was stored on the checkout session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The metadata object could not be parsed as a valid JSON object.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Purchase_Commitment_Found`: The customer has clicked the Complete Purchase button and the checkout is therefore locked for modifications.\n- `Purchase_Completed`: The purchase is already completed.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/shippingproperties": { "put": { "tags": [ "Checkout" ], "summary": "Update custom shipping properties", "description": "Set the shipping properties Walley passes on to the shipping provider, such as the pickup location or the dimensions of the shipment. Only relevant when your store uses integrated shipping.", "operationId": "setCustomShippingProperties", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set the custom shipping properties used to configure shipping options for a checkout.", "$ref": "#/components/schemas/CustomShippingPropertiesRequest" }, "example": { "shippingProperties": { "height": "10", "width": "20", "isBulky": "true" } } } }, "required": true }, "responses": { "200": { "description": "The custom shipping properties were applied to the checkout session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The request contains properties with invalid values. Details are provided in the `errors` property.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Purchase_Commitment_Found`: The customer has clicked the Complete Purchase button and the checkout is therefore locked for modifications.\n- `Purchase_Completed`: The purchase is already completed.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/fees": { "put": { "tags": [ "Checkout" ], "summary": "Update fees", "description": "Set the shipping fee and the invoice fee for a checkout session. Send both fees together: whatever you send replaces the current fees, and Walley recalculates the totals.", "operationId": "setFees", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set the fees applied to a checkout, such as the shipping fee and the direct invoice notification fee.", "$ref": "#/components/schemas/SetFeesRequest" }, "example": { "shipping": { "description": "Shipping fee (incl. VAT)", "id": "shipping1", "unitPrice": 59, "vat": 25 } } } }, "required": true }, "responses": { "200": { "description": "The fees were set and the checkout totals were recalculated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The request contains properties with invalid values. Details are provided in the `errors` property.\n- `Fees_Not_Allowed`: Fees are not allowed for the intent of this checkout session.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Purchase_Commitment_Found`: The customer has clicked the Complete Purchase button and the checkout is therefore locked for modifications.\n- `Purchase_Completed`: The purchase is already completed.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/checkouts/{checkoutId}/reference": { "put": { "tags": [ "Checkout" ], "summary": "Update order reference", "description": "Set your own order reference on a checkout session. The reference follows the order into Order Management and settlement reports, so use it to match Walley's records against your own order numbers.", "operationId": "setOrderReference", "parameters": [ { "name": "checkoutId", "in": "path", "description": "The private id (privateId) of the checkout session, returned by Initialize Checkout.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set the merchant's own reference for an order.", "$ref": "#/components/schemas/SetOrderReferenceRequest" }, "example": { "reference": "ABCDEFGHJIKLMNOP" } } }, "required": true }, "responses": { "200": { "description": "The order reference was stored on the checkout session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseSuccess" }, "example": { "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7", "data": null } } } }, "400": { "description": "Bad or faulty request. Please examine the errors property for details.\n\nPossible `error.errors[].reason` values:\n- `Validation_Error`: The request contains properties with invalid values. Details are provided in the `errors` property.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "401": { "description": "The resource requested requires authentication.", "content": { "application/json": {} } }, "403": { "description": "Access to the requested resource is denied.", "content": { "application/json": {} } }, "404": { "description": "The resource requested was not found.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "423": { "description": "The resource requested is currently locked for modification. Try again.\n\nPossible `error.errors[].reason` values:\n- `Resource_Locked`: Another modifying request is currently being executed for the checkout session. Retry by sending the request again.", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "500": { "description": "An unhandled exception has occurred. Please contact Walley!", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } }, "default": { "description": "HTTP 900: The request was rejected by the server due to a business error.\n\nPossible `error.errors[].reason` values:\n- `Order_reference_already_set`: The order reference has already been set once after the completed purchase; it can only be updated once.\n- `Order_reference_could_not_be_set`: The order reference could not be set, for example because the order has already been captured (activated).", "content": { "application/json": { "schema": { "description": "Standard response envelope returned by the Checkout merchant API.", "$ref": "#/components/schemas/MerchantResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/purchase/authorizations": { "post": { "tags": [ "Customer Tokens" ], "summary": "Create authorization", "description": "Authorizes a payment for the order against a stored customer token. By default the authorization is processed asynchronously and returns 202 with an authorization id; when the schedule requests synchronous processing the call returns 200 with both an authorization id and an order id.", "operationId": "createAuthorization", "parameters": [ { "$ref": "#/components/parameters/CustomerTokens_IdempotencyKey" }, { "$ref": "#/components/parameters/CustomerTokens_CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" }, "examples": { "asynchronous": { "summary": "Asynchronous authorization (default)", "value": { "customerToken": "f590b7c4-0d2e-4d99-a3c7-5c1a39f45dce", "storeId": 1234, "order": { "items": [ { "id": "id-001", "description": "Description 001", "quantity": 1, "unitPrice": 10, "vat": 25 }, { "id": "id-002", "description": "Description 002", "quantity": 10, "unitPrice": 2, "vat": 12 } ], "currency": "EUR", "reference": "01478520", "actionReference": "reference 1234", "captureMode": "Auto" } } }, "synchronous": { "summary": "Synchronous authorization", "value": { "customerToken": "f590b7c4-0d2e-4d99-a3c7-5c1a39f45dce", "storeId": 1234, "order": { "items": [ { "id": "id-001", "description": "Description 001", "quantity": 1, "unitPrice": 10, "vat": 25 } ], "currency": "EUR", "reference": "01478520", "captureMode": "Auto" }, "attemptSchedule": { "preferSynchronous": true } } } } } } }, "responses": { "200": { "description": "Synchronous authorization succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeSyncResponse" }, "example": { "id": "17635160-e66f-46b9-84fc-db939005050c", "data": { "authorizationId": "f874e54d-2d58-4d31-a769-857dc3972979", "orderId": "4f35934d-dcf7-4929-b1ec-179155a6db58" } } } } }, "202": { "description": "Authorization accepted for asynchronous processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeAcceptedResponse" }, "example": { "id": "17635160-e66f-46b9-84fc-db939005050c", "data": { "authorizationId": "f874e54d-2d58-4d31-a769-857dc3972979" } } } } }, "400": { "description": "Validation failed (`VALIDATION_ERROR`), the order currency does not match the customer token currency (`INVALID_CURRENCY`), or the idempotency key was not a valid GUID (`IDEMPOTENCY_KEY_PARSING`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The resource requested requires authentication. The response has no body." }, "404": { "description": "The customer token was not found, or the caller lacks permission for the given store. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The token status prevents authorization, a synchronous payment attempt was declined, or the request conflicts with a previous request using the same idempotency key. When a synchronous attempt neither succeeded nor was declined outright (for example the provider has not yet reached a final state), the `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/CustomerTokens_InternalServerError" }, "503": { "description": "A downstream dependency timed out or was unavailable while processing the authorization (`DOWNSTREAM_TIMEOUT` or `DOWNSTREAM_ERROR`). When an asynchronous authorization could not be queued, the `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/purchase/authorizations/{authorizationId}": { "delete": { "tags": [ "Customer Tokens" ], "summary": "Cancel authorization", "description": "Cancels the remaining attempts of an asynchronous authorization, for example when the subscription ends, the invoice is credited or the customer changes payment method. The customer token is not affected. An authorization can only be cancelled while it is waiting for its first or next attempt; once it has succeeded, cancel or credit the order instead. A successful cancellation sends a `walley:authorization:cancelled` webhook. Cancelling an authorization that is already cancelled returns 200 again without sending the webhook.", "operationId": "cancelAuthorization", "parameters": [ { "$ref": "#/components/parameters/CustomerTokens_AuthorizationIdPath" }, { "$ref": "#/components/parameters/CustomerTokens_IdempotencyKey" }, { "$ref": "#/components/parameters/CustomerTokens_CorrelationId" } ], "responses": { "200": { "description": "The authorization is cancelled, or was already cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAuthorizationResponse" }, "example": { "id": "17635160-e66f-46b9-84fc-db939005050c", "data": { "authorizationId": "f874e54d-2d58-4d31-a769-857dc3972979" } } } } }, "400": { "description": "The idempotency key was not a valid GUID (`IDEMPOTENCY_KEY_PARSING`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The resource requested requires authentication. The response has no body." }, "404": { "description": "The authorization was not found, or the caller lacks permission for its store. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An attempt is being processed and may still charge the customer (`AUTHORIZATION_ATTEMPT_IN_PROGRESS`, try again shortly), the authorization has already succeeded or failed (`AUTHORIZATION_NOT_CANCELLABLE`), or the request conflicts with a previous request using the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/CustomerTokens_InternalServerError" }, "503": { "description": "A downstream dependency timed out or was unavailable while cancelling the authorization (`DOWNSTREAM_TIMEOUT` or `DOWNSTREAM_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/purchase/customer-tokens/{customerToken}": { "get": { "tags": [ "Customer Tokens" ], "summary": "Get customer token", "description": "Retrieves a stored customer token, including its status, payment method, and buyer contact details.", "operationId": "getCustomerToken", "parameters": [ { "$ref": "#/components/parameters/CustomerTokens_CustomerTokenPath" }, { "$ref": "#/components/parameters/CustomerTokens_CorrelationId" } ], "responses": { "200": { "description": "The customer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTokenResponse" }, "example": { "id": "ee634b96-f40e-426a-be3f-3533a7f6a400", "data": { "status": "Active", "paymentMethod": { "type": "Card", "maskedCardNumber": "516020******2127" }, "buyer": { "email": "customer@example.com", "mobilePhone": "+46701234567" } } } } } }, "401": { "description": "The resource requested requires authentication. The response has no body." }, "404": { "description": "The customer token was not found, or the caller lacks permission for its store. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/CustomerTokens_InternalServerError" }, "503": { "$ref": "#/components/responses/CustomerTokens_ServiceUnavailable" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Customer Tokens" ], "summary": "Update customer token", "description": "Updates the buyer contact details stored on a customer token.", "operationId": "updateCustomerToken", "parameters": [ { "$ref": "#/components/parameters/CustomerTokens_CustomerTokenPath" }, { "$ref": "#/components/parameters/CustomerTokens_IdempotencyKey" }, { "$ref": "#/components/parameters/CustomerTokens_CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyCustomerTokenRequest" }, "example": { "email": "updated@example.com", "mobilePhone": "+46701234567" } } } }, "responses": { "200": { "description": "The customer token was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" }, "example": { "id": "17635160-e66f-46b9-84fc-db939005050c" } } } }, "400": { "description": "The email address or mobile phone number is not in a valid format (`VALIDATION_ERROR`), or the idempotency key was not a valid GUID (`IDEMPOTENCY_KEY_PARSING`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The resource requested requires authentication. The response has no body." }, "403": { "description": "The customer token has already been cancelled (`TOKEN_CANCELLED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The customer token was not found, or the caller lacks permission for its store. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Buyer details cannot be updated because the token has no buyer (`VALIDATION_ERROR`), or the request conflicts with a previous request using the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/CustomerTokens_InternalServerError" }, "503": { "$ref": "#/components/responses/CustomerTokens_ServiceUnavailable" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Customer Tokens" ], "summary": "Cancel customer token", "description": "Cancels a customer token. Cancellation is processed asynchronously.", "operationId": "deleteCustomerToken", "parameters": [ { "$ref": "#/components/parameters/CustomerTokens_CustomerTokenPath" }, { "$ref": "#/components/parameters/CustomerTokens_IdempotencyKey" }, { "$ref": "#/components/parameters/CustomerTokens_CorrelationId" } ], "responses": { "202": { "description": "Cancellation accepted for asynchronous processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" }, "example": { "id": "17635160-e66f-46b9-84fc-db939005050c" } } } }, "400": { "description": "The idempotency key was not a valid GUID (`IDEMPOTENCY_KEY_PARSING`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The resource requested requires authentication. The response has no body." }, "403": { "description": "The customer token has already been cancelled (`TOKEN_CANCELLED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The customer token was not found, or the caller lacks permission for its store. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request conflicts with a previous request using the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/CustomerTokens_InternalServerError" }, "503": { "description": "A downstream dependency timed out or was unavailable while submitting the cancellation (`DOWNSTREAM_TIMEOUT` or `DOWNSTREAM_ERROR`). When the cancellation could not be queued, the `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/manage/orders": { "get": { "tags": [ "Order Management" ], "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Free-text search or a field query (`AND` + `:`,`<`,`>`,`<=`,`>=`). Example: `storeId:1158 AND status:Activated`." }, { "name": "filter", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Repeatable structured filter. Date-range filters apply to the order date fields; other filters narrow by field value." }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "" }, "description": "`field-direction` tokens joined by `|`, e.g. `placedAt-desc` or `_score-desc|placedAt-desc`. Defaults to score (when querying) then most-recent first." }, { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 }, "description": "1-based page number." }, { "name": "perPage", "in": "query", "schema": { "maximum": 1000, "minimum": 0, "type": "integer", "format": "int32", "default": 10 }, "description": "Page size, from 0 to 1000. Defaults to 10." } ], "responses": { "200": { "description": "A paged list of matching orders with pagination metadata and links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSearchResponse" }, "example": { "data": [ { "id": "c75f9525-ac1a-484e-8f9e-acd800cd1e3d", "orderNumber": "MX_210223_132648", "paymentMethod": "Invoice", "totalAmount": 2168.88, "totalVat": 433.78, "currency": "SEK", "status": "Activated", "countryCode": "SE", "placedAt": "2021-04-29T13:26:48.8534534+02:00", "expiresAt": null, "deliveryAddress": { "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "coAddress": null, "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": "+46701234567", "postalCode": "12345" }, "invoiceAddress": { "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "coAddress": null, "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": "+46701234567", "postalCode": "12345" } } ], "links": { "self": { "method": "GET", "href": "/manage/orders?page=1&perPage=10", "query": "page=1&perPage=10" }, "next": { "method": "GET", "href": "/manage/orders?page=2&perPage=10", "query": "page=2&perPage=10" } }, "metaData": { "totalNumberOfRecords": 32672, "numberOfPages": 3268, "currentPage": 1, "range": { "from": 1, "to": 10 } } } } } }, "422": { "description": "The search was rejected: invalid paging (`PAGE_RANGE`, `PER_PAGE_RANGE`), the paging limit was exceeded (`RESULT_WINDOW_SIZE`), the query or filters are malformed (`SEARCH_QUERY_INVALID`, `DUPLICATE_SEARCH_FILTER_PROPERTIES`), or the query parameters failed validation (`REQUEST_INVALID`, with the offending fields in `errors`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "searchOrders", "summary": "Search orders", "description": "Search orders across every store the caller has `read` permission for.\n\nCombine three inputs:\n- **`query`**: free-text (email, order reference, national registration number, article, and so on) or a field query. Field queries support `AND` and the comparison operators `:`, `<`, `>`, `<=`, `>=`. Example: `storeId:1158 AND status:Activated`.\n- **`filter`**: repeatable structured filters, including date-range filters on order date fields.\n- **`sort`**: `field-direction` tokens joined by `|` (for example `placedAt-desc`). Defaults to `_score-desc` when a free-text query is present, then `placedAt-desc`.\n\nResults are paged and wrapped in a standard envelope with `metadata` (total, pages, page, perPage) and HATEOAS `links`. Deep paging is bounded, and requests beyond the limit are rejected, so refine the query instead.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}": { "get": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "correlationId", "in": "query", "schema": { "type": "string" }, "description": "Optional. Asserts the order originated from this correlation id; a mismatch yields 404." } ], "responses": { "200": { "description": "The order. The representation is selected by the `Accept` header: the default `application/json` is the compact representation, `application/vnd.merchanthub.order+json` is the full representation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" }, "example": { "data": { "id": "853f3f82-ab12-47c3-9d97-af17009852cd", "reference": "MX_220921_111434", "paymentMethod": "Invoice", "totalAmount": 2459.49, "currency": "SEK", "status": "Activated", "salesSegment": "B2C", "countryCode": "SE", "productCode": "DI_001", "placedAt": "2022-09-21T11:14:35.7900411+00:00", "expiresAt": null, "customer": { "type": "Person", "name": "Test Testsson", "firstName": "Test", "lastName": "Testsson", "registrationNumber": "510731***3", "countryCode": "SE", "coAddress": "c/o Test Testsson", "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "postalCode": "12345", "email": "test@example.com", "mobilePhoneNumber": "+46701234567", "homePhoneNumber": "+46701234567" }, "deliveryAddress": { "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "coAddress": "c/o Test Testsson", "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": "+46701234567", "postalCode": "12345" }, "invoiceAddress": { "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "coAddress": "c/o Test Testsson", "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": "+46701234567", "postalCode": "12345" }, "items": [ { "articleNumber": "9364", "description": "Table lamp", "price": 237.22, "totalPrice": 474.44, "vatRate": 12, "currency": "SEK", "quantity": 2, "status": "Activated", "captureId": "117573228", "capturedAt": "2022-09-21T11:14:35.7900411+00:00", "refundedAt": null }, { "articleNumber": "10000", "description": "Discount 10%", "price": -393.78, "totalPrice": -393.78, "vatRate": 25, "currency": "SEK", "quantity": 1, "status": "Activated", "captureId": "117573228", "capturedAt": "2022-09-21T11:14:35.7900411+00:00", "refundedAt": null }, { "articleNumber": "3570", "description": "Mug", "price": 228.17, "totalPrice": 2281.7, "vatRate": 25, "currency": "SEK", "quantity": 10, "status": "Activated", "captureId": "117573228", "capturedAt": "2022-09-21T11:14:35.7900411+00:00", "refundedAt": null }, { "articleNumber": "2552", "description": "Mug 30 cl", "price": 157.5, "totalPrice": 787.5, "vatRate": 6, "currency": "SEK", "quantity": 5, "status": "Returned", "captureId": "117573228", "capturedAt": null, "refundedAt": "2022-09-21T11:15:02.2884003+00:00" }, { "articleNumber": "8484", "description": "Paper bag", "price": 144.46, "totalPrice": 288.92, "vatRate": 12, "currency": "SEK", "quantity": 2, "status": "Returned", "captureId": "117573228", "capturedAt": null, "refundedAt": "2022-09-21T11:16:27.8328129+00:00" }, { "articleNumber": "3755", "description": "Cotton rug 75x200 cm", "price": 105.21, "totalPrice": 105.21, "vatRate": 12, "currency": "SEK", "quantity": 1, "status": "Returned", "captureId": "117573228", "capturedAt": null, "refundedAt": "2022-09-21T11:16:27.8328129+00:00" }, { "articleNumber": "1156", "description": "Cheese dome", "price": 97.35, "totalPrice": 97.35, "vatRate": 12, "currency": "SEK", "quantity": 1, "status": "NotActivated", "captureId": null, "capturedAt": null, "refundedAt": null } ], "invoices": [ { "invoiceNumber": "117573228", "paymentStatus": "NotPaid", "totalAmount": 2362.14, "createdAt": "2022-09-21T11:14:35.8582677+00:00", "dueDate": "2022-10-31T23:59:59+01:00" } ] }, "links": { "self": { "method": "GET", "href": "/orders/853f3f82-ab12-47c3-9d97-af17009852cd", "query": "" }, "refund": { "method": "POST", "href": "/orders/853f3f82-ab12-47c3-9d97-af17009852cd/refund", "query": "" } }, "metaData": {} } }, "application/vnd.merchanthub.order+json": { "schema": { "$ref": "#/components/schemas/OrderDetailsResponse" }, "examples": { "fullOrder": { "$ref": "#/components/examples/Manage_FullOrder" } } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId` (or, when `correlationId` is supplied, it does not belong to this order). The response has no body." } }, "operationId": "getOrder", "summary": "Get order", "description": "Retrieve a single order by id, including its current purchase, rows, statuses, connected invoice/settlement accounts and correlation ids.\n\nTwo representations are available via content negotiation on the `Accept` header:\n- `application/vnd.merchanthub.order+json`: the full order representation.\n- anything else (default): the compact order representation.\n\nSupplying `correlationId` asserts the order was created from that correlation id; if it does not match, the order is treated as not found.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/capture": { "post": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "requestBody": { "required": true, "description": "Amount and, optionally, the specific articles/quantities to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureOrderRequest" }, "examples": { "fullCapture": { "summary": "Activate the whole order by amount", "value": { "amount": 285, "description": "Capture description", "actionReference": "test-captureref-123" } }, "partCaptureByItems": { "summary": "Activate specific articles", "value": { "amount": 285, "actionReference": "test-captureref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2 } ] } }, "replaceItems": { "summary": "Replace the article set and activate", "value": { "amount": 285, "actionReference": "test-captureref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1, "vat": 25 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2, "vat": 25 } ], "replaceItems": true } } } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing. Walley processes the action and the order is updated shortly after. Poll `GET /manage/orders/{orderId}` for the resulting state.", "headers": { "Location": { "description": "Path of the affected order to poll for the updated state.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId` (or, when `correlationId` is supplied, it does not belong to this order). The response has no body." }, "422": { "description": "The activation was rejected. The body is a problem object whose `code` identifies the problem. Request-validation failures use `REQUEST_INVALID` and list the offending fields in `errors`.\n\nProblem codes for this action:\n\n- `CAPTURE_AMOUNT_MUST_NOT_BE_NEGATIVE`\n- `CAPTURE_AMOUNT_TOO_LARGE`\n- `CAPTURE_AMOUNT_HAS_TOO_MANY_DECIMALS`\n- `CAPTURE_AMOUNT_GREATER_THAN_INVOICE_AMOUNT`\n- `CAPTURE_ITEMS_AMOUNT_NOT_EQUAL_TO_TOTAL_AMOUNT`\n- `CAPTURE_ITEMS_UNITPRICE_HAS_TOO_MANY_DECIMALS`\n- `CAPTURE_ITEMS_MISSING_ID`\n- `CAPTURE_DESCRIPTION_TOO_LONG`\n- `CAPTURE_ORDER_ALREADY_CAPTURED`\n- `CAPTURE_INVALID_INVOICE_STATUS`\n- `ACTION_REFERENCE_TOO_LONG`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "captureOrder", "summary": "Activate (capture) order", "description": "Activate (capture) an order, or part of it, so it can be shipped and invoiced. Moves the order out of `Not activated`. Activating only some rows or quantities leaves it `Partly activated`, and the remainder can be activated later (e.g. back-ordered items).\n\nOnly orders in `Not activated` or `Partly activated` can be activated. For invoice orders, a notification is sent to the customer on each activation.\n\nBody rules:\n- `amount` must equal the sum of `items` (`unitPrice × quantity`) when items are supplied, and must not be negative.\n- omit `items` to capture the whole order for `amount`.\n- set `replaceItems: true` to replace the order’s article set with `items` (every item must then carry an `id`).\n\nThe action is processed asynchronously and returns `202 Accepted`. Poll the order for the resulting state.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/cancel": { "post": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "requestBody": { "required": false, "description": "Optional. May be empty or carry only an action reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" }, "example": { "actionReference": "test-cancelref-123" } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing. Walley processes the action and the order is updated shortly after. Poll `GET /manage/orders/{orderId}` for the resulting state.", "headers": { "Location": { "description": "Path of the affected order to poll for the updated state.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId` (or, when `correlationId` is supplied, it does not belong to this order). The response has no body." }, "422": { "description": "The cancellation was rejected. The body is a problem object whose `code` identifies the problem. Request-validation failures use `REQUEST_INVALID` and list the offending fields in `errors`.\n\nProblem codes for this action:\n\n- `CANCEL_INVALID_INVOICE_STATUS`\n- `ACTION_REFERENCE_TOO_LONG`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "cancelOrder", "summary": "Cancel order", "description": "Cancel an order that has not yet been fully activated. An order in `Not activated` becomes `Canceled`. A `Partly activated` order becomes `Activated`, and the already-activated part stands. Cancellable statuses: `Not activated`, `Partly activated`, `Expired`, `On hold`.\n\nThe body is optional. Send an empty body, or supply an `actionReference` to tag the action in reporting.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/refund": { "post": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "requestBody": { "required": true, "description": "Amount and the articles, fees, discounts and replacements to return.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundOrderRequest" }, "examples": { "fullRefund": { "summary": "Return the whole order by amount", "value": { "amount": 285, "description": "Refund description", "actionReference": "test-refundref-123" } }, "partRefundByItems": { "summary": "Return specific articles", "value": { "amount": 285, "actionReference": "test-refundref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2 } ] } }, "refundWithFee": { "summary": "Return an article and charge a return fee", "value": { "amount": 75, "actionReference": "test-refundref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 100, "quantity": 1, "vat": 25 }, { "id": "10002", "description": "Return fee", "unitPrice": -25, "quantity": 1, "vat": 25, "type": "FEE" } ] } } } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing. Walley processes the action and the order is updated shortly after. Poll `GET /manage/orders/{orderId}` for the resulting state.", "headers": { "Location": { "description": "Path of the affected order to poll for the updated state.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId` (or, when `correlationId` is supplied, it does not belong to this order). The response has no body." }, "422": { "description": "The return was rejected. The body is a problem object whose `code` identifies the problem. Request-validation failures use `REQUEST_INVALID` and list the offending fields in `errors`.\n\nProblem codes for this action:\n\n- `REFUND_AMOUNT_MUST_BE_POSITIVE`\n- `REFUND_AMOUNT_MUST_MATCH_SUM_OF_ARTICLES`\n- `REFUND_AMOUNT_HAS_TOO_MANY_DECIMALS`\n- `REFUND_VAT_HAS_TOO_MANY_DECIMALS`\n- `REFUND_DESCRIPTION_TOO_LONG`\n- `REFUND_ORDER_ALREADY_FULLY_REFUNDED`\n- `REFUND_UNMATCHED_RETURN_ARTICLES`\n- `REFUND_ITEM_ID_TOO_LONG`\n- `REFUND_ITEM_DESCRIPTION_TOO_LONG`\n- `REFUND_ITEM_QUANTITY_MUST_BE_POSITIVE`\n- `REFUND_ITEM_UNITPRICE_HAS_TOO_MANY_DECIMALS`\n- `REFUND_ITEM_FEE_OR_DISCOUNT_ID_AND_DESCRIPTION_REQUIRED`\n- `REFUND_REPLACEMENT_ITEM_QUANTITY_INVALID`\n- `ACTION_REFERENCE_TOO_LONG`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "refundOrder", "summary": "Return (refund) order", "description": "Return (refund) an order, in full or in part. Use this when a customer returns articles: it credits the customer and adjusts the order. Only `Activated` and `Partly activated` orders are returnable.\n\n`items` may mix four kinds, distinguished by `type`: ordinary purchase rows (no/other type), `FEE`, `DISCOUNT` and `REPLACEMENT`. Fees and discounts require both `id` and `description`. When `items` are supplied, `amount` must equal their signed total. A replacement that pairs with an opposite-priced purchase row nets out rather than double-counting.\n\nAlways processed asynchronously, returning `202 Accepted`. Poll the order for the resulting state. A zero-amount refund is accepted and treated as a no-op.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/extend": { "post": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "responses": { "202": { "description": "Accepted for asynchronous processing. Walley processes the action and the order is updated shortly after. Poll `GET /manage/orders/{orderId}` for the resulting state.", "headers": { "Location": { "description": "Path of the affected order to poll for the updated state.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId` (or, when `correlationId` is supplied, it does not belong to this order). The response has no body." }, "422": { "description": "The order cannot be extended (no open pending invoice, not close to expiration, already extended, or a non-extendable payment method). The body is a problem object whose `code` identifies the problem. Problem code for this action: `ORDER_CANNOT_BE_EXTENDED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "extendOrder", "summary": "Extend order", "description": "Extend the expiration of an order’s pending invoice so the customer has longer to pay, up to 180 days from purchase. Can be done **once** per order; the number of days available depends on the partner agreement.\n\nOnly possible when the order has an open pending invoice and is close to expiration, and the payment method is invoice-like. Card, bank transfer, Swish, MobilePay, Amex and Vipps orders cannot be extended. Otherwise the request is rejected with `ORDER_CANNOT_BE_EXTENDED`. Takes no request body.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/reauthorize": { "post": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "requestBody": { "required": true, "description": "New total amount and, optionally, the article set to authorize.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthorizeOrderRequest" }, "examples": { "withItems": { "summary": "Reauthorize with a new article set", "value": { "amount": 285, "actionReference": "test-captureref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1, "vat": 25 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2, "vat": 25 } ] } }, "amountOnly": { "summary": "Reauthorize the amount only", "value": { "amount": 280, "actionReference": "test-captureref-123" } } } } } }, "responses": { "201": { "description": "The reauthorization increases the order amount, so an additional credit check runs. Poll the reauthorization at the `Location` path for the outcome (`Completed` or `Failed`).", "headers": { "Location": { "description": "Path of the reauthorization to poll for the outcome.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6/reauthorize/ca81364e-895f-4250-bdb2-a9dafa13c4bc" ] } } } }, "202": { "description": "Accepted for asynchronous processing (amount unchanged or lowered). Walley processes the action and the order is updated shortly after. Poll `GET /manage/orders/{orderId}` for the resulting state.", "headers": { "Location": { "description": "Path of the affected order to poll for the updated state.", "schema": { "type": "string", "examples": [ "/manage/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "403": { "description": "The caller lacks the required permission on the order’s store. Order actions need `write` permission, and reading needs `read`. The response has no body." }, "404": { "description": "No order matches `orderId`. The response has no body." }, "409": { "description": "A conflicting reauthorization exists: a reauthorization is already in process for this order (`REAUTHORIZE_ALREADY_IN_PROCESS`), or the idempotency key was already used for a different request (`IDEMPOTENCY_KEY_ALREADY_IN_USE_FOR_DIFFERENT_REQUEST`). The body is a problem object whose `code` identifies the problem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } }, "422": { "description": "The reauthorization was rejected. The body is a problem object whose `code` identifies the problem. Request-validation failures use `REQUEST_INVALID` and list the offending fields in `errors`.\n\nProblem codes for this action:\n\n- `REAUTHORIZE_AMOUNT_MUST_BE_GREATER_THAN_ZERO`\n- `REAUTHORIZE_AMOUNT_MUST_MATCH_SUM_OF_ARTICLES`\n- `REAUTHORIZE_AMOUNT_HAS_TOO_MANY_DECIMALS`\n- `REAUTHORIZE_ORDER_INCREASE_ABOVE_CURRENT_TOTAL_AMOUNT_IS_NOT_ALLOWED`\n- `REAUTHORIZE_INCREASED_AMOUNT_NOT_AVAILABLE_FOR_PREPAID_PAYMENT_METHOD`\n- `REAUTHORIZE_DESCRIPTION_TOO_LONG`\n- `REAUTHORIZE_ID_TOO_LONG`\n- `REAUTHORIZE_UNIT_PRICE_HAS_TOO_MANY_DECIMALS`\n- `REAUTHORIZE_QUANTITY_MUST_BE_GREATER_THAN_ZERO`\n- `REAUTHORIZE_VAT_MUST_BE_GREATER_THAN_ZERO`\n- `REAUTHORIZE_ORDER_ALREADY_CAPTURED`\n- `REAUTHORIZE_INVALID_INVOICE_STATUS`\n- `REAUTHORIZE_MATCHING_ARTICLES_WITH_DIFFERENT_VAT`\n- `REAUTHORIZE_ARTICLE_EXISTS_BUT_OTHER_INFORMATION`\n- `ACTION_REFERENCE_TOO_LONG`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageProblemDetails" } } } } }, "operationId": "reauthorizeOrder", "summary": "Reauthorize order", "description": "Change the not-yet-captured part of an order: replace the remaining article set and/or change the authorized amount. Already captured items are unaffected.\n\nOnly orders in `Not activated` or `Partly activated` can be reauthorized. Keeping the amount the same or lowering it is processed asynchronously (`202`); increasing it triggers an additional credit check (`201`). Poll the reauthorization at the returned `Location` for `Completed` or `Failed`. Increasing the amount is only available for credit payment methods, not prepaid ones.\n\nBody rules:\n- `amount` must equal the sum of `items` (`unitPrice × quantity`) when items are supplied; it must be greater than zero.\n- omit `items` to reauthorize the amount only.", "security": [ { "bearerAuth": [] } ] } }, "/manage/orders/{orderId}/reauthorize/{reauthorizeId}": { "get": { "tags": [ "Order Management" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order identifier (GUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "reauthorizeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Reauthorization identifier (GUID), taken from the `Location` header of a `201` reauthorize response.", "example": "ca81364e-895f-4250-bdb2-a9dafa13c4bc" } ], "responses": { "200": { "description": "The reauthorization outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthorizationResponse" }, "example": { "data": { "id": "ca81364e-895f-4250-bdb2-a9dafa13c4bc", "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "Completed", "createdAt": "2023-01-17T12:09:27.029057+00:00" }, "links": {}, "metaData": {} } } } }, "403": { "description": "The caller lacks `read` permission on the order’s store. The response has no body." }, "404": { "description": "No order matches `orderId`, or no reauthorization matches `reauthorizeId` for this order. The response has no body." } }, "operationId": "getReauthorization", "summary": "Get reauthorization outcome", "description": "Poll the outcome of a reauthorization that returned `201` (increased amount, additional credit check). `Completed` means the reauthorization succeeded; `Failed` means it was rejected, for example when the credit check was denied.", "security": [ { "bearerAuth": [] } ] } }, "/reports/settlements": { "get": { "tags": [ "Settlements" ], "summary": "Search settlements", "description": "Returns a paged list of settlements across all your stores. Use `query` for free-text and property searches (for example by date, currency, store, or reference); page through large result sets with `page` and `perPage`.", "operationId": "searchSettlements", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Free-text search, or a property search to filter settlements. Properties can be combined with `AND` and compared with `:`, `<`, `>`, `<=`, `>=`. Spaces must be URL-encoded as `%20`. Examples: `startDate:>2022-12-17`, `currency:SEK`, `storeId:4567`, `reference:2134`, `startDate:>=2022-12-01%20AND%20endDate:<=2022-12-08%20AND%20currency:SEK`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of settlements per page. Largest allowed value is 1000.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000, "default": 10 } } ], "responses": { "200": { "description": "A paged list of settlements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementSearchResponse" }, "example": { "data": [ { "id": "1", "startDate": "2022-12-30T00:00:00", "endDate": "2022-12-30T00:00:00", "storeId": 1, "ingoingBalance": 0, "totalAmount": 100000, "currency": "SEK", "netSales": 100000, "paidOutAt": "2023-01-02T11:00:10.000000+01:00", "generatedAt": "2023-01-02T11:00:10.000000+01:00", "captured": 103000, "refunded": -3000, "reference": "2134", "compensations": 0, "adjustments": 0, "links": { "pdf": { "method": "GET", "href": "/reports/settlements/1/file/pdf", "query": "" }, "transactions": { "method": "GET", "href": "/reports/settlements/1/transactions", "query": "" } } } ], "links": { "self": { "method": "GET", "href": "/reports/settlements?page=1&perPage=1", "query": "page=1&perPage=1" }, "next": { "method": "GET", "href": "/reports/settlements?page=2&perPage=1", "query": "page=2&perPage=1" } }, "metaData": { "totalNumberOfRecords": 100, "numberOfPages": 100, "currentPage": 1, "range": { "from": 1, "to": 1 } } } } } }, "401": { "description": "Unauthorized. Token verification needed. The response has no body." }, "409": { "description": "A request with the same idempotency key is already in progress. The body is a problem object whose `code` identifies the problem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementsProblemDetails" } } } }, "422": { "description": "The search was rejected: the query has an incorrect format (`SEARCH_QUERY_INVALID`), the paging limit was exceeded (`RESULT_WINDOW_SIZE`), or the query parameters failed validation (`REQUEST_INVALID`, with the offending fields in `errors`, for example `PER_PAGE_RANGE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementsProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/settlements/{settlementId}/file/pdf": { "get": { "tags": [ "Settlements" ], "summary": "Get settlement PDF", "description": "Downloads the settlement as a PDF document. The PDF aggregates all transactions and fees (if any), giving an overview of the transactions for the settlement period. Depending on the merchant setup the PDF might not be available.", "operationId": "getSettlementPdf", "parameters": [ { "name": "settlementId", "in": "path", "required": true, "description": "Identifier of the settlement.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The settlement PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized. Token verification needed. The response has no body." }, "403": { "description": "Permissions needed, for example trying to fetch content for a store you do not have permission to. The response has no body." }, "404": { "description": "The settlement PDF was not found. The response has no body." } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/settlements/{settlementId}/transactions": { "get": { "tags": [ "Settlements" ], "summary": "Get settlement transactions", "description": "Returns a paged list of the transactions included in a settlement. The default response format is JSON; set the `Accept` header to `text/csv` to receive the transactions as a CSV file using the same format as the settlement CSV example files.", "operationId": "getSettlementTransactions", "parameters": [ { "name": "settlementId", "in": "path", "required": true, "description": "Identifier of the settlement.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 2147483647, "default": 1 } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of transactions per page. Largest allowed value is 10000.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "default": 1000 } }, { "name": "includeProductCode", "in": "query", "required": false, "description": "Include the product code for each transaction.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paged list of settlement transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementTransactionsResponse" }, "example": { "data": [ { "customerNumber": "", "firstName": "Test", "lastName": "Test", "amount": 1000, "purchaseDate": "2022-01-01", "transactionDate": "2020-01-01", "orderNumber": "TEST_230116_011045", "invoiceNumber": "11111111", "type": "Purchase", "totalVatAmountPerRate": [ { "vatRate": 25, "amount": 180 }, { "vatRate": 6, "amount": 5.66 } ], "currency": "SEK", "orderId": "4f35934d-dcf7-4929-b1ec-179155a6db58", "productCode": "DI001" } ], "links": { "self": { "method": "GET", "href": "/reports/settlements/1/transactions?page=1&perPage=1", "query": "page=1&perPage=1" }, "next": { "method": "GET", "href": "/reports/settlements/1/transactions?page=2&perPage=1", "query": "page=2&perPage=1" } }, "metaData": { "totalNumberOfRecords": 100, "numberOfPages": 100, "currentPage": 1, "range": { "from": 1, "to": 1 } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "Customer Number;First Name;Last Name;Amount;Purchase Date;Transaction Date;Order Number;Invoice Number;Type;Settlement Date\nCust_1;Approved08;Sweden08;1449.00;2018-09-10;2018-09-09;Order222;1263308;Purchase;2018-09-11\nCust_1;Approved08;Sweden08;-21.01;2018-09-10;2018-09-09;Order222;1263308;Service fee, subject to VAT;2018-09-11\n" } } }, "401": { "description": "Unauthorized. Token verification needed. The response has no body." }, "403": { "description": "Permissions needed, for example trying to fetch content for a store you do not have permission to. The response has no body." }, "404": { "description": "The settlement transactions were not found. The response has no body." }, "409": { "description": "A request with the same idempotency key is already in progress. The body is a problem object whose `code` identifies the problem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementsProblemDetails" } } } }, "422": { "description": "The query parameters failed validation (`REQUEST_INVALID`, with the offending fields in `errors`, for example `PAGE_RANGE` or `PER_PAGE_RANGE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementsProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "TokenRequest": { "type": "object", "description": "Form parameters for the client credentials token request.", "properties": { "client_id": { "type": "string", "description": "The client id of your Walley API credentials." }, "client_secret": { "type": "string", "description": "The client secret of your Walley API credentials." }, "grant_type": { "type": "string", "description": "OAuth2 grant type. Use `client_credentials`.", "examples": [ "client_credentials" ] }, "scope": { "type": "string", "description": "Space-separated list of scopes being requested. Use the scope provided with your Walley API credentials." } }, "required": [ "client_id", "client_secret", "grant_type", "scope" ] }, "TokenResponse": { "type": "object", "description": "The issued OAuth2 access token with its type and lifetime.", "properties": { "token_type": { "type": "string", "description": "Token type. Always `Bearer`.", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Lifetime of the access token in seconds.", "examples": [ 3599 ] }, "access_token": { "type": "string", "description": "The bearer access token to send in the `Authorization` header of Walley API requests." } }, "required": [ "token_type", "expires_in", "access_token" ] }, "TokenErrorResponse": { "type": "object", "description": "Error response for a rejected token request.", "properties": { "error": { "type": "string", "description": "Machine-readable error code, e.g. `invalid_request` or `invalid_client`.", "examples": [ "invalid_request" ] }, "error_description": { "type": "string", "description": "Human-readable explanation of the error." } }, "required": [ "error" ] }, "AddressRequestItem": { "type": "object", "properties": { "companyName": { "type": [ "null", "string" ], "description": "The name of the company, used for business addresses." }, "firstName": { "maxLength": 75, "type": [ "null", "string" ], "description": "The customer's first name." }, "lastName": { "maxLength": 75, "type": [ "null", "string" ], "description": "The customer's last name." }, "coAddress": { "maxLength": 75, "type": [ "null", "string" ], "description": "The care-of (c/o) address line." }, "address": { "maxLength": 100, "type": [ "null", "string" ], "description": "The primary address row." }, "address2": { "maxLength": 100, "type": [ "null", "string" ], "description": "An additional address row." }, "postalCode": { "maxLength": 25, "type": [ "null", "string" ], "description": "The postal code." }, "city": { "maxLength": 50, "type": [ "null", "string" ], "description": "The city." }, "countryCode": { "maxLength": 2, "type": [ "null", "string" ], "description": "The country code; only used when shipping to multiple countries." } }, "description": "A postal address supplied for a checkout, such as a customer's billing or delivery address." }, "AddressResponseItem": { "type": "object", "properties": { "id": { "type": [ "null", "string" ], "description": "The id of the address." }, "companyName": { "type": [ "null", "string" ], "description": "The name of the company." }, "firstName": { "type": [ "null", "string" ], "description": "The customer's first name." }, "lastName": { "type": [ "null", "string" ], "description": "The customer's last name." }, "coAddress": { "type": [ "null", "string" ], "description": "The care-of (c/o) address line." }, "address": { "type": [ "null", "string" ], "description": "The primary address row." }, "address2": { "type": [ "null", "string" ], "description": "An additional address row." }, "postalCode": { "type": [ "null", "string" ], "description": "The postal code." }, "city": { "type": [ "null", "string" ], "description": "The city." }, "country": { "type": [ "null", "string" ], "description": "The resolved country name." }, "countryCode": { "type": [ "null", "string" ], "description": "The country code." } }, "description": "A postal address returned for a checkout, such as a customer's billing or delivery address, including the resolved country name." }, "ArticleRequestItem": { "required": [ "description", "id", "quantity", "unitPrice", "vat" ], "type": "object", "properties": { "description": { "type": "string", "description": "The item description, shown on the invoice or receipt. Text longer than 50 characters is truncated." }, "id": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The item id or equivalent, shown on the invoice or receipt. Maximum 50 characters." }, "type": { "type": [ "null", "string" ], "description": "An optional item type. `GiftCard` is currently the only value accepted on a request." }, "quantity": { "maximum": 99999999, "minimum": 1, "type": [ "null", "integer" ], "description": "The quantity of the item. Allowed values are 1 to 99999999.", "format": "int32" }, "unitPrice": { "maximum": 999999.99, "minimum": -999999.99, "type": [ "null", "number" ], "description": "The unit price of the item including VAT; both positive and negative values are allowed. Maximum 2 decimals.", "format": "double" }, "unitWeight": { "maximum": 999999.99999, "minimum": 0, "type": [ "null", "number" ], "description": "The weight of the item; only non-negative values are allowed.", "format": "double" }, "vat": { "maximum": 100, "minimum": 0, "type": [ "null", "number" ], "description": "The VAT of the item in percent. Allowed values are 0 to 100.", "format": "double" }, "requiresElectronicId": { "type": "boolean", "description": "Forces the customer to strongly identify with electronic id, such as Mobilt BankID, at purchase to reduce fraud risk on credit products." }, "minimumAge": { "maximum": 120, "minimum": 1, "type": [ "null", "integer" ], "description": "The minimum age allowed to purchase this product; triggers national identification number verification with electronic id. Allowed values are 1 to 120.", "format": "int32" }, "maximumAge": { "maximum": 120, "minimum": 1, "type": [ "null", "integer" ], "description": "The maximum age allowed to purchase this product; triggers national identification number verification with electronic id. Allowed values are 1 to 120.", "format": "int32" }, "sku": { "maxLength": 1024, "minLength": 0, "type": [ "null", "string" ], "description": "A stock keeping unit; a unique alphanumeric code identifying product types and variations. Maximum 1024 characters." }, "shipping": { "oneOf": [ { "type": "null" }, { "description": "Shipping details for this item, such as weight, dimensions, tags and delivery interval.", "$ref": "#/components/schemas/ArticleShippingRequestItem" } ], "description": "Shipping details for this item, such as weight, dimensions, tags and delivery interval." } }, "description": "A single item in the checkout cart, describing a product or gift card." }, "ArticleResponseItem": { "required": [ "id", "description", "unitPrice", "quantity", "vat" ], "type": "object", "properties": { "id": { "type": "string", "description": "The item id, shown on the invoice or receipt." }, "description": { "type": "string", "description": "The item description." }, "type": { "description": "The type of the item, such as a gift card.", "$ref": "#/components/schemas/ArticleType" }, "unitPrice": { "type": "number", "description": "The unit price of the item including VAT.", "format": "double" }, "unitWeight": { "type": "number", "description": "The weight of the item.", "format": "double" }, "quantity": { "type": "integer", "description": "The quantity of the item.", "format": "int32" }, "vat": { "type": "number", "description": "The VAT of the item in percent.", "format": "double" }, "sku": { "type": "string", "description": "The stock keeping unit identifying the item." }, "usedAmount": { "type": "number", "description": "The amount of a gift card that has been used.", "format": "double" }, "requiresElectronicId": { "type": "boolean", "description": "Whether the item requires the customer to identify with electronic id at purchase." }, "minimumAge": { "type": "integer", "description": "The minimum age allowed to purchase the item.", "format": "int32" }, "maximumAge": { "type": "integer", "description": "The maximum age allowed to purchase the item.", "format": "int32" } }, "description": "A single item in the checkout cart, describing a product or gift card." }, "ArticleShippingRequestItem": { "type": "object", "properties": { "tags": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Tags describing shipping constraints or options for this item." }, "unitWeight": { "type": [ "null", "number" ], "description": "The weight of a single unit of the item.", "format": "double" }, "dimensions": { "oneOf": [ { "type": "null" }, { "description": "The physical dimensions of the item.", "$ref": "#/components/schemas/ShippingDimensionsRequestItem" } ], "description": "The physical dimensions of the item." }, "shippingInterval": { "oneOf": [ { "type": "null" }, { "description": "The expected delivery window for the item.", "$ref": "#/components/schemas/ShippingIntervalRequestItem" } ], "description": "The expected delivery window for the item." } }, "description": "Shipping details for a single cart item, such as its weight, dimensions, tags and delivery interval." }, "ArticleType": { "enum": [ "GiftCard", "ShippingFee", "MerchantNotificationFee", "Upsell" ], "type": "string", "description": "The special article kind of an order item: a gift card, a shipping fee, a merchant notification fee, or an upsell item." }, "BusinessCustomerRequestItem": { "type": "object", "properties": { "organizationNumber": { "maxLength": 50, "type": [ "null", "string" ], "description": "The organization number of the company. Maximum 50 characters." }, "buyer": { "oneOf": [ { "type": "null" }, { "description": "The person performing the purchase on behalf of the company.", "$ref": "#/components/schemas/CheckoutBuyer" } ], "description": "The person performing the purchase on behalf of the company." }, "invoiceReference": { "maxLength": 50, "type": [ "null", "string" ], "description": "A reference shown on the invoice. Maximum 50 characters." }, "invoiceTag": { "maxLength": 50, "type": [ "null", "string" ], "description": "A tag shown on the invoice. Maximum 50 characters." }, "eInvoiceAddress": { "maxLength": 50, "type": [ "null", "string" ], "description": "The company's electronic invoice address. Maximum 50 characters." }, "eInvoiceType": { "maxLength": 50, "type": [ "null", "string" ], "description": "The electronic invoice type or format. Maximum 50 characters." }, "invoiceEmail": { "maxLength": 256, "type": [ "null", "string" ], "description": "The email address to which the invoice is sent." }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "description": "The delivery address for the business customer.", "$ref": "#/components/schemas/AddressRequestItem" } ], "description": "The delivery address for the business customer." } }, "description": "Business customer details supplied when initializing a B2B checkout." }, "CheckoutBuyer": { "type": "object", "properties": { "firstName": { "maxLength": 50, "type": [ "null", "string" ], "description": "The buyer's first name." }, "lastName": { "maxLength": 50, "type": [ "null", "string" ], "description": "The buyer's last name." }, "email": { "maxLength": 256, "type": [ "null", "string" ], "description": "The buyer's email address." }, "mobilePhoneNumber": { "maxLength": 50, "type": [ "null", "string" ], "description": "The buyer's mobile phone number; foreign numbers must include a valid prefix such as +46 or 0046." } }, "description": "The individual person acting as the buyer on behalf of a business customer." }, "CardInfo": { "required": [ "lastFour", "expiryDate" ], "type": "object", "properties": { "lastFour": { "type": "string", "description": "The last four digits of the card number." }, "expiryDate": { "type": "string", "description": "The expiry date of the card." } }, "description": "Details of the card used for a purchase, such as the last four digits and the expiry date." }, "CartRequestItem": { "type": "object", "properties": { "shippingProperties": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Optional key/value properties used to customize which delivery methods are available based on the cart, when a delivery module is used." }, "items": { "type": [ "null", "array" ], "items": { "description": "A single item in the checkout cart, describing a product or gift card.", "$ref": "#/components/schemas/ArticleRequestItem" }, "description": "The cart items." } }, "description": "The checkout cart, containing the cart items being purchased and optional shipping properties." }, "CartResponseItem": { "type": "object", "properties": { "totalAmount": { "type": "number", "description": "The total amount of the cart items.", "format": "double" }, "items": { "type": "array", "items": { "description": "A single item in the checkout cart, describing a product or gift card.", "$ref": "#/components/schemas/ArticleResponseItem" }, "description": "The current cart items." } }, "description": "The checkout cart, containing the current cart items and the total amount." }, "CheckoutMetadataRequest": { "type": "object", "properties": { "metadata": { "type": [ "null", "object" ], "description": "Custom merchant metadata in key/value form (any valid JSON values), not processed by Walley and returned when retrieving the checkout.\nKey casing is preserved, and the metadata is limited to 200000 characters when serialized as JSON." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set or update the custom metadata associated with a checkout." }, "CheckoutStatus": { "enum": [ "Aborted", "Initialized", "CustomerIdentified", "CommittedToPurchase", "PurchaseCompleted", "Identifying", "Identified", "IdentificationAborted", "AgreementRegistered" ], "type": "string", "description": "The current lifecycle status of a checkout, from initialization through customer identification to a completed or aborted purchase." }, "CustomerType": { "enum": [ "PrivateCustomer", "BusinessCustomer" ], "type": "string", "description": "Whether the checkout is for a private or business customer." }, "CustomFieldsGroupRequestItem": { "required": [ "id", "fields" ], "type": "object", "properties": { "id": { "type": "string", "description": "The id of the group. Must be unique across the custom field groups." }, "name": { "type": [ "null", "string" ], "description": "The header rendered above the group section." }, "fields": { "minItems": 1, "type": "array", "items": { "description": "A single custom field within a group.", "$ref": "#/components/schemas/Field" }, "description": "The fields rendered in the group." }, "localizations": { "type": [ "null", "object" ], "additionalProperties": { "description": "Language-specific overrides for a custom field group.", "$ref": "#/components/schemas/GroupLocale" }, "description": "Per-language overrides for the group's name and metadata, keyed by ISO language code." }, "metadata": { "type": [ "null", "object" ], "description": "A custom metadata object for the group." } }, "description": "A named group of custom checkout fields, with optional per-language localizations." }, "CustomFieldType": { "enum": [ "Checkbox", "Text", "Toggle" ], "type": "string", "description": "The kind of input control used to render a custom checkout field: a checkbox, a free-text field or a toggle." }, "CustomShippingPropertiesRequest": { "type": "object", "properties": { "shippingProperties": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Key/value properties used to customize which delivery methods are available for the checkout." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set the custom shipping properties used to configure shipping options for a checkout." }, "DateTimeIntervalRequestItem": { "type": "object", "properties": { "startDate": { "type": [ "null", "string" ], "description": "The start of the interval.", "format": "date-time" }, "endDate": { "type": [ "null", "string" ], "description": "The end of the interval.", "format": "date-time" } }, "description": "A time span defined by an optional start and end date, used to express a delivery or shipping window." }, "DeliveryContactInformationResponseItem": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address used to reach the customer about their delivery." }, "mobilePhoneNumber": { "type": "string", "description": "The mobile phone number used to reach the customer about their delivery." } }, "description": "Contact details used to reach the customer about their delivery, such as an email address and mobile phone number." }, "Destination": { "required": [ "mobilePhoneNumber" ], "type": "object", "properties": { "mobilePhoneNumber": { "type": "string", "description": "Mobile phone number the payment link is delivered to, by SMS or as a push notification in the Walley app. Accepted in the checkout country's local format or in international (E.164) format." }, "email": { "type": [ "null", "string" ], "description": "Email address used, when provided, to match an existing Walley customer so the payment link can be delivered as a push notification in the Walley app. The link is not sent by email." } }, "description": "The recipient of a payment link notification, identified by mobile phone number and an optional email address." }, "CheckoutError": { "required": [ "reason" ], "type": "object", "properties": { "reason": { "type": "string", "description": "A machine-readable reason code for the error." }, "message": { "type": "string", "description": "A human-readable error message." }, "title": { "type": "string", "description": "A short title for the error." }, "field": { "type": "string", "description": "The request field the error relates to." }, "clientPayload": { "type": "object", "description": "Additional error data for the client." } }, "description": "A single error describing why a request failed." }, "ErrorDetails": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "integer", "description": "The error code (HTTP status).", "format": "int32" }, "message": { "type": "string", "description": "A human-readable error message." }, "errors": { "type": [ "null", "array" ], "items": { "description": "A single error describing why a request failed.", "$ref": "#/components/schemas/CheckoutError" }, "description": "The related errors. Each entry may relate to a specific request field or be a general error not tied to a field." } }, "description": "Details of an error returned by the API, with any related errors. Some entries relate to a specific request field; others are general errors not tied to a field." }, "FeeRequestItem": { "required": [ "description", "id", "unitPrice", "vat" ], "type": "object", "properties": { "description": { "type": "string", "description": "The description of the fee, shown on the invoice or receipt. Longer than 50 characters is truncated." }, "id": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The id of the fee, shown on the invoice or receipt. Maximum 50 characters." }, "unitPrice": { "maximum": 999999.99, "minimum": 0, "type": "number", "description": "The unit price of the fee including VAT. Allowed values are 0 to 999999.99. Maximum 2 decimals.", "format": "double" }, "vat": { "maximum": 100, "minimum": 0, "type": "number", "description": "The VAT of the fee in percent. Allowed values are 0 to 100.", "format": "double" } }, "description": "A single fee applied to a checkout, such as a shipping or direct invoice notification fee." }, "FeeResponseItem": { "required": [ "id", "description", "unitPrice", "vat" ], "type": "object", "properties": { "id": { "type": "string", "description": "The id of the fee, shown on the invoice or receipt." }, "description": { "type": "string", "description": "The description of the fee." }, "unitPrice": { "type": "number", "description": "The unit price of the fee including VAT.", "format": "double" }, "vat": { "type": "number", "description": "The VAT of the fee in percent.", "format": "double" } }, "description": "A single fee returned for a checkout, such as a shipping or direct invoice notification fee." }, "FeesRequestItem": { "type": "object", "properties": { "shipping": { "oneOf": [ { "type": "null" }, { "description": "The shipping fee applied to the checkout.", "$ref": "#/components/schemas/FeeRequestItem" } ], "description": "The shipping fee applied to the checkout." }, "directInvoiceNotification": { "oneOf": [ { "type": "null" }, { "description": "The direct invoice notification fee applied to the checkout.", "$ref": "#/components/schemas/FeeRequestItem" } ], "description": "The direct invoice notification fee applied to the checkout." } }, "description": "The set of fees applied to a checkout, such as the shipping fee and the direct invoice notification fee." }, "FeesResponseItem": { "type": "object", "properties": { "shipping": { "description": "The shipping fee for the checkout.", "$ref": "#/components/schemas/FeeResponseItem" }, "directInvoiceNotification": { "description": "The direct invoice notification fee for the checkout.", "$ref": "#/components/schemas/FeeResponseItem" } }, "description": "The set of fees returned for a checkout, such as the shipping fee and the direct invoice notification fee." }, "Field": { "required": [ "id", "name", "type" ], "type": "object", "properties": { "id": { "type": "string", "description": "The id of the field. Must be unique within the group." }, "name": { "type": "string", "description": "The label for the field." }, "type": { "type": "string", "description": "The kind of input control: Checkbox, Toggle or Text." }, "value": { "description": "The default value of the field; a string for text fields and true/false for checkboxes and toggles." }, "localizations": { "type": [ "null", "object" ], "additionalProperties": { "description": "Language-specific overrides for a custom field.", "$ref": "#/components/schemas/FieldLocale" }, "description": "Per-language overrides for the field, keyed by ISO language code." }, "metadata": { "type": [ "null", "object" ], "description": "A custom metadata object for the field." } }, "description": "A single custom field within a group." }, "FieldLocale": { "required": [ "name", "value", "metadata" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The localized label for the field." }, "value": { "description": "The localized default value of the field." }, "metadata": { "type": [ "null", "object" ], "description": "The localized custom metadata object for the field." } }, "description": "Language-specific overrides for a custom field." }, "FieldResponseItem": { "required": [ "id", "name", "type" ], "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the field, as set when the custom fields were configured." }, "name": { "type": "string", "description": "Display name of the field." }, "type": { "description": "The kind of input control used to render the field.", "$ref": "#/components/schemas/CustomFieldType" }, "value": { "description": "Value of the field: the customer's input, or the configured default if unchanged. Text fields yield strings; checkboxes and toggles yield booleans." }, "metadata": { "type": "object", "description": "Metadata attached to the field as key/value pairs." } }, "description": "A single custom field." }, "GetMerchantCheckoutInformationResponse": { "type": "object", "properties": { "customerType": { "description": "Whether the checkout is for a private or business customer.", "$ref": "#/components/schemas/CustomerType" }, "customer": { "oneOf": [ { "type": "null" }, { "description": "The private customer's details, including delivery and billing address; null for a business customer.", "$ref": "#/components/schemas/MerchantPrivateCustomerResponseItem" } ], "description": "The private customer's details, including delivery and billing address; null for a business customer." }, "businessCustomer": { "oneOf": [ { "type": "null" }, { "description": "The business customer's details, including invoice and delivery address; null for a private customer.", "$ref": "#/components/schemas/MerchantBusinessCustomerResponseItem" } ], "description": "The business customer's details, including invoice and delivery address; null for a private customer." }, "countryCode": { "type": "string", "description": "The market/country code the checkout was initialized for." }, "status": { "description": "The current lifecycle status of the checkout.", "$ref": "#/components/schemas/CheckoutStatus" }, "paymentName": { "type": [ "null", "string" ], "description": "The name of the payment option used." }, "reference": { "type": [ "null", "string" ], "description": "The merchant's reference supplied when the checkout was initialized." }, "cart": { "oneOf": [ { "type": "null" }, { "description": "The items for a purchase that has not yet been completed; null once the purchase is complete.", "$ref": "#/components/schemas/CartResponseItem" } ], "description": "The items for a purchase that has not yet been completed; null once the purchase is complete." }, "fees": { "oneOf": [ { "type": "null" }, { "description": "The fees, such as shipping, while the purchase is not yet completed; null once complete.", "$ref": "#/components/schemas/FeesResponseItem" } ], "description": "The fees, such as shipping, while the purchase is not yet completed; null once complete." }, "purchase": { "oneOf": [ { "type": "null" }, { "description": "Details of a completed purchase.", "$ref": "#/components/schemas/MerchantPurchaseInformationResponseItem" } ], "description": "Details of a completed purchase." }, "order": { "oneOf": [ { "type": "null" }, { "description": "The total amount and all items of a completed order.", "$ref": "#/components/schemas/OrderInformationResponseItem" } ], "description": "The total amount and all items of a completed order." }, "shipping": { "description": "The shipment(s) the customer selected, with the chosen shipping option, its destination and\nthe shipping fee. Present once a delivery has been selected, and still returned after the\npurchase is completed.", "$ref": "#/components/schemas/ShippingResponseItem" }, "customFields": { "type": "array", "items": { "description": "A named group of custom checkout fields.", "$ref": "#/components/schemas/GroupResponseItem" }, "description": "The custom fields and the customer's submitted values." }, "hasSessionExpired": { "type": "boolean", "description": "Whether the checkout session has expired and a new session must be initialized." }, "metadata": { "type": "object", "description": "The custom merchant metadata supplied for the checkout." }, "appliedVouchers": { "type": "array", "items": { "description": "A voucher applied to the checkout, including its id, code, description and discount amount.", "$ref": "#/components/schemas/MerchantVoucherResponseItem" }, "description": "The bonus vouchers applied and redeemed as part of the purchase." } }, "description": "A complete snapshot of a checkout returned to the merchant." }, "GroupLocale": { "required": [ "name", "metadata" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The localized header rendered above the group section." }, "metadata": { "type": [ "null", "object" ], "description": "The localized custom metadata object for the group." } }, "description": "Language-specific overrides for a custom field group." }, "GroupResponseItem": { "required": [ "id", "fields" ], "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the group, as set when the custom fields were configured." }, "name": { "type": "string", "description": "Display name of the group." }, "fields": { "type": "array", "items": { "description": "A single custom field.", "$ref": "#/components/schemas/FieldResponseItem" }, "description": "The custom fields in the group." }, "metadata": { "type": "object", "description": "Metadata attached to the group as key/value pairs." } }, "description": "A named group of custom checkout fields." }, "InitializeCheckoutRequest": { "required": [ "countryCode", "notificationUri" ], "type": "object", "properties": { "countryCode": { "type": "string", "description": "The market/country code for the checkout. Supported values are SE, NO, FI, DK, DE, NL and EU." }, "reference": { "maxLength": 50, "minLength": 0, "type": [ "null", "string" ], "description": "The merchant's reference for the order, such as an order id, shown to the customer on the invoice or receipt. Maximum 50 characters." }, "settlementReference": { "maxLength": 50, "minLength": 0, "type": [ "null", "string" ], "description": "Groups settlement reports by this value, for example when several shops share one store id. Requires settlement settings to be set up by Merchant Services. Maximum 50 characters." }, "actionReference": { "maxLength": 255, "minLength": 0, "type": [ "null", "string" ], "description": "A reference to this specific checkout session that appears on the settlement report when the order is auto-captured. Maximum 255 characters." }, "storeId": { "maximum": 2147483647, "minimum": 1, "type": [ "null", "integer" ], "description": "The Walley store identifier received from Walley Merchant Services. Only required when integrating multiple stores.", "format": "int32" }, "externalStoreId": { "maxLength": 50, "minLength": 0, "type": [ "null", "string" ], "description": "The merchant's own identifier for the store, forwarded to Voyado when used as the CRM. Maximum 50 characters." }, "salesSegment": { "type": [ "null", "string" ], "description": "Selects the store by segment instead of by store id, when the merchant has at most one B2C and/or B2B store in the country. Valid values are B2C and B2B." }, "cart": { "oneOf": [ { "type": "null" }, { "description": "The initial cart with the items to purchase. At least one item is required.", "$ref": "#/components/schemas/CartRequestItem" } ], "description": "The initial cart with the items to purchase. At least one item is required." }, "upsell": { "oneOf": [ { "type": "null" }, { "description": "Upsell items offered to the customer after the order is placed.", "$ref": "#/components/schemas/UpsellRequestItem" } ], "description": "Upsell items offered to the customer after the order is placed." }, "shipping": { "oneOf": [ { "type": "null" }, { "description": "Shipping details for the order, used together with a delivery module.", "$ref": "#/components/schemas/ShippingRequestItem" } ], "description": "Shipping details for the order, used together with a delivery module." }, "notificationUri": { "type": "string", "description": "The endpoint called whenever a notable event occurs in the checkout, typically used to create the order once a purchase is completed. Must be https.", "format": "uri" }, "redirectPageUri": { "type": [ "null", "string" ], "description": "The page the browser is redirected to once the purchase completes, used to show a confirmation page. Must be https.", "format": "uri" }, "appRedirectUri": { "type": [ "null", "string" ], "description": "Return URL for the Swedish BankID app-switch when the customer authenticates on the same device. The BankID app returns the customer here after authentication.", "format": "uri" }, "checkoutAbortedRedirectPageUri": { "type": [ "null", "string" ], "description": "When rendering a pay link, the page the browser is redirected to if the customer clicks the go-back button, which also deletes the session. Must be https.", "format": "uri" }, "validationUri": { "type": [ "null", "string" ], "description": "A URI called with a backend GET request to validate the items during purchase. Must be https. Superseded by the callback functionality.", "format": "uri" }, "callback": { "oneOf": [ { "type": "null" }, { "description": "Configuration for synchronous backend POST callbacks, such as order validation.", "$ref": "#/components/schemas/MerchantCallbackRequestItem" } ], "description": "Configuration for synchronous backend POST callbacks, such as order validation." }, "merchantTermsUri": { "type": [ "null", "string" ], "description": "The page linked from the checkout where the customer can view the merchant's purchase terms. Must be https.", "format": "uri" }, "fees": { "oneOf": [ { "type": "null" }, { "description": "The fees applied to the checkout, such as the shipping fee.", "$ref": "#/components/schemas/FeesRequestItem" } ], "description": "The fees applied to the checkout, such as the shipping fee." }, "privateCustomerPrefill": { "oneOf": [ { "type": "null" }, { "description": "Prefilled private customer information shown as a non-binding suggestion the customer can change.", "$ref": "#/components/schemas/PrivateCustomerRequestItem" } ], "description": "Prefilled private customer information shown as a non-binding suggestion the customer can change." }, "businessCustomerPrefill": { "oneOf": [ { "type": "null" }, { "description": "Prefilled business customer information shown as a non-binding suggestion the customer can change.", "$ref": "#/components/schemas/BusinessCustomerRequestItem" } ], "description": "Prefilled business customer information shown as a non-binding suggestion the customer can change." }, "businessCustomerPreset": { "oneOf": [ { "type": "null" }, { "description": "Preset business customer information the customer cannot change.", "$ref": "#/components/schemas/BusinessCustomerRequestItem" } ], "description": "Preset business customer information the customer cannot change." }, "profileName": { "type": [ "null", "string" ], "description": "The name of a settings profile configured by Merchant Services." }, "metadata": { "type": [ "null", "object" ], "description": "Custom merchant metadata in key/value form, not processed by Walley and returned when retrieving the checkout." }, "customFields": { "minItems": 1, "type": [ "null", "array" ], "items": { "description": "A named group of custom checkout fields, with optional per-language localizations.", "$ref": "#/components/schemas/CustomFieldsGroupRequestItem" }, "description": "Custom input fields rendered inside the checkout, such as consent checkboxes or comment fields." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to initialize a new checkout." }, "InitializeCheckoutResponse": { "required": [ "privateId", "publicToken", "expiresAt", "paymentUri", "paymentQrCodeUri" ], "type": "object", "properties": { "privateId": { "type": "string", "description": "The private checkout id used for backend communication, retrieving information and modifying the session.", "format": "uuid" }, "publicToken": { "type": "string", "description": "The public token used to render the checkout iframe." }, "expiresAt": { "type": "string", "description": "The timestamp when the checkout session expires; after it the purchase cannot be completed.", "format": "date-time" }, "paymentUri": { "type": "string", "description": "A shortcut link to the checkout session, used when distributing a pay link.", "format": "uri" }, "paymentQrCodeUri": { "type": "string", "description": "A QR-code image URL representing the payment URI; publicly accessible with no authentication required.", "format": "uri" } }, "description": "The result of initializing a checkout, including the URIs used to load the payment page." }, "InitializeWidgetRequest": { "type": "object", "properties": { "storeId": { "maximum": 100000, "minimum": 1, "type": "integer", "description": "The id of the store to initialize the widget for.", "format": "int32" }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to initialize a widget session for a store and obtain a widget token." }, "InitializeWidgetResponse": { "required": [ "widgetToken", "expiresAt" ], "type": "object", "properties": { "widgetToken": { "type": "string", "description": "The widget token. The Walley widget loader script sends it verbatim in the Authorization header when calling the widget endpoints." }, "expiresAt": { "type": "string", "description": "When the widget token expires. After this time a new token must be requested.", "format": "date-time" } }, "description": "Response from initializing a widget session, carrying the token to be passed to the widget loader script." }, "InvoiceStatus": { "enum": [ "OnHold", "Preliminary", "Activated", "Rejected", "Signing", "Completed" ], "type": "string", "description": "Status of the purchase's invoice.\n\n- `OnHold`: Walley has not approved the invoice yet.\n- `Preliminary`: approved by Walley and waiting to be activated.\n- `Activated`: the goods are delivered and Walley has bought the invoice.\n- `Rejected`: denied by Walley, so it cannot be activated.\n- `Signing`: waiting for the customer to sign electronically, for example with Mobile BankID.\n- `Completed`: not handled by Walley." }, "LoyaltyMembershipResponseItem": { "type": "object", "properties": { "provider": { "type": [ "null", "string" ], "description": "The loyalty provider." }, "success": { "type": "boolean", "description": "Whether the loyalty membership lookup succeeded." }, "isMember": { "type": [ "null", "string" ], "description": "The customer's membership status: \"Yes\" (a member), \"No\" (not a member) or \"New\" (applying for membership)." }, "id": { "type": [ "null", "string" ], "description": "The customer's loyalty membership id." }, "memberNumber": { "type": [ "null", "string" ], "description": "The customer's loyalty member number." } }, "description": "A customer's loyalty membership details, including the provider, whether lookup succeeded and their membership identifiers." }, "MerchantBusinessCustomerResponseItem": { "type": "object", "properties": { "companyName": { "type": [ "null", "string" ], "description": "The name of the company." }, "organizationNumber": { "type": [ "null", "string" ], "description": "The organization number of the company." }, "invoiceReference": { "type": [ "null", "string" ], "description": "An optional invoice reference." }, "email": { "type": [ "null", "string" ], "description": "The buyer's email address." }, "invoiceEmail": { "type": [ "null", "string" ], "description": "The email address the invoice is sent to." }, "firstName": { "type": [ "null", "string" ], "description": "The buyer's first name." }, "lastName": { "type": [ "null", "string" ], "description": "The buyer's last name." }, "mobilePhoneNumber": { "type": [ "null", "string" ], "description": "The buyer's mobile phone number." }, "invoiceTag": { "type": [ "null", "string" ], "description": "Optional labeling shown on the invoice (e.g. cost center, invoice label)." }, "invoiceAddress": { "oneOf": [ { "type": "null" }, { "description": "The company's invoice address.", "$ref": "#/components/schemas/AddressResponseItem" } ], "description": "The company's invoice address." }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "description": "The address the order is delivered to.", "$ref": "#/components/schemas/AddressResponseItem" } ], "description": "The address the order is delivered to." }, "validatedVatNumber": { "type": [ "null", "string" ], "description": "The company's VAT number that has been validated." } }, "description": "Business customer details returned for a checkout." }, "MerchantCallbackRequestItem": { "required": [ "callbackUri", "callbackTypes" ], "type": "object", "properties": { "callbackUri": { "type": "string", "description": "The endpoint called when any of the callback types occurs; must accept POST and be https.", "format": "uri" }, "callbackTypes": { "type": "array", "items": { "type": "string" }, "description": "The event types that trigger the callback. Currently ValidateOrder and PaymentFailed are supported." } }, "description": "Configuration for a merchant callback, specifying the URI to call and which event types should trigger it." }, "MerchantPrivateCustomerResponseItem": { "type": "object", "properties": { "email": { "type": [ "null", "string" ], "description": "The customer's email address." }, "mobilePhoneNumber": { "type": [ "null", "string" ], "description": "The customer's mobile phone number." }, "nationalIdentificationNumber": { "type": [ "null", "string" ], "description": "The customer's national identification number, when strongly identified." }, "deliveryContactInformation": { "oneOf": [ { "type": "null" }, { "description": "Contact details for the delivery, used when they differ from the billing contact details.", "$ref": "#/components/schemas/DeliveryContactInformationResponseItem" } ], "description": "Contact details for the delivery, used when they differ from the billing contact details." }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "description": "The address the order is delivered to.", "$ref": "#/components/schemas/AddressResponseItem" } ], "description": "The address the order is delivered to." }, "billingAddress": { "oneOf": [ { "type": "null" }, { "description": "The customer's billing address; included when strongly identified with a national identification number.", "$ref": "#/components/schemas/AddressResponseItem" } ], "description": "The customer's billing address; included when strongly identified with a national identification number." }, "loyaltyMembership": { "description": "The customer's loyalty membership details.", "$ref": "#/components/schemas/LoyaltyMembershipResponseItem" } }, "description": "Private customer details returned for a checkout." }, "MerchantPurchaseInformationResponseItem": { "type": "object", "properties": { "amountToPay": { "type": "number", "description": "The total amount the customer pays, which may exceed the order total due to payment-method fees.", "format": "double" }, "paymentName": { "type": "string", "description": "The name of the payment option the customer used." }, "purchaseIdentifier": { "type": "string", "description": "The identifier of the purchase, used to manage the invoice via the Walley Payments API." }, "result": { "description": "The status of the purchase at the time it was made.", "$ref": "#/components/schemas/InvoiceStatus" }, "externalPaymentReference": { "type": "string", "description": "The third-party payment reference for Swish or Vipps settlements made with the merchant's own agreement." }, "directSettlementPaymentName": { "type": "string", "description": "The payment name used for direct settlement." }, "card": { "description": "The card details for a purchase made as a tokenized payment.", "$ref": "#/components/schemas/CardInfo" }, "decisionCategory": { "type": "string", "description": "The credit decision outcome for the purchase; only applicable to Norwegian checkouts and only when a custom thank-you page is used." } }, "description": "Information about a completed purchase." }, "MerchantResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The correlation id for this response, echoed from the request's CorrelationId/X-Correlation-ID header when provided; otherwise generated by the API.", "format": "uuid" }, "context": { "type": "string", "description": "The caller-supplied context value echoed from the request when a non-empty value was supplied; otherwise omitted." }, "data": { "description": "The response payload." }, "error": { "oneOf": [ { "type": "null" }, { "description": "The error details when the request failed.", "$ref": "#/components/schemas/ErrorDetails" } ], "description": "The error details when the request failed." } }, "description": "Standard response envelope returned by the Checkout merchant API." }, "GetMerchantCheckoutInformationResponseEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "description": "The response payload.", "$ref": "#/components/schemas/GetMerchantCheckoutInformationResponse" } ], "description": "The response payload." }, "id": { "type": "string", "description": "The correlation id for this response, echoed from the request's CorrelationId/X-Correlation-ID header when provided; otherwise generated by the API.", "format": "uuid" }, "context": { "type": "string", "description": "The caller-supplied context value echoed from the request when a non-empty value was supplied; otherwise omitted." } }, "description": "Response envelope; the `data` property holds the response data." }, "InitializeCheckoutResponseEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "description": "The response payload.", "$ref": "#/components/schemas/InitializeCheckoutResponse" } ], "description": "The response payload." }, "id": { "type": "string", "description": "The correlation id for this response, echoed from the request's CorrelationId/X-Correlation-ID header when provided; otherwise generated by the API.", "format": "uuid" }, "context": { "type": "string", "description": "The caller-supplied context value echoed from the request when a non-empty value was supplied; otherwise omitted." } }, "description": "Response envelope; the `data` property holds the response data." }, "InitializeWidgetResponseEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "null" }, { "description": "The response payload.", "$ref": "#/components/schemas/InitializeWidgetResponse" } ], "description": "The response payload." }, "id": { "type": "string", "description": "The correlation id for this response, echoed from the request's CorrelationId/X-Correlation-ID header when provided; otherwise generated by the API.", "format": "uuid" }, "context": { "type": "string", "description": "The caller-supplied context value echoed from the request when a non-empty value was supplied; otherwise omitted." } }, "description": "Response envelope; the `data` property holds the response data." }, "MerchantResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The correlation id for this response, echoed from the request's CorrelationId/X-Correlation-ID header when provided; otherwise generated by the API.", "format": "uuid" }, "context": { "type": "string", "description": "The caller-supplied context value echoed from the request when a non-empty value was supplied; otherwise omitted." }, "data": { "description": "The response payload." } }, "description": "Standard response envelope returned by the Checkout merchant API." }, "MerchantShipmentResponseItem": { "required": [ "id", "shippingChoice" ], "type": "object", "properties": { "id": { "type": [ "null", "string" ], "description": "The id of the shipment, as supplied by the shipping provider. A single-shipment delivery\ntypically uses a fixed id such as \"delivery\"." }, "feeItemId": { "type": [ "null", "string" ], "description": "The id of the order item that carries this shipment's shipping fee, matching an entry in\n`order.items[].id`. Only set once the purchase is completed." }, "bookedShipmentId": { "type": [ "null", "string" ], "description": "The shipping provider's identifier for the prepared/booked shipment, used when booking or\ntracking it in the provider's system (the prepare id for nShift, for instance). Never returned\nfor Ingrid deliveries, which are identified by `externalShipmentId` and\n`externalSessionId` instead." }, "externalShipmentId": { "type": [ "null", "string" ], "description": "The shipment identifier in the shipping provider's own system: the transport order id for\nIngrid, or the id returned by a custom delivery adapter when it creates the shipment. Null for\nproviders that supply none." }, "metadata": { "type": [ "null", "object" ], "description": "Free-form key/value data the shipping provider attached to the shipment. Null when the provider\nsupplied none." }, "shippingChoice": { "description": "The shipping option the customer selected for this shipment.", "$ref": "#/components/schemas/MerchantShippingChoiceResponseItem" } }, "description": "One shipment of the order, with the shipping option the customer chose for it." }, "MerchantShippingChoiceResponseItem": { "required": [ "id", "name", "fee", "vat" ], "type": "object", "properties": { "id": { "type": "string", "description": "The id of the selected shipping option, as supplied by the shipping provider." }, "name": { "type": "string", "description": "The name of the selected shipping option as it was shown to the customer, for example\n\"Postnord Ombud\"." }, "carrier": { "type": "string", "description": "The carrier delivering the shipment. Supplied by Ingrid only; omitted for every other provider." }, "product": { "type": "string", "description": "The carrier's product/service code for the option. Supplied by Ingrid only; omitted for every\nother provider." }, "fee": { "type": "number", "description": "The fee for this shipping option, including VAT. Any fee added by the selected destination or\noptions is charged on top; the total the customer pays for shipping is\n`shipping.shippingFee`.", "format": "double" }, "vat": { "type": "number", "description": "The VAT rate applied to the shipping fee, in percent (25 means 25%), decided by the market the\ncheckout was initialized for. Not a VAT amount.", "format": "double" }, "metadata": { "type": [ "null", "object" ], "description": "Free-form key/value data the shipping provider attached to the option. Null when the provider\nsupplied none." }, "destination": { "oneOf": [ { "type": "null" }, { "description": "Where the shipment is delivered, for options that let the customer pick a location such as a\nservice point. Null for options that deliver to the customer's delivery address.", "$ref": "#/components/schemas/MerchantShippingDestinationResponseItem" } ], "description": "Where the shipment is delivered, for options that let the customer pick a location such as a\nservice point. Null for options that deliver to the customer's delivery address." }, "options": { "type": [ "null", "array" ], "items": { "description": "An add-on option the customer selected for a shipping option, such as carry-in or a delivery notice.", "$ref": "#/components/schemas/ShippingOptionResponseItem" }, "description": "The add-on options the customer selected for this shipping option, such as carry-in or a\ndelivery notice. Null when the option has none." } }, "description": "The shipping option the customer selected for a shipment, such as home delivery or delivery to a\nservice point." }, "MerchantShippingDeliveryDateResponseItem": { "required": [ "fee", "date", "timeFrom", "timeTo" ], "type": "object", "properties": { "fee": { "type": "number", "description": "The additional fee for this delivery slot, including VAT. Zero when the slot costs no extra.", "format": "double" }, "metadata": { "type": [ "null", "object" ], "description": "Free-form key/value data the shipping provider attached to the delivery slot. Null when the\nprovider supplied none." }, "date": { "type": "string", "description": "The delivery date, as supplied by the shipping provider (normally ISO 8601, \"2026-08-28\")." }, "timeFrom": { "type": "string", "description": "The start of the delivery window on that date, as supplied by the shipping provider (\"08:00\")." }, "timeTo": { "type": "string", "description": "The end of the delivery window on that date, as supplied by the shipping provider (\"12:00\")." } }, "description": "The delivery slot the customer selected for a shipment." }, "MerchantShippingDestinationResponseItem": { "required": [ "id", "fee" ], "type": "object", "properties": { "id": { "type": "string", "description": "The id of the destination, as supplied by the shipping provider. For a service point this is\nthe provider's identifier for that location." }, "name": { "type": [ "null", "string" ], "description": "The name of the destination as it was shown to the customer, for example the name of the store\nhosting the service point." }, "description": { "type": [ "null", "string" ], "description": "A description of the destination, typically its street address." }, "fee": { "type": "number", "description": "The additional fee for delivering to this destination, including VAT. Zero when the destination\ncosts no extra.", "format": "double" }, "metadata": { "type": [ "null", "object" ], "description": "Free-form key/value data the shipping provider attached to the destination, such as the\nopening hours or coordinates of a service point. Null when the provider supplied none." }, "deliveryDate": { "oneOf": [ { "type": "null" }, { "description": "The delivery date and time window the customer selected, for options that offer a choice of\ndelivery slots. Null when the option has no selectable delivery date.", "$ref": "#/components/schemas/MerchantShippingDeliveryDateResponseItem" } ], "description": "The delivery date and time window the customer selected, for options that offer a choice of\ndelivery slots. Null when the option has no selectable delivery date." } }, "description": "The location a shipment is delivered to, such as the service point the customer picked." }, "MerchantVoucherResponseItem": { "required": [ "voucherId", "code", "description", "discountAmount" ], "type": "object", "properties": { "voucherId": { "type": "string", "description": "The id of the voucher." }, "code": { "type": "string", "description": "The voucher code." }, "description": { "type": "string", "description": "The description of the voucher." }, "discountAmount": { "type": "number", "description": "The discount amount applied by the voucher.", "format": "double" } }, "description": "A voucher applied to the checkout, including its id, code, description and discount amount." }, "OrderInformationResponseItem": { "type": "object", "properties": { "orderId": { "type": [ "null", "string" ], "description": "The unique id of the created order, used in calls to manage the order." }, "totalAmount": { "type": "number", "description": "The total amount to be settled, i.e. the sum paid to the merchant for the purchase.", "format": "double" }, "customerToken": { "type": [ "null", "string" ], "description": "The customer token used for future tokenized payments, when configured.", "format": "uuid" }, "items": { "type": [ "null", "array" ], "items": { "description": "A single item in a completed order, describing a product or gift card.", "$ref": "#/components/schemas/OrderItemResponseItem" }, "description": "The items of the completed order." } }, "description": "Information about the order created from a completed checkout." }, "OrderItemResponseItem": { "required": [ "id", "description", "unitPrice", "quantity", "vat" ], "type": "object", "properties": { "id": { "type": "string", "description": "The item id, shown on the invoice or receipt." }, "description": { "type": "string", "description": "The item description." }, "type": { "description": "The type of the item, such as a gift card.", "$ref": "#/components/schemas/ArticleType" }, "unitPrice": { "type": "number", "description": "The unit price of the item including VAT.", "format": "double" }, "unitWeight": { "type": "number", "description": "The weight of the item.", "format": "double" }, "quantity": { "type": "integer", "description": "The quantity of the item.", "format": "int32" }, "vat": { "type": "number", "description": "The VAT of the item in percent.", "format": "double" }, "sku": { "type": "string", "description": "The stock keeping unit identifying the item." }, "usedAmount": { "type": "number", "description": "The amount of a gift card that has been used.", "format": "double" } }, "description": "A single item in a completed order, describing a product or gift card." }, "PrivateCustomerRequestItem": { "type": "object", "properties": { "email": { "type": [ "null", "string" ], "description": "The customer's email address." }, "mobilePhoneNumber": { "type": [ "null", "string" ], "description": "The customer's mobile phone number; foreign numbers must include a valid prefix such as +46 or 0046." }, "nationalIdentificationNumber": { "type": [ "null", "string" ], "description": "The customer's national identification number." }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "description": "The customer's delivery address.", "$ref": "#/components/schemas/AddressRequestItem" } ], "description": "The customer's delivery address." } }, "description": "Private customer details supplied for a checkout." }, "SendPayLinkRequest": { "required": [ "destination" ], "type": "object", "properties": { "destination": { "description": "The recipient the payment link is sent to.", "$ref": "#/components/schemas/Destination" }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to send a payment link to the customer, specifying the recipient destination." }, "SetCartRequest": { "type": "object", "properties": { "shippingProperties": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Key/value properties used to customize which delivery methods are available, when a delivery module is used." }, "items": { "type": [ "null", "array" ], "items": { "description": "A single item in the checkout cart, describing a product or gift card.", "$ref": "#/components/schemas/ArticleRequestItem" }, "description": "The cart items to set on the cart." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set the cart for a checkout, containing the cart items and optional shipping properties." }, "SetCheckoutRequest": { "type": "object", "properties": { "cart": { "type": [ "null", "array" ], "items": { "description": "A single item in the checkout cart, describing a product or gift card.", "$ref": "#/components/schemas/ArticleRequestItem" }, "description": "The cart items to set on the checkout, replacing the existing cart." }, "shipping": { "oneOf": [ { "type": "null" }, { "description": "Shipping details for the order.", "$ref": "#/components/schemas/ShippingRequestItem" } ], "description": "Shipping details for the order." }, "fees": { "oneOf": [ { "type": "null" }, { "description": "The fees applied to the checkout, such as the shipping and direct invoice notification fees.", "$ref": "#/components/schemas/FeesRequestItem" } ], "description": "The fees applied to the checkout, such as the shipping and direct invoice notification fees." }, "shippingProperties": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Key/value properties used to customize which delivery methods are available, when a delivery module is used." }, "reference": { "maxLength": 50, "minLength": 0, "type": [ "null", "string" ], "description": "The merchant's reference for the order, shown to the customer on the invoice or receipt. Maximum 50 characters." }, "settlementReference": { "maxLength": 50, "minLength": 0, "type": [ "null", "string" ], "description": "Groups settlement reports by this value. Maximum 50 characters." }, "metadata": { "type": [ "null", "object" ], "description": "Custom merchant metadata in key/value form, returned when retrieving the checkout.\nKey casing is preserved, and the metadata is limited to 200000 characters when serialized as JSON." }, "upsell": { "oneOf": [ { "type": "null" }, { "description": "Upsell items offered to the customer after the order is placed.", "$ref": "#/components/schemas/UpsellRequestItem" } ], "description": "Upsell items offered to the customer after the order is placed." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set up or update a checkout." }, "SetFeesRequest": { "type": "object", "properties": { "shipping": { "oneOf": [ { "type": "null" }, { "description": "The shipping fee applied to the checkout.", "$ref": "#/components/schemas/FeeRequestItem" } ], "description": "The shipping fee applied to the checkout." }, "directInvoiceNotification": { "oneOf": [ { "type": "null" }, { "description": "The direct invoice notification fee applied to the checkout.", "$ref": "#/components/schemas/FeeRequestItem" } ], "description": "The direct invoice notification fee applied to the checkout." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set the fees applied to a checkout, such as the shipping fee and the direct invoice notification fee." }, "SetOrderReferenceRequest": { "required": [ "reference" ], "type": "object", "properties": { "reference": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The merchant's own reference for the order. Maximum 50 characters." }, "context": { "type": [ "null", "string" ], "description": "An optional caller-supplied value that is echoed back in the response envelope when a non-empty value is supplied, useful for correlating a response with the request that produced it." } }, "description": "Request to set the merchant's own reference for an order." }, "ShipmentContentRequestItem": { "type": "object", "properties": { "sku": { "type": "string", "description": "The stock keeping unit of the item included in the shipment." }, "quantity": { "type": "integer", "description": "The quantity of the item shipped.", "format": "int32" } }, "description": "An item included in a shipment, identified by its SKU and the quantity shipped." }, "ShipmentRequestItem": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": [ "null", "string" ], "description": "The id of the shipment." }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Tags describing the shipment." }, "contents": { "type": [ "null", "array" ], "items": { "description": "An item included in a shipment, identified by its SKU and the quantity shipped.", "$ref": "#/components/schemas/ShipmentContentRequestItem" }, "description": "The items included in the shipment." } }, "description": "A single shipment within the order, describing the items it contains." }, "ShippingDimensionsRequestItem": { "type": "object", "properties": { "width": { "type": "integer", "description": "The width of the item.", "format": "int32" }, "height": { "type": "integer", "description": "The height of the item.", "format": "int32" }, "length": { "type": "integer", "description": "The length of the item.", "format": "int32" } }, "description": "The physical dimensions of an item, given as width, height and length." }, "ShippingIntervalAlternativeRequestItem": { "required": [ "shippingInterval" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "An optional display name for the alternative delivery window." }, "shippingInterval": { "description": "The delivery interval for this alternative.", "$ref": "#/components/schemas/DateTimeIntervalRequestItem" } }, "description": "An alternative delivery window offered to the customer, with an optional display name and its own delivery interval." }, "ShippingIntervalRequestItem": { "type": "object", "properties": { "alternatives": { "type": [ "null", "array" ], "items": { "description": "An alternative delivery window offered to the customer, with an optional display name and its own delivery interval.", "$ref": "#/components/schemas/ShippingIntervalAlternativeRequestItem" }, "description": "Alternative delivery windows offered to the customer." }, "startDate": { "type": [ "null", "string" ], "description": "The start of the interval.", "format": "date-time" }, "endDate": { "type": [ "null", "string" ], "description": "The end of the interval.", "format": "date-time" } }, "description": "The expected delivery window, given as a start and end date together with any alternative windows offered to the customer." }, "ShippingOptionResponseItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the option, as supplied by the shipping provider." }, "description": { "type": [ "null", "string" ], "description": "The description of the option as it was shown to the customer." }, "type": { "type": [ "null", "string" ], "description": "The provider's type for the option, which decides how `value` is interpreted (a boolean\nfor a toggle, a string for free text, and so on)." }, "fee": { "type": "number", "description": "The additional fee for the option, including VAT. Zero when the option costs no extra.", "format": "double" }, "value": { "description": "The value the customer supplied for the option, of the type given by `type`." }, "metadata": { "type": "object", "description": "Free-form key/value data the shipping provider attached to the option. Omitted when the\nprovider supplied none." } }, "description": "An add-on option the customer selected for a shipping option, such as carry-in or a delivery notice." }, "ShippingRequestItem": { "type": "object", "properties": { "tags": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Tags used to filter or describe the available shipping options for the order." }, "shipments": { "type": [ "null", "array" ], "items": { "description": "A single shipment within the order, describing the items it contains.", "$ref": "#/components/schemas/ShipmentRequestItem" }, "description": "The individual shipments that make up the order." }, "shippingInterval": { "oneOf": [ { "type": "null" }, { "description": "The expected delivery window for the order.", "$ref": "#/components/schemas/ShippingIntervalRequestItem" } ], "description": "The expected delivery window for the order." } }, "description": "Shipping details for the order, such as shipment tags, the individual shipments and the delivery interval." }, "ShippingResponseItem": { "type": "object", "properties": { "provider": { "type": [ "null", "string" ], "description": "The name of the shipping provider that supplied the delivery options, as configured for the\nstore (for example \"Ingrid\", \"nShift\" or the name of a custom provider integration)." }, "shippingFee": { "type": "number", "description": "The total shipping fee for all shipments, including VAT and any fees added by the selected\ndestination or options. The same amount is charged as a separate order item.", "format": "double" }, "externalSessionId": { "type": "string", "description": "The shipping provider's own session identifier, for looking the delivery up in the provider's\nsystem. Supplied by Ingrid only, and only returned once the purchase is completed; omitted for\nevery other provider." }, "shipments": { "type": "array", "items": { "description": "One shipment of the order, with the shipping option the customer chose for it.", "$ref": "#/components/schemas/MerchantShipmentResponseItem" }, "description": "The shipments the order is delivered in. A single delivery yields one shipment; providers that\nsupport split deliveries can yield several." } }, "description": "The shipment(s) the customer selected, with the chosen shipping option, its destination and\nthe shipping fee. Present once a delivery has been selected, and still returned after the\npurchase is completed." }, "UpsellItemRequestItem": { "required": [ "description", "id", "quantity", "unitPrice", "vat", "imageUrl" ], "type": "object", "properties": { "description": { "type": "string", "description": "The description of the upsell item, shown on the invoice or receipt. Text longer than 50 characters is truncated." }, "id": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The upsell item id. Maximum 50 characters." }, "quantity": { "maximum": 99999999, "minimum": 1, "type": [ "null", "integer" ], "description": "The quantity offered. Allowed values are 1 to 99999999.", "format": "int32" }, "unitPrice": { "maximum": 999999.99, "minimum": 0.01, "type": [ "null", "number" ], "description": "The unit price of the upsell item including VAT. Must be above zero: the upsell is charged as a separate\npayment of `unitPrice × quantity`, so unlike a cart article a zero or negative price is not a discount\nbut a payment that can never start. Allowed values are 0.01 to 999999.99. Maximum 2 decimals.", "format": "double" }, "vat": { "maximum": 100, "minimum": 0, "type": [ "null", "number" ], "description": "The VAT in percent. Allowed values are 0 to 100.", "format": "double" }, "sku": { "maxLength": 1024, "minLength": 0, "type": [ "null", "string" ], "description": "A stock keeping unit identifying the product. Maximum 1024 characters." }, "imageUrl": { "type": "string", "description": "The URL of an image shown for the upsell item. Must be an absolute https URL. Maximum 2048 characters.", "format": "uri" } }, "description": "A single upsell item offered to the customer." }, "UpsellRequestItem": { "required": [ "items" ], "type": "object", "properties": { "items": { "maxItems": 10, "type": "array", "items": { "description": "A single upsell item offered to the customer.", "$ref": "#/components/schemas/UpsellItemRequestItem" }, "description": "The upsell items offered to the customer. Maximum 10 items." }, "timeLimitInSeconds": { "maximum": 300, "minimum": 60, "type": [ "null", "integer" ], "description": "How long, in seconds, the upsell offer stays open after the purchase completes.\nBetween 60 and 300 seconds. Omitted, the offer gets the maximum of 300 seconds - every\noffer closes, so the customer always sees a deadline and you always know when the order\nstops changing.", "format": "int32" } }, "description": "The set of upsell items offered to the customer after the order has been placed." }, "CaptureMode": { "type": "string", "description": "How the authorized amount is captured.", "enum": [ "Auto", "Manual" ] }, "TokenStatus": { "type": "string", "description": "Lifecycle status of a customer token.", "enum": [ "Active", "Pending", "Cancelled", "Denied", "Revoked", "Suspended" ] }, "OrderItem": { "type": "object", "description": "An order line in the order to authorize.", "required": [ "description", "id", "quantity", "unitPrice", "vat" ], "properties": { "id": { "type": "string", "maxLength": 50, "description": "Merchant identifier of the order line." }, "description": { "type": "string", "description": "Description of the order line. Values longer than 50 characters are accepted but truncated to 50 characters." }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 99999999, "description": "Number of units." }, "unitPrice": { "type": "number", "format": "double", "minimum": -999999.99, "maximum": 999999.99, "description": "Price per unit, including VAT, with at most two decimals." }, "vat": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "VAT rate as a percentage, with at most two decimals." } } }, "CustomerTokensOrder": { "type": "object", "description": "The order to authorize payment for: its order lines, currency and references.", "required": [ "items", "currency" ], "properties": { "items": { "type": "array", "minItems": 1, "description": "Order lines. The total of quantity x unitPrice across all items must be greater than zero.", "items": { "$ref": "#/components/schemas/OrderItem" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three-letter currency code. Must match the currency of the customer token." }, "reference": { "type": [ "string", "null" ], "maxLength": 50, "description": "Merchant order reference." }, "actionReference": { "type": [ "string", "null" ], "maxLength": 255, "description": "Reference for this specific action." }, "settlementReference": { "type": [ "string", "null" ], "maxLength": 50, "description": "Reference used on the settlement." }, "captureMode": { "$ref": "#/components/schemas/CaptureMode", "description": "When omitted, the capture mode stored on the customer token is used." } } }, "AttemptSchedule": { "type": "object", "description": "Optional schedule controlling when authorization attempts are made. Provide either relative or absolute times, not both; relative/absolute cannot be combined with preferSynchronous. When a schedule is supplied, attempts must not be more than one minute in the past, and the span from the earliest to the latest attempt cannot exceed 30 days. In production, attempts must also be at least 5 minutes apart; that spacing rule is not enforced in test environments. Omit this object to attempt the authorization once, immediately.", "properties": { "relative": { "type": [ "array", "null" ], "description": "Delays before each attempt, as duration strings (for example \"00:05:00\"). Each delay is applied cumulatively from the previous attempt, so [\"00:05:00\", \"00:05:00\"] schedules attempts 5 and 10 minutes from now.", "items": { "type": "string" } }, "absolute": { "type": [ "array", "null" ], "description": "Absolute times at which to attempt authorization.", "items": { "type": "string", "format": "date-time" } }, "preferSynchronous": { "type": "boolean", "default": false, "description": "Process the authorization synchronously and return the result in the response." } } }, "AuthorizeRequest": { "type": "object", "description": "Request body for authorizing a payment against a stored customer token.", "required": [ "customerToken", "order" ], "properties": { "customerToken": { "type": "string", "format": "uuid", "description": "Identifier of the customer token to authorize against." }, "storeId": { "type": [ "integer", "null" ], "format": "int32", "description": "Store the authorization belongs to. Defaults to the store of the customer token." }, "order": { "$ref": "#/components/schemas/CustomerTokensOrder" }, "attemptSchedule": { "$ref": "#/components/schemas/AttemptSchedule" } } }, "AuthorizeAcceptedData": { "type": "object", "description": "Payload of an asynchronous (202) authorization response.", "required": [ "authorizationId" ], "properties": { "authorizationId": { "type": "string", "format": "uuid", "description": "Identifier of the created authorization." } } }, "AuthorizeAcceptedResponse": { "type": "object", "description": "Response envelope for an authorization accepted for asynchronous processing.", "required": [ "id", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." }, "data": { "$ref": "#/components/schemas/AuthorizeAcceptedData" } } }, "CancelAuthorizationData": { "type": "object", "description": "Payload of a cancel authorization response.", "required": [ "authorizationId" ], "properties": { "authorizationId": { "type": "string", "format": "uuid", "description": "Identifier of the cancelled authorization." } } }, "CancelAuthorizationResponse": { "type": "object", "description": "Response envelope for a cancelled authorization.", "required": [ "id", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." }, "data": { "$ref": "#/components/schemas/CancelAuthorizationData" } } }, "AuthorizeSyncData": { "type": "object", "description": "Payload of a synchronous (200) authorization response.", "required": [ "authorizationId", "orderId" ], "properties": { "authorizationId": { "type": "string", "format": "uuid", "description": "Identifier of the created authorization." }, "orderId": { "type": "string", "format": "uuid", "description": "Identifier of the resulting order." } } }, "AuthorizeSyncResponse": { "type": "object", "description": "Response envelope for a synchronously processed authorization.", "required": [ "id", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." }, "data": { "$ref": "#/components/schemas/AuthorizeSyncData" } } }, "GetTokenResponse": { "type": "object", "description": "Response envelope for a customer token lookup.", "required": [ "id", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." }, "data": { "$ref": "#/components/schemas/CustomerToken" } } }, "CustomerToken": { "type": "object", "description": "A stored customer token: its lifecycle status, payment method and buyer contact details.", "required": [ "status", "paymentMethod" ], "properties": { "status": { "$ref": "#/components/schemas/TokenStatus" }, "cancellationDate": { "type": [ "string", "null" ], "format": "date-time", "description": "When the token was cancelled. Absent when the token has not been cancelled." }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "buyer": { "$ref": "#/components/schemas/CustomerTokensBuyer", "description": "Buyer contact details. Absent when the token has no buyer." } } }, "CustomerTokensBuyer": { "type": [ "object", "null" ], "description": "Buyer contact details stored on the token.", "properties": { "email": { "type": [ "string", "null" ], "description": "Buyer email address." }, "mobilePhone": { "type": [ "string", "null" ], "description": "Buyer mobile phone number." } } }, "PaymentMethod": { "type": "object", "description": "Stored payment method. The concrete shape depends on the type discriminator.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Payment method type discriminator: Card, Credit or Swish." } }, "discriminator": { "propertyName": "type", "mapping": { "Card": "#/components/schemas/CardPaymentMethod", "Credit": "#/components/schemas/CreditPaymentMethod", "Swish": "#/components/schemas/SwishPaymentMethod" } } }, "CardPaymentMethod": { "description": "Stored card payment method (type = Card).", "allOf": [ { "$ref": "#/components/schemas/PaymentMethod" }, { "type": "object", "properties": { "maskedCardNumber": { "type": [ "string", "null" ], "description": "Masked card number as supplied by the acquirer, for example 516020******2127." } } } ] }, "CreditPaymentMethod": { "description": "Stored credit/invoice payment method (type = Credit).", "allOf": [ { "$ref": "#/components/schemas/PaymentMethod" }, { "type": "object", "properties": { "invoiceType": { "type": "string", "description": "Delivery method of the invoice. Defaults to Email when the token has no electronic invoice address." }, "invoiceTag": { "type": [ "string", "null" ], "description": "Optional invoice tag." }, "invoiceReference": { "type": [ "string", "null" ], "description": "Optional invoice reference." } } } ] }, "SwishPaymentMethod": { "description": "Stored Swish payment method (type = Swish).", "allOf": [ { "$ref": "#/components/schemas/PaymentMethod" }, { "type": "object", "properties": { "maskedPayerAlias": { "type": [ "string", "null" ], "description": "Swish payer alias with all but the last four digits replaced by asterisks, for example *******7654." } } } ] }, "ModifyCustomerTokenRequest": { "type": "object", "description": "Updates the buyer contact details on the token. Both fields are optional; a request that supplies neither succeeds without changing anything. The token must have an existing buyer if either field is supplied, otherwise the request is rejected with 422.", "properties": { "email": { "type": [ "string", "null" ], "format": "email", "description": "Updated buyer email address." }, "mobilePhone": { "type": [ "string", "null" ], "description": "Updated buyer mobile phone number in E.164 format. Whitespace is stripped before the number is stored." } } }, "EmptyResponse": { "type": "object", "description": "Response envelope for operations that return no payload. The body contains only the correlation fields.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." } } }, "ErrorResponse": { "type": "object", "description": "Error response for Customer Tokens requests.", "required": [ "id", "error" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Correlation id for the request. Echoes the `CorrelationId` request header when that header is a GUID, otherwise a generated value." }, "context": { "type": [ "string", "null" ], "description": "The `CorrelationId` request header value when it was not a GUID. Absent otherwise." }, "error": { "$ref": "#/components/schemas/CustomerTokensError" } } }, "CustomerTokensError": { "type": "object", "description": "The error: an HTTP status code, a summary message and the individual problems.", "required": [ "code", "message", "errors" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "HTTP status code of the error." }, "message": { "type": "string", "description": "Short summary of the error. This is the standard reason phrase for the status code." }, "errors": { "type": "array", "description": "Individual problems that caused the error. Empty when no machine-readable reason is available, for example on 404 and 500 responses and on some 422 and 503 responses.", "items": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "ErrorDetail": { "type": "object", "description": "One individual problem behind an error response, with a machine-readable reason code.", "required": [ "reason", "message" ], "properties": { "reason": { "type": "string", "description": "Machine-readable reason code. One of: INVALID_CURRENCY, TOKEN_PENDING, TOKEN_DENIED, TOKEN_REVOKED, TOKEN_CANCELLED, TOKEN_SUSPENDED, VALIDATION_ERROR, PAYMENT_DENIED, PAYMENT_FAILED, PAYMENT_TIMEOUT, PAYMENT_METHOD_NO_FUNDS, PAYMENT_METHOD_EXPIRED, IMPORTED_CUSTOMER_TOKEN_IGNORED, SERVICE_UNAVAILABLE, DOWNSTREAM_TIMEOUT, DOWNSTREAM_ERROR, IDEMPOTENCY_KEY_PARSING, IDEMPOTENCY_REQUEST_IN_PROGRESS, IDEMPOTENCY_RESPONSE_EXPIRED, IDEMPOTENCY_MISMATCHING_REQUEST_TYPE." }, "message": { "type": "string", "description": "Human-readable explanation." }, "messageDetails": { "type": [ "string", "null" ], "description": "Additional detail from the payment provider, when available." }, "field": { "type": [ "string", "null" ], "description": "Request field the problem relates to, when applicable." } } }, "CancelOrderRequest": { "type": "object", "description": "Request body for cancelling an order. Optional, so send an empty body or just an action reference.", "properties": { "actionReference": { "type": "string", "description": "Optional reference for this cancellation, echoed in reporting (max 255 chars)." } }, "additionalProperties": false }, "CaptureOrderRequest": { "type": "object", "description": "Request body for activating (capturing) an order or part of it: the amount and, optionally, the specific articles to activate.", "properties": { "amount": { "type": "number", "format": "double", "description": "Total amount to activate. Must be ≥ 0 and, when `items` are given, equal their summed `unitPrice × quantity`." }, "description": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Free-text note for the activation (max 50 chars)." }, "actionReference": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Your own reference for this action, echoed in reporting (max 255 chars)." }, "replaceItems": { "type": "boolean", "description": "When true, replace the order’s article set with `items` (each item must carry an `id`). When false/omitted, `items` are activated against the existing rows." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CaptureOrderItem" }, "description": "Specific articles/quantities to activate. Omit to activate the whole order for `amount`." } }, "additionalProperties": false }, "CaptureOrderItem": { "type": "object", "description": "All fields are optional at the protocol level: omitted numeric fields default to 0 and omitted strings to null. `id` is required when `replaceItems` is true, and when `items` are given their summed `unitPrice × quantity` must equal `amount`.", "properties": { "id": { "type": "string", "description": "Article id. Required when `replaceItems` is true." }, "unitPrice": { "type": "number", "format": "double", "description": "Price per unit, incl. VAT." }, "description": { "type": "string", "description": "Article description shown on the invoice." }, "quantity": { "type": "integer", "format": "int32", "description": "Number of units to activate." }, "vat": { "type": "number", "format": "double", "description": "VAT rate for the article (e.g. 25 for 25%)." } }, "additionalProperties": false }, "RefundOrderRequest": { "type": "object", "description": "Request body for returning (refunding) an order or part of it: the amount and the lines to return.", "properties": { "amount": { "type": "number", "format": "double", "description": "Total amount to return. Must be ≥ 0 and, when `items` are given, equal their signed total. 0 is accepted as a no-op." }, "description": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Free-text note for the return (max 50 chars)." }, "actionReference": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Your own reference for this action, echoed in reporting (max 255 chars)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RefundOrderItem" }, "description": "Lines to return: purchase rows, plus optional `FEE`, `DISCOUNT` and `REPLACEMENT` lines distinguished by `type`." } }, "additionalProperties": false }, "RefundOrderItem": { "type": "object", "description": "A line to return. `type` distinguishes ordinary purchase rows from `FEE`, `DISCOUNT` and `REPLACEMENT` lines; fees and discounts require both `id` and `description`. Purchase rows must match the order's rows on `id`, `description` and `unitPrice`.", "required": [ "quantity" ], "properties": { "type": { "type": "string", "description": "Line kind: omit/other for a purchase row, or one of `FEE`, `DISCOUNT`, `REPLACEMENT`." }, "id": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Article id (max 50 chars). Required for `FEE` and `DISCOUNT` lines." }, "unitPrice": { "type": "number", "format": "double", "description": "Price per unit, incl. VAT. Sign is normalised server-side per line kind." }, "vat": { "type": "number", "format": "double", "description": "VAT rate for the line in percent (e.g. 25 for 25%). Only used for `FEE`, `DISCOUNT` and `REPLACEMENT` lines; ignored on purchase rows. Defaults to 0." }, "description": { "type": "string", "description": "Line description. Required for `FEE` and `DISCOUNT` lines." }, "quantity": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "description": "Number of units to return (≥ 1)." } }, "additionalProperties": false }, "ReauthorizeOrderRequest": { "type": "object", "description": "Request body for reauthorizing an order: the new total amount and, optionally, the article set that replaces the not-yet-captured rows.", "required": [ "amount" ], "properties": { "amount": { "type": "number", "format": "double", "description": "The new amount to authorize (max 2 decimals). Must be greater than zero and, when `items` are given, equal their total (`unitPrice × quantity`)." }, "description": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Free-text note for the reauthorization (max 50 chars). Used as the description when no `items` are provided; visible on invoices where applicable." }, "actionReference": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Your own reference for this action, echoed in reporting (max 255 chars)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReauthorizeOrderItem" }, "description": "The article set to authorize. Replaces the not-yet-captured articles; omit to reauthorize the amount only." } }, "additionalProperties": false }, "ReauthorizeOrderItem": { "type": "object", "description": "An article in the replacement article set to authorize.", "required": [ "quantity" ], "properties": { "id": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Article id (max 50 chars)." }, "unitPrice": { "type": "number", "format": "double", "description": "Price per unit, incl. VAT (max 2 decimals)." }, "description": { "type": "string", "description": "Article description shown on the invoice." }, "quantity": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "description": "Number of units to authorize (≥ 1)." }, "vat": { "type": "number", "format": "double", "description": "VAT rate for the article (e.g. 25 for 25%). Must not be negative." } }, "additionalProperties": false }, "Reauthorization": { "type": "object", "description": "The recorded outcome of a reauthorization that required an additional credit check.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the reauthorization.", "examples": [ "ca81364e-895f-4250-bdb2-a9dafa13c4bc" ] }, "orderId": { "type": "string", "format": "uuid", "description": "The order affected by the reauthorization.", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "status": { "type": "string", "enum": [ "Completed", "Failed" ], "description": "`Completed` for a successfully completed reauthorization. `Failed` when it was rejected, for example a denied credit check." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp of the reauthorization.", "examples": [ "2023-01-17T12:09:27.029057+00:00" ] } } }, "ReauthorizationResponse": { "type": "object", "description": "Response envelope for a reauthorization lookup.", "properties": { "data": { "$ref": "#/components/schemas/Reauthorization" }, "links": { "type": "object", "description": "HATEOAS links related to the reauthorization.", "additionalProperties": { "$ref": "#/components/schemas/ManageLink" } }, "metaData": { "type": "object", "description": "Additional response metadata." } } }, "ManageLink": { "type": "object", "description": "A HATEOAS link describing a related request.", "properties": { "method": { "type": "string", "description": "HTTP method to use for the link.", "examples": [ "GET" ] }, "href": { "type": "string", "description": "Path of the linked resource, without the `/manage` prefix. Prepend `/manage` when making the request.", "examples": [ "/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "query": { "type": "string", "description": "Query string of the linked resource, if any.", "examples": [ "" ] } } }, "ManagePaginationLinks": { "type": "object", "description": "Links for navigating the paged result set.", "properties": { "self": { "$ref": "#/components/schemas/ManageLink" }, "next": { "$ref": "#/components/schemas/ManageLink" }, "prev": { "$ref": "#/components/schemas/ManageLink" } } }, "PaginationMetaData": { "type": "object", "description": "Paging metadata for the result set.", "properties": { "totalNumberOfRecords": { "type": "integer", "format": "int64", "description": "Total number of records across all pages.", "examples": [ 100 ] }, "numberOfPages": { "type": "integer", "format": "int32", "description": "Total number of pages.", "examples": [ 10 ] }, "currentPage": { "type": "integer", "format": "int32", "description": "The page returned in this response.", "examples": [ 1 ] }, "range": { "$ref": "#/components/schemas/ManageIndexRange" } } }, "ManageIndexRange": { "type": "object", "description": "The 1-based range of records included in this page.", "properties": { "from": { "type": "integer", "format": "int64", "description": "Index of the first record on this page.", "examples": [ 1 ] }, "to": { "type": "integer", "format": "int64", "description": "Index of the last record on this page.", "examples": [ 10 ] } } }, "OrderAddress": { "type": [ "object", "null" ], "description": "A delivery or invoice address on the order.", "properties": { "addressLine1": { "type": [ "string", "null" ], "description": "First address line (street address)." }, "addressLine2": { "type": [ "string", "null" ], "description": "Second address line, when present." }, "city": { "type": [ "string", "null" ], "description": "City or town." }, "coAddress": { "type": [ "string", "null" ], "description": "Care-of (c/o) address, when present." }, "receiverName": { "type": [ "string", "null" ], "description": "Name of the receiver at this address." }, "countryCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "email": { "type": [ "string", "null" ], "description": "Contact email address for the delivery." }, "mobilePhone": { "type": [ "string", "null" ], "description": "Contact mobile phone number." }, "phoneNumber": { "type": [ "string", "null" ], "description": "Contact phone number (landline), when present." }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code." } } }, "ElectronicInvoiceAddress": { "type": [ "object", "null" ], "description": "Electronic invoicing address for B2B orders, when configured.", "properties": { "type": { "type": "string", "description": "Address kind.", "enum": [ "Peppol", "Finvoice" ] }, "value": { "type": "string", "description": "Peppol id, or for Finvoice the intermediator and receiver address joined by `;`." } } }, "OrderCustomerBuyer": { "type": [ "object", "null" ], "description": "The buyer (person acting for the customer) on B2B orders, when present. Personal data is masked.", "properties": { "firstName": { "type": [ "string", "null" ], "description": "Buyer first name." }, "lastName": { "type": [ "string", "null" ], "description": "Buyer last name." }, "registrationNumber": { "type": [ "string", "null" ], "description": "Masked registration number." }, "email": { "type": [ "string", "null" ], "description": "Buyer email address." }, "mobilePhoneNumber": { "type": [ "string", "null" ], "description": "Buyer mobile phone number." }, "homePhoneNumber": { "type": [ "string", "null" ], "description": "Buyer home phone number, when present." } } }, "OrderCustomer": { "type": "object", "description": "The customer on the order. Registration numbers for persons are masked.", "properties": { "type": { "type": [ "string", "null" ], "description": "Customer kind, e.g. `Person` or `Company`." }, "name": { "type": [ "string", "null" ], "description": "Company name for B2B customers." }, "firstName": { "type": [ "string", "null" ], "description": "Customer first name (persons)." }, "lastName": { "type": [ "string", "null" ], "description": "Customer last name (persons)." }, "registrationNumber": { "type": [ "string", "null" ], "description": "Masked registration number for persons; organization number for companies." }, "countryCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the customer's address." }, "coAddress": { "type": [ "string", "null" ], "description": "Care-of (c/o) address, when present." }, "addressLine1": { "type": [ "string", "null" ], "description": "First address line (street address)." }, "addressLine2": { "type": [ "string", "null" ], "description": "Second address line, when present." }, "city": { "type": [ "string", "null" ], "description": "City or town." }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code." }, "email": { "type": [ "string", "null" ], "description": "Customer email address." }, "mobilePhoneNumber": { "type": [ "string", "null" ], "description": "Customer mobile phone number." }, "homePhoneNumber": { "type": [ "string", "null" ], "description": "Customer home phone number, when present." }, "buyer": { "$ref": "#/components/schemas/OrderCustomerBuyer" } } }, "OrderRowItem": { "type": "object", "description": "An order line in the compact order representation. Removed rows are excluded.", "properties": { "articleNumber": { "type": [ "string", "null" ], "description": "Article number (id) of the row." }, "description": { "type": [ "string", "null" ], "description": "Article description shown on the invoice." }, "price": { "type": "number", "format": "double", "description": "Price per unit, incl. VAT." }, "totalPrice": { "type": "number", "format": "double", "description": "Total price of the row, incl. VAT (`price` × `quantity`)." }, "vatRate": { "type": "number", "format": "double", "description": "VAT rate for the line (e.g. 25 for 25%)." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 three-letter currency code." }, "quantity": { "type": "integer", "format": "int32", "description": "Number of units on the row." }, "status": { "type": "string", "description": "Row status, e.g. `NotActivated`, `Activated`, `Returned`, `Expired`." }, "captureId": { "type": [ "string", "null" ], "description": "Identifier of the capture the row belongs to. Only present for activated or returned rows." }, "capturedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the row was activated (captured). Only present for activated or returned rows." }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Only present for returned rows." } } }, "OrderInvoice": { "type": "object", "description": "An invoice connected to the order. Cancelled invoices are excluded.", "properties": { "invoiceNumber": { "type": [ "string", "null" ], "description": "Invoice number." }, "paymentStatus": { "type": "string", "description": "Payment status of the invoice, e.g. `NotPaid`." }, "totalAmount": { "type": "number", "format": "double", "description": "Total invoice amount, incl. VAT." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invoice was created." }, "dueDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the invoice is due for payment." } } }, "ManageOrder": { "type": "object", "description": "The compact order representation returned by default from `GET /manage/orders/{orderId}`.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Order identifier." }, "reference": { "type": [ "string", "null" ], "description": "The merchant order reference (order number)." }, "paymentMethod": { "type": "string", "description": "Payment method of the order, e.g. `Invoice`, `Account`, `Installment`, `Card`, `Swish`, `BankTransfer`, `Vipps`, `MobilePay`, `ApplePay`." }, "totalAmount": { "type": "number", "format": "double", "description": "Current total order amount, incl. VAT." }, "currency": { "type": "string", "description": "ISO 4217 three-letter currency code." }, "status": { "type": "string", "description": "Order status, e.g. `Not activated`, `Partly activated`, `Activated`, `Canceled`, `Expired`, `On hold`." }, "salesSegment": { "type": [ "string", "null" ], "description": "`B2C` or `B2B`." }, "countryCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the order's market." }, "productCode": { "type": [ "string", "null" ], "description": "Code of the Walley credit product the order was placed on, e.g. `DI_SERVICE_001`." }, "placedAt": { "type": "string", "format": "date-time", "description": "When the order was placed." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order expires unless activated." }, "customer": { "$ref": "#/components/schemas/OrderCustomer" }, "deliveryAddress": { "$ref": "#/components/schemas/OrderAddress" }, "invoiceAddress": { "$ref": "#/components/schemas/OrderAddress", "description": "Null for prepaid payment methods." }, "electronicInvoiceAddress": { "$ref": "#/components/schemas/ElectronicInvoiceAddress" }, "items": { "type": "array", "description": "The order rows. Removed rows are excluded.", "items": { "$ref": "#/components/schemas/OrderRowItem" } }, "invoices": { "type": "array", "description": "Invoices connected to the order. Cancelled invoices are excluded.", "items": { "$ref": "#/components/schemas/OrderInvoice" } } } }, "OrderResponse": { "type": "object", "description": "Envelope for the compact order representation.", "properties": { "data": { "$ref": "#/components/schemas/ManageOrder" }, "links": { "type": "object", "description": "Available links for the order, e.g. `self`.", "additionalProperties": { "$ref": "#/components/schemas/ManageLink" } }, "metaData": { "type": "object", "description": "Empty for single-resource responses." } } }, "OrderDetailsRow": { "type": "object", "description": "An order row in the full order representation. Unlike the compact representation, removed rows are included.", "properties": { "rowId": { "type": [ "string", "null" ], "description": "Row identifier." }, "groupId": { "type": [ "string", "null" ], "description": "Groups rows that belong together." }, "articleNumber": { "type": [ "string", "null" ], "description": "Article number (id) of the row." }, "description": { "type": [ "string", "null" ], "description": "Article description shown on the invoice." }, "price": { "type": "number", "format": "double", "description": "Price per unit, incl. VAT." }, "originalPrice": { "type": "number", "format": "double", "description": "Price per unit at purchase, before later adjustments." }, "totalPrice": { "type": "number", "format": "double", "description": "Total price of the row, incl. VAT (`price` × `quantity`)." }, "vatRate": { "type": "number", "format": "double", "description": "VAT rate for the row (e.g. 25 for 25%)." }, "vatAmount": { "type": "number", "format": "double", "description": "VAT amount for the row." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 three-letter currency code." }, "quantity": { "type": "integer", "format": "int32", "description": "Number of units on the row." }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure, e.g. `st`." }, "purchaseId": { "type": [ "string", "null" ], "description": "Identifier of the purchase (capture) the row belongs to." }, "addedAt": { "type": "string", "format": "date-time", "description": "When the row was added to the order." }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the row was activated (captured), when applicable." }, "status": { "type": "string", "description": "Row status, e.g. `NotActivated`, `Activated`, `Returned`, `Expired`, `Removed`." }, "rowSource": { "type": [ "string", "null" ], "description": "Origin of the row." } } }, "OrderDetailsEvent": { "type": "object", "description": "An event in the order history.", "properties": { "eventId": { "type": [ "string", "null" ], "description": "Unique identifier (GUID) of the event." }, "eventType": { "type": "string", "description": "Type of event, e.g. activation, cancellation, notification." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred." }, "metaData": { "type": [ "object", "null" ], "description": "Additional event data as key/value pairs." } } }, "OrderDetailsPurchase": { "type": "object", "description": "A purchase (capture) of the order, wrapped in its own envelope.", "properties": { "data": { "type": "object", "description": "The purchase: its identifier and the rows it contains.", "properties": { "purchaseId": { "type": [ "string", "null" ], "description": "Purchase identifier." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailsRow" }, "description": "The order rows belonging to this purchase." } } }, "links": { "type": "object", "description": "Actions currently available on the purchase, e.g. `capture`, `cancel`, `extend`.", "additionalProperties": { "$ref": "#/components/schemas/ManageLink" } }, "metaData": { "type": "object", "description": "Empty for single-resource responses." } } }, "OrderDetailsAccountInvoice": { "type": "object", "description": "An invoice on an account connected to the order. Unlike the compact representation, cancelled invoices are included and flagged with `canceled`.", "properties": { "invoiceNumber": { "type": [ "string", "null" ], "description": "Invoice number." }, "paymentStatus": { "type": "string", "description": "Payment status of the invoice, e.g. `NotPaid`." }, "totalAmount": { "type": "number", "format": "double", "description": "Total invoice amount, incl. VAT." }, "invoiceState": { "type": [ "string", "null" ], "description": "Lifecycle state of the invoice document (distinct from `paymentStatus`), e.g. `Preliminary`, `Delivered`, `OnHold`, `Canceled`, `Expired`, `Rejected`." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invoice was created." }, "dueDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the invoice is due for payment." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invoice was sent to the customer, when applicable." }, "canceled": { "type": "boolean", "description": "True when the invoice has been cancelled." } } }, "OrderDetailsAccount": { "type": "object", "description": "An account connected to the order.", "properties": { "accountId": { "type": [ "string", "null" ], "description": "Identifier of the Walley credit account the activated purchase was booked to." }, "purchaseIdentifier": { "type": [ "string", "null" ], "description": "Identifier of the purchase the account belongs to." }, "moved": { "type": "boolean", "description": "True when the account has been moved to another account." }, "movedToAccountId": { "type": [ "string", "null" ], "description": "Identifier of the account this account was moved to, when `moved` is true." }, "currentInvoice": { "$ref": "#/components/schemas/OrderDetailsAccountInvoice", "description": "The most recently created invoice on the account, if any." }, "invoices": { "type": "array", "description": "Invoices on the account, including cancelled ones.", "items": { "$ref": "#/components/schemas/OrderDetailsAccountInvoice" } } } }, "OrderDetails": { "type": "object", "description": "The full order representation. A superset of the compact representation: adds amounts split per state, rows grouped per purchase, connected accounts with their invoices, and the order event history.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Order identifier." }, "orderNumber": { "type": [ "string", "null" ], "description": "The merchant order reference (order number)." }, "merchantId": { "type": [ "string", "null" ], "description": "Identifier of the merchant owning the order." }, "storeId": { "type": "integer", "format": "int32", "description": "Identifier of the store the order was placed in." }, "paymentMethod": { "type": "string", "description": "Payment method of the order, e.g. `Invoice`, `Account`, `Installment`, `Card`, `Swish`, `BankTransfer`, `Vipps`, `MobilePay`, `ApplePay`." }, "isPrepaidPaymentMethod": { "type": "boolean", "description": "True for prepaid payment methods; such orders have no invoice address." }, "totalAmount": { "type": "number", "format": "double", "description": "Current total order amount, incl. VAT." }, "totalVat": { "type": "number", "format": "double", "description": "Total VAT amount of the order." }, "originalOrderAmount": { "type": [ "number", "null" ], "format": "double", "description": "The order amount at purchase, before later adjustments." }, "activatedAmount": { "type": [ "number", "null" ], "format": "double", "description": "The part of the order amount that has been activated (captured)." }, "notActivatedAmount": { "type": [ "number", "null" ], "format": "double", "description": "The part of the order amount not yet activated." }, "currency": { "type": "string", "description": "ISO 4217 three-letter currency code." }, "status": { "type": "string", "description": "Order status, e.g. `Not activated`, `Partly activated`, `Activated`, `Canceled`, `Expired`, `On hold`." }, "countryCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the order's market." }, "productCode": { "type": [ "string", "null" ], "description": "Code of the Walley credit product the order was placed on, e.g. `DI_SERVICE_001`." }, "placedAt": { "type": "string", "format": "date-time", "description": "When the order was placed." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order expires unless activated." }, "customerDetails": { "type": [ "object", "null" ], "description": "Customer details as key/value pairs. National registration numbers are masked. Null after the details have been purged." }, "customerDetailsPurged": { "type": "boolean", "description": "True when customer details have been removed for data-retention reasons." }, "deliveryAddress": { "$ref": "#/components/schemas/OrderAddress" }, "invoiceAddress": { "$ref": "#/components/schemas/OrderAddress", "description": "Null for prepaid payment methods." }, "electronicInvoiceAddress": { "$ref": "#/components/schemas/ElectronicInvoiceAddress" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailsEvent" }, "description": "History of events that have occurred on the order." }, "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailsPurchase" }, "description": "The purchases (captures) of the order with their rows." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailsAccount" }, "description": "Accounts connected to the order with their invoices." }, "costCenter": { "type": [ "string", "null" ], "description": "Cost center stated by the customer at purchase (B2B orders), when present." }, "referencePerson": { "type": [ "string", "null" ], "description": "Invoice reference person stated by the customer at purchase (B2B orders), when present." }, "commitmentAlias": { "type": [ "object", "null" ], "description": "Commitment alias connected to the order, when present.", "properties": { "integrationId": { "type": [ "string", "null" ], "description": "Masked integration id." }, "description": { "type": [ "string", "null" ], "description": "Description of the commitment alias." } } }, "customerToken": { "type": [ "string", "null" ], "description": "Customer token connected to the order, if any." } } }, "OrderDetailsResponse": { "type": "object", "description": "Envelope for the full order representation, as returned by `GET /manage/orders/{orderId}` with `Accept: application/vnd.merchanthub.order+json` and by the synchronous (`200`) responses of the capture, cancel and extend actions.", "properties": { "data": { "$ref": "#/components/schemas/OrderDetails" }, "links": { "type": "object", "description": "Actions currently available on the order, e.g. `capture`, `cancel`, `extend`, `refund`.", "additionalProperties": { "$ref": "#/components/schemas/ManageLink" } }, "metaData": { "type": "object", "description": "Empty for single-resource responses." } } }, "OrderSummary": { "type": "object", "description": "An order as returned in search results. Additional undocumented fields may appear in the payload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Order identifier." }, "orderNumber": { "type": [ "string", "null" ], "description": "The merchant order reference." }, "paymentMethod": { "type": "string", "description": "Payment method of the order, e.g. `Invoice`, `Account`, `Installment`, `Card`, `Swish`, `BankTransfer`, `Vipps`, `MobilePay`, `ApplePay`." }, "totalAmount": { "type": "number", "format": "double", "description": "Current total order amount, incl. VAT." }, "totalVat": { "type": "number", "format": "double", "description": "Total VAT amount of the order." }, "currency": { "type": "string", "description": "ISO 4217 three-letter currency code." }, "status": { "type": "string", "description": "Order status, e.g. `Not activated`, `Partly activated`, `Activated`, `Canceled`, `Expired`, `On hold`." }, "countryCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the order's market." }, "productCode": { "type": [ "string", "null" ], "description": "Code of the Walley credit product the order was placed on, e.g. `DI_SERVICE_001`." }, "placedAt": { "type": "string", "format": "date-time", "description": "When the order was placed." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order expires unless activated." }, "deliveryAddress": { "$ref": "#/components/schemas/OrderAddress" }, "invoiceAddress": { "$ref": "#/components/schemas/OrderAddress" }, "electronicInvoiceAddress": { "$ref": "#/components/schemas/ElectronicInvoiceAddress" } } }, "OrderSearchResponse": { "type": "object", "description": "A paged list of orders.", "properties": { "data": { "type": "array", "description": "The orders on this page.", "items": { "$ref": "#/components/schemas/OrderSummary" } }, "links": { "$ref": "#/components/schemas/ManagePaginationLinks" }, "metaData": { "$ref": "#/components/schemas/PaginationMetaData" } } }, "ManageProblemDetails": { "type": "object", "description": "Error response for Order Management requests, based on RFC 9457 problem details plus a Walley problem code. `code` is the machine-readable identifier of the problem, and the response description of each operation lists the codes it can return. Request-validation failures use the top-level code `REQUEST_INVALID` and list the offending fields in `errors`. Other problems set `code` directly and omit `errors`.", "properties": { "title": { "type": "string", "description": "Human-readable summary of the problem." }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code, repeated from the response." }, "detail": { "type": "string", "description": "Additional human-readable detail about this occurrence of the problem. Omitted when there is nothing to add." }, "code": { "$ref": "#/components/schemas/ProblemCode" }, "errors": { "type": "array", "description": "Field-level validation failures. Present only when `code` is `REQUEST_INVALID`.", "items": { "$ref": "#/components/schemas/ManageValidationError" } } }, "required": [ "title", "status", "code" ] }, "ManageValidationError": { "type": "object", "description": "One field-level failure from request validation.", "properties": { "name": { "type": "string", "description": "Name of the offending request field, as bound from the body or query string." }, "code": { "$ref": "#/components/schemas/ProblemCode" }, "message": { "type": "string", "description": "Human-readable explanation of the failure." } }, "required": [ "name", "code", "message" ] }, "ProblemCode": { "type": "string", "description": "Machine-readable problem code identifying why an Order Management request was rejected. The API may return additional codes not listed here; treat an unrecognized code as a generic rejection.\n\n| Code | Meaning |\n| --- | --- |\n| `REQUEST_INVALID` | The request is not valid; the offending fields are listed in `errors`. |\n| `ACTION_REFERENCE_TOO_LONG` | `actionReference` has a max limit of 255 characters. |\n| `SEARCH_QUERY_INVALID` | The search has an invalid format and cannot be performed. |\n| `DUPLICATE_SEARCH_FILTER_PROPERTIES` | The same filter property was supplied more than once. |\n| `PAGE_RANGE` | `page` is not in the allowed range. |\n| `PER_PAGE_RANGE` | `perPage` is not in the allowed range. |\n| `RESULT_WINDOW_SIZE` | The search generated too many results; narrow it down with more filters. |\n| `CAPTURE_AMOUNT_MUST_NOT_BE_NEGATIVE` | The amount to be captured must be zero or greater. |\n| `CAPTURE_AMOUNT_TOO_LARGE` | The amount to be captured cannot be larger than the sum of all items. |\n| `CAPTURE_AMOUNT_HAS_TOO_MANY_DECIMALS` | The amount to be captured cannot have more than 2 decimals. |\n| `CAPTURE_AMOUNT_GREATER_THAN_INVOICE_AMOUNT` | The amount to be captured cannot be larger than the current order amount. |\n| `CAPTURE_ITEMS_AMOUNT_NOT_EQUAL_TO_TOTAL_AMOUNT` | When items are provided, `amount` must equal the total sum of the items. |\n| `CAPTURE_ITEMS_UNITPRICE_HAS_TOO_MANY_DECIMALS` | The unit price of an item in the items list has too many decimals. |\n| `CAPTURE_ITEMS_MISSING_ID` | When replacing items, every item must have an `id`. |\n| `CAPTURE_DESCRIPTION_TOO_LONG` | Description has a max limit of 50 characters. |\n| `CAPTURE_ORDER_ALREADY_CAPTURED` | A captured order cannot be captured again. |\n| `CAPTURE_INVALID_INVOICE_STATUS` | An order in state closed or expired cannot be captured. |\n| `CANCEL_INVALID_INVOICE_STATUS` | The order must have pending rows to be canceled. |\n| `REFUND_AMOUNT_MUST_BE_POSITIVE` | The refunded amount cannot have a negative value. |\n| `REFUND_AMOUNT_MUST_MATCH_SUM_OF_ARTICLES` | When items are provided, `amount` must equal the total sum of the items. |\n| `REFUND_AMOUNT_HAS_TOO_MANY_DECIMALS` | The amount to be refunded has too many decimals. |\n| `REFUND_VAT_HAS_TOO_MANY_DECIMALS` | The VAT rate given has too many decimals. |\n| `REFUND_DESCRIPTION_TOO_LONG` | Description has a max limit of 50 characters. |\n| `REFUND_ORDER_ALREADY_FULLY_REFUNDED` | An already fully refunded order cannot be refunded again. |\n| `REFUND_UNMATCHED_RETURN_ARTICLES` | Items provided for part refund cannot be found on the order; `id`, `description` and `unitPrice` must match the order item values exactly. |\n| `REFUND_ITEM_ID_TOO_LONG` | Item id has a max limit of 50 characters. |\n| `REFUND_ITEM_DESCRIPTION_TOO_LONG` | Item description has a max limit of 50 characters. |\n| `REFUND_ITEM_QUANTITY_MUST_BE_POSITIVE` | Item quantity must be positive. |\n| `REFUND_ITEM_UNITPRICE_HAS_TOO_MANY_DECIMALS` | Item unit price has too many decimals. |\n| `REFUND_ITEM_FEE_OR_DISCOUNT_ID_AND_DESCRIPTION_REQUIRED` | Fees and discounts must have an `id` and a `description`. |\n| `REFUND_REPLACEMENT_ITEM_QUANTITY_INVALID` | When refunding and replacing the same item in one request, the replacement quantity cannot exceed the refund quantity. |\n| `ORDER_CANNOT_BE_EXTENDED` | The order cannot be extended: it has no open pending invoice or is not close enough to expiration. |\n| `REAUTHORIZE_AMOUNT_MUST_BE_GREATER_THAN_ZERO` | Total amount must be positive. |\n| `REAUTHORIZE_AMOUNT_MUST_MATCH_SUM_OF_ARTICLES` | Total amount must match the summed article amount. |\n| `REAUTHORIZE_AMOUNT_HAS_TOO_MANY_DECIMALS` | Total amount has too many decimals. |\n| `REAUTHORIZE_ORDER_INCREASE_ABOVE_CURRENT_TOTAL_AMOUNT_IS_NOT_ALLOWED` | Total amount must be less than or equal to the original amount. |\n| `REAUTHORIZE_INCREASED_AMOUNT_NOT_AVAILABLE_FOR_PREPAID_PAYMENT_METHOD` | The order amount cannot be increased on prepaid orders. |\n| `REAUTHORIZE_DESCRIPTION_TOO_LONG` | Description has a max limit of 50 characters. |\n| `REAUTHORIZE_ID_TOO_LONG` | Item id has a max limit of 50 characters. |\n| `REAUTHORIZE_UNIT_PRICE_HAS_TOO_MANY_DECIMALS` | Item unit price has too many decimals. |\n| `REAUTHORIZE_QUANTITY_MUST_BE_GREATER_THAN_ZERO` | Item quantity must be greater than zero. |\n| `REAUTHORIZE_VAT_MUST_BE_GREATER_THAN_ZERO` | Item VAT must be greater than zero. |\n| `REAUTHORIZE_ORDER_ALREADY_CAPTURED` | An already fully captured order cannot be reauthorized. |\n| `REAUTHORIZE_INVALID_INVOICE_STATUS` | An order in state closed or expired cannot be reauthorized. |\n| `REAUTHORIZE_MATCHING_ARTICLES_WITH_DIFFERENT_VAT` | The request includes identical articles with mismatched VAT. |\n| `REAUTHORIZE_ARTICLE_EXISTS_BUT_OTHER_INFORMATION` | The request includes identical articles with mismatched unit price. |\n| `REAUTHORIZE_ALREADY_IN_PROCESS` | A reauthorization is already in process for this order; retry when it completes. |\n| `IDEMPOTENCY_KEY_ALREADY_IN_USE_FOR_DIFFERENT_REQUEST` | The idempotency key was already used for a different request; use a new key. |" }, "SettlementsLink": { "type": "object", "description": "A HATEOAS link describing a related request.", "properties": { "method": { "type": "string", "description": "HTTP method to use for the link.", "examples": [ "GET" ] }, "href": { "type": "string", "description": "Path of the linked resource.", "examples": [ "/reports/settlements/1/transactions" ] }, "query": { "type": "string", "description": "Query string of the linked resource, if any.", "examples": [ "" ] } } }, "SettlementsPaginationLinks": { "type": "object", "description": "Links for navigating the paged result set.", "properties": { "self": { "$ref": "#/components/schemas/SettlementsLink" }, "next": { "$ref": "#/components/schemas/SettlementsLink" }, "prev": { "$ref": "#/components/schemas/SettlementsLink" } } }, "MetaData": { "type": "object", "description": "Paging metadata for the result set.", "properties": { "totalNumberOfRecords": { "type": "integer", "format": "int64", "description": "Total number of records across all pages.", "examples": [ 100 ] }, "numberOfPages": { "type": "integer", "format": "int32", "description": "Total number of pages.", "examples": [ 100 ] }, "currentPage": { "type": "integer", "format": "int32", "description": "The page returned in this response.", "examples": [ 1 ] }, "range": { "$ref": "#/components/schemas/SettlementsIndexRange" } } }, "SettlementsIndexRange": { "type": "object", "description": "The 1-based range of records included in this page.", "properties": { "from": { "type": "integer", "format": "int64", "description": "Index of the first record on this page.", "examples": [ 1 ] }, "to": { "type": "integer", "format": "int64", "description": "Index of the last record on this page.", "examples": [ 10 ] } } }, "Settlement": { "type": "object", "description": "A settlement: the transactions Walley paid out together for one store in a single remittance.", "properties": { "id": { "type": "string", "description": "The id of the settlement.", "examples": [ "1" ] }, "startDate": { "type": "string", "description": "The start date of captures and refunds included in the settlement. Local date-time without a timezone offset.", "examples": [ "2022-12-30T00:00:00" ] }, "endDate": { "type": "string", "description": "The end date of captures and refunds included in the settlement. Local date-time without a timezone offset.", "examples": [ "2022-12-30T00:00:00" ] }, "storeId": { "type": "integer", "format": "int32", "description": "The id of the store that has been settled.", "examples": [ 1 ] }, "ingoingBalance": { "type": "number", "format": "double", "description": "If the previous settlement had a negative balance, it is moved onto this settlement.", "examples": [ 0 ] }, "totalAmount": { "type": "number", "format": "double", "description": "The amount that will be paid out for the period.", "examples": [ 100000 ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three-letter currency code of the purchases that have been settled.", "examples": [ "SEK" ] }, "netSales": { "type": "number", "format": "double", "description": "The net sales during the settled period.", "examples": [ 100000 ] }, "paidOutAt": { "type": "string", "format": "date-time", "description": "The date of the payout.", "examples": [ "2023-01-02T11:00:10.000000+01:00" ] }, "generatedAt": { "type": "string", "format": "date-time", "description": "The date and time the settlement was generated.", "examples": [ "2023-01-02T11:00:10.000000+01:00" ] }, "captured": { "type": "number", "format": "double", "description": "The captured amount during the settlement period.", "examples": [ 103000 ] }, "refunded": { "type": "number", "format": "double", "description": "The returned amount during the settlement period.", "examples": [ -3000 ] }, "reference": { "type": [ "string", "null" ], "description": "The settlement reference. Only shown for merchants with the settlement reference option activated.", "examples": [ "2134" ] }, "compensations": { "type": "number", "format": "double", "description": "All Walley fees for the settlement period, summarized.", "examples": [ 0 ] }, "adjustments": { "type": "number", "format": "double", "description": "Settlement adjustments. See the manual adjustment types in the Reports documentation.", "examples": [ 0 ] }, "links": { "$ref": "#/components/schemas/SettlementLinks" } } }, "SettlementLinks": { "type": "object", "description": "Links to related resources for this settlement.", "properties": { "pdf": { "$ref": "#/components/schemas/SettlementsLink" }, "transactions": { "$ref": "#/components/schemas/SettlementsLink" } } }, "SettlementSearchResponse": { "type": "object", "description": "A paged list of settlements.", "properties": { "data": { "type": "array", "description": "The settlements on this page.", "items": { "$ref": "#/components/schemas/Settlement" } }, "links": { "$ref": "#/components/schemas/SettlementsPaginationLinks" }, "metaData": { "$ref": "#/components/schemas/MetaData" } } }, "VatAmount": { "type": "object", "description": "The VAT amount paid for a single VAT rate.", "properties": { "vatRate": { "type": "number", "format": "double", "description": "VAT rate as a percentage.", "examples": [ 25 ] }, "amount": { "type": "number", "format": "double", "description": "The VAT amount for this rate.", "examples": [ 180 ] } } }, "SettlementTransactionType": { "type": "string", "description": "The type of settlement transaction. See the Settlement Types documentation for full definitions.", "enum": [ "Purchase", "Return", "PurchaseAmountAdjustment", "DirectPayment", "Credited customer fees", "Kickback (%)", "Kickback", "Transaction fee, subject to VAT", "Service fee, subject to VAT", "Fee for requested invoice print, subject to VAT", "SettlementVatCost" ], "examples": [ "Purchase" ] }, "SettlementTransaction": { "type": "object", "description": "A single transaction included in a settlement.", "properties": { "customerNumber": { "type": "string", "description": "Custom value that can be provided at purchase.", "examples": [ "" ] }, "firstName": { "type": "string", "description": "B2C customer's first name; for B2B the company name.", "examples": [ "Test" ] }, "lastName": { "type": "string", "description": "B2C customer's last name; empty for B2B.", "examples": [ "Test" ] }, "amount": { "type": "number", "format": "double", "description": "Transaction amount.", "examples": [ 1000 ] }, "purchaseDate": { "type": "string", "format": "date", "description": "The date when the purchase was captured.", "examples": [ "2022-01-01" ] }, "transactionDate": { "type": "string", "format": "date", "description": "Custom date value provided at purchase.", "examples": [ "2020-01-01" ] }, "invoiceNumber": { "type": "string", "description": "The purchase invoice number.", "examples": [ "11111111" ] }, "orderNumber": { "type": "string", "description": "Custom value that can be provided at purchase. In Checkout, the reference.", "examples": [ "ORDER-12345" ] }, "type": { "$ref": "#/components/schemas/SettlementTransactionType" }, "totalVatAmountPerRate": { "type": "array", "description": "The amount of VAT paid for each VAT rate.", "items": { "$ref": "#/components/schemas/VatAmount" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The purchase currency, as an ISO 4217 three-letter code.", "examples": [ "SEK" ] }, "orderId": { "type": [ "string", "null" ], "format": "uuid", "description": "The id of the order associated with the transaction. Available on types Purchase, Return, and PurchaseAmountAdjustment.", "examples": [ "4f35934d-dcf7-4929-b1ec-179155a6db58" ] }, "productCode": { "type": [ "string", "null" ], "description": "The product code associated with the transaction. Possibly empty. Included only when includeProductCode is true.", "examples": [ "DI001" ] } } }, "SettlementTransactionsResponse": { "type": "object", "description": "A paged list of settlement transactions.", "properties": { "data": { "type": "array", "description": "The transactions on this page.", "items": { "$ref": "#/components/schemas/SettlementTransaction" } }, "links": { "$ref": "#/components/schemas/SettlementsPaginationLinks" }, "metaData": { "$ref": "#/components/schemas/MetaData" } } }, "SettlementsProblemDetails": { "type": "object", "description": "Error response for Settlements requests, based on RFC 9457 problem details plus a Walley problem code. `code` is the machine-readable identifier of the problem, and the response description of each operation lists the codes it can return. Request-validation failures use the top-level code `REQUEST_INVALID` and list the offending fields in `errors`. Other problems set `code` directly and omit `errors`.", "properties": { "title": { "type": "string", "description": "Human-readable summary of the problem." }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code, repeated from the response." }, "detail": { "type": "string", "description": "Additional human-readable detail about this occurrence of the problem. Omitted when there is nothing to add." }, "code": { "type": "string", "description": "Machine-readable problem code identifying why a Settlements request was rejected. The API may return additional codes not listed here; treat an unrecognized code as a generic rejection.\n\n| Code | Meaning |\n| --- | --- |\n| `REQUEST_INVALID` | The request is not valid; the offending fields are listed in `errors`. |\n| `SEARCH_QUERY_INVALID` | The search has an invalid format and cannot be performed. |\n| `PAGE_RANGE` | `page` is not in the allowed range. |\n| `PER_PAGE_RANGE` | `perPage` is not in the allowed range. |\n| `RESULT_WINDOW_SIZE` | The search generated too many results; narrow it down with more filters. |", "examples": [ "RESULT_WINDOW_SIZE" ] }, "errors": { "type": "array", "description": "Field-level validation failures. Present only when `code` is `REQUEST_INVALID`.", "items": { "$ref": "#/components/schemas/SettlementsValidationError" } } }, "required": [ "title", "status", "code" ] }, "SettlementsValidationError": { "type": "object", "description": "One field-level failure from request validation.", "properties": { "name": { "type": "string", "description": "Name of the offending request field, as bound from the query string.", "examples": [ "perPage" ] }, "code": { "type": "string", "description": "Machine-readable problem code for this field.", "examples": [ "PER_PAGE_RANGE" ] }, "message": { "type": "string", "description": "Human-readable explanation of the failure." } }, "required": [ "name", "code", "message" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token from the OAuth2 client credentials flow (`POST /oauth2/v2.0/token` on the environment's API host). Fetch it outside the browser and paste it here. See [Authentication](https://dev.walleypay.com/docs/manage/getting-started/authentication) for the endpoints and scope values." } }, "parameters": { "CustomerTokens_CorrelationId": { "name": "CorrelationId", "in": "header", "required": false, "description": "Optional value used to correlate the request with the response. A GUID is returned as the response `id`; any other non-empty string is returned in the response `context` instead, and `id` is generated.", "schema": { "type": "string" } }, "CustomerTokens_AuthorizationIdPath": { "name": "authorizationId", "in": "path", "required": true, "description": "Identifier of the authorization.", "schema": { "type": "string", "format": "uuid" } }, "CustomerTokens_CustomerTokenPath": { "name": "customerToken", "in": "path", "required": true, "description": "Identifier of the customer token.", "schema": { "type": "string", "format": "uuid" } }, "CustomerTokens_IdempotencyKey": { "name": "Walley-Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key. Must be a GUID. Repeating a request with the same key returns the cached response of the first request (2xx responses only). While the first request is still running, or after its cached response has expired, the repeat returns 422. Reusing a key on a different endpoint also returns 422.", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "CustomerTokens_InternalServerError": { "description": "An unexpected error occurred. The `errors` array is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "CustomerTokens_ServiceUnavailable": { "description": "A downstream dependency timed out or was unavailable (`DOWNSTREAM_TIMEOUT` or `DOWNSTREAM_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "examples": { "Manage_FullOrder": { "summary": "Full order representation", "value": { "data": { "id": "a2042556-7d8a-49e2-a810-ace200ca3041", "orderNumber": "12345", "merchantId": null, "storeId": 1158, "paymentMethod": "Invoice", "totalAmount": 31.98, "totalVat": 6.4, "currency": "SEK", "status": "Not activated", "countryCode": "SE", "placedAt": "2021-03-05T13:16:08.7737385+01:00", "expiresAt": "2021-09-07T23:59:59+02:00", "customerDetails": { "type": "Person", "name": "Test Testsson", "firstName": "Test", "lastName": "Testsson", "customerId": 1234567, "registrationNumber": "510731****", "countryCode": "SE", "addressLine1": "Test Street 2", "city": "Test City", "postalCode": "12345", "email": "test@example.com", "mobilePhoneNumber": "+46701234567" }, "deliveryAddress": { "addressLine1": "Test Street 1", "addressLine2": null, "city": "Test City", "coAddress": null, "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": null, "postalCode": "12345" }, "invoiceAddress": { "addressLine1": "Test Street 2", "addressLine2": null, "city": "Test City", "coAddress": null, "receiverName": "Test Testsson", "countryCode": "SE", "email": "test@example.com", "mobilePhone": "+46701234567", "phoneNumber": null, "postalCode": "12345" }, "events": [ { "eventId": "70528675-8fde-4e5d-b2eb-cd374496a470", "eventType": "Created", "occurredAt": "2021-03-05T13:16:08.7737385+01:00", "metaData": { "status": "NotActivated", "originatedFrom": "Walley Checkout", "amount": 31.98, "by": "coll_check" } }, { "eventId": "order-extended-0483826e-ae5e-4d0f-a053-fde0801fad88", "eventType": "Extended", "occurredAt": "2021-03-11T17:24:39.5468851+00:00", "metaData": { "originatedFrom": "MerchantHub", "by": "test.testsson@example.com" } } ], "purchases": [ { "data": { "purchaseId": "80378000", "rows": [ { "rowId": "MTExMTFJdGVtIG9uZTUuMDA4MDM3ODAwMEZhbHNl", "groupId": "MTExMTFJdGVtIG9uZTUuMDA=", "articleNumber": "11111", "description": "Item one", "price": 5, "originalPrice": 5, "totalPrice": 5, "vatRate": 25, "vatAmount": 1, "currency": "SEK", "quantity": 1, "unit": "", "purchaseId": "80378000", "addedAt": "2021-03-05T13:16:08.7737385+01:00", "activatedAt": null, "status": "NotActivated" } ] }, "links": { "activate": { "method": "POST", "href": "/orders/a2042556-7d8a-49e2-a810-ace200ca3041/activate", "query": "" }, "cancel": { "method": "POST", "href": "/orders/a2042556-7d8a-49e2-a810-ace200ca3041/cancel", "query": "" }, "update": { "method": "PATCH", "href": "/orders/a2042556-7d8a-49e2-a810-ace200ca3041/purchases/80378000", "query": "" } }, "metaData": {} } ], "accounts": [] }, "links": { "self": { "method": "GET", "href": "/orders/a2042556-7d8a-49e2-a810-ace200ca3041", "query": "" } }, "metaData": {} } } } }, "servers": [ { "url": "https://api.uat.walleydev.com", "description": "UAT (test environment)" }, { "url": "https://api.walleypay.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ] }