{ "title": "Orders API", "description": "The Orders API enables merchants to create and manage orders. Orders must be created to initiate payments because each payment is assigned to a specific order. In this way, each payment is coupled with the total payable amount and detailed line items like products purchased, the quantity of products, the individual price per item etc. This streamlines the payment operations (tracking, receipts, refunds etc.).", "endpoints": [ { "fragment": "Create Order", "method": "POST", "link": "API_URL/orders" }, { "fragment": "Update Order", "method": "PUT", "link": "API_URL/orders/:orderId" }, { "fragment": "Fetch Order Status", "method": "GET", "link": "API_URL/orders/:orderId/status" }, { "fragment": "Fetch Order By Id", "method": "GET", "link": "API_URL/orders/:orderId" }, { "fragment": "Update Customer Details", "method": "PUT", "link": "API_URL/orders/:orderId/customer" }, { "fragment": "Cancel an Order", "method": "DELETE", "link": "API_URL/orders/:orderId" }, { "fragment": "Add Receipt Information", "method": "PUT", "link": "API_URL/orders/:orderId/receipt" }, { "fragment": "Fetch Order Adjustments", "method": "GET", "link": "API_URL/orders/:orderId/adjustments" }, { "fragment": "Fetch Tokens from Order", "method": "GET", "link": "API_URL/orders/:orderId/tokens" }, { "fragment": "Fetch Online Orders", "method": "GET", "link": "API_URL/orders/:terminalId/online" } ], "apis": [ { "heading": "Create Order", "new": true, "description": "The createOrder API lets you create and pay for an order in a single call—supporting purchases, returns, and multiple payment methods for faster checkout.", "reqParams": [ { "name": "terminal$id", "type": "string", "mandatory": true, "description": "ID of the checkout or payment terminal" }, { "name": "referenceId", "type": "string", "mandatory": false, "description": "External reference ID for the order" }, { "name": "comments", "type": "string", "mandatory": false, "description": "Additional comments or notes for the order" }, { "name": "customer", "type": "object", "mandatory": false, "description": "Customer details for the order", "reqParams": [ { "name": "customerId", "type": "string", "mandatory": false, "description": "Unique identifier for the customer" }, { "name": "person", "type": "object", "mandatory": false, "description": "Personal information of the customer", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Person identifier." }, { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the customer", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the customer" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the customer" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the customer" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Email address of the customer" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number of the customer", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "birthDate", "type": "string", "mandatory": false, "description": "Date of birth in YYYY-MM-DD format" }, { "name": "personalNumber", "type": "string", "mandatory": false, "description": "Personal identification number" }, { "name": "coordinationNumber", "type": "string", "mandatory": false, "description": "Coordination number" }, { "name": "countryResidence", "type": "string", "description": "Country of residence of the customer" }, { "name": "gdNumber", "type": "string", "description": "Government-issued identification number of the customer" } ] }, { "name": "company", "type": "object", "mandatory": false, "description": "Company information for corporate purchases", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Company identifier." }, { "name": "vatId", "type": "string", "mandatory": false, "description": "VAT ID of the company" }, { "name": "poDetails", "type": "string", "mandatory": false, "description": "Purchase order details for the company" }, { "name": "companyName", "type": "string", "mandatory": false, "description": "Company display name." }, { "name": "registrationNumber", "type": "string", "mandatory": false, "description": "Company registration number." }, { "name": "gln", "type": "string", "mandatory": false, "description": "GLN of the buyer's e-invoice department, used to route e-invoices." } ] } ] }, { "name": "billing", "type": "object", "mandatory": false, "description": "Billing contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the billing contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the billing contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the billing contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the billing contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Billing email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for billing", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Billing address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "shipping", "type": "object", "mandatory": false, "description": "Shipping contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the shipping contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the shipping contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the shipping contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the shipping contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Recipient email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for shipping", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Shipping address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "orderLines", "type": "array", "mandatory": true, "description": "List of items in the order", "reqParams": [ { "name": "id", "type": "string", "mandatory": true, "description": "Order line identifier" }, { "name": "externalItemId", "type": "string", "mandatory": false, "description": "External order line identifier" }, { "name": "name", "type": "string", "mandatory": true, "description": "Product name" }, { "name": "categoryId", "type": "string", "mandatory": false, "description": "Product category identifier" }, { "name": "description", "type": "string", "mandatory": false, "description": "Line item description" }, { "name": "quantity", "type": "number", "mandatory": true, "description": "Quantity ordered. A negative value indicates a refund." }, { "name": "amount", "type": "object", "mandatory": true, "description": "Pricing details for the line item", "reqParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "shipping", "type": "number", "mandatory": false, "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "total", "type": "number", "mandatory": true, "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Currency (numeric ISO 4217 as string)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Tax breakdown", "reqParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Tax amount" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Tax type (e.g., VAT)" } ] } ] }, { "name": "unit", "type": "string", "mandatory": false, "description": "Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. " }, { "name": "gtin", "type": "string", "mandatory": false, "description": "Global Trade Item Number" }, { "name": "imageUrl", "type": "string", "mandatory": false, "description": "Image URL for the product" }, { "name": "brand", "type": "string", "mandatory": false, "description": "Brand name" }, { "name": "purchaseOrderId", "type": "string", "mandatory": false, "conditional": true, "description": "Mandatory purchase order identifier if it's a return item." }, { "name": "promotionApplied", "type": "string", "mandatory": false, "description": "Product promotional campaign identifier." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary metadata for the line" }, { "name": "storeId", "type": "string", "mandatory": false, "description": "Store identifier" }, { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Purchase payment identifier associated with the order line" } ] }, { "name": "totalOrderAmount", "type": "object", "mandatory": false, "description": "Total amount details of the order.", "reqParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Total campaign or discount amount applied to the order in the smallest currency unit" }, { "name": "total", "type": "number", "mandatory": true, "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Order-level tax breakdown across applied tax categories", "reqParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Total tax amount for the order in the smallest currency unit" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Applied tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Type of tax applied (e.g., VAT, GST)" } ] } ] }, { "name": "date", "type": "string", "mandatory": false, "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items" }, { "name": "adjustments", "type": "array", "mandatory": false, "description": "Order-level adjustments", "reqParams": [ { "name": "type", "type": "string", "mandatory": true, "description": "Adjustment type" }, { "name": "value", "type": "number", "mandatory": true, "description": "Adjustment value" }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items." } ] }, { "name": "controlFunctions", "type": "object", "mandatory": false, "description": "Advanced order/payment control configuration", "reqParams": [ { "name": "cancelPreviousPendingOrder", "type": "boolean", "mandatory": false, "description": "Set as true when you want to cancel all previous pending orders" }, { "name": "orderLineLevelCalculation", "type": "boolean", "mandatory": false, "description": " Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false." }, { "name": "serviceProviders", "type": "array", "mandatory": false, "description": "External service providers participating in the transaction", "reqParams": [ { "name": "serviceProviderId", "type": "string", "mandatory": true, "description": "Service provider identifier" }, { "name": "amount", "type": "object", "mandatory": false, "description": "Share/fee configuration", "reqParams": [ { "name": "percentage", "type": "number", "mandatory": false, "description": "Percentage share" }, { "name": "fixed", "type": "number", "mandatory": false, "description": "Fixed share amount" }, { "name": "adjustmentTypes", "type": "array", "mandatory": false, "description": "Allowed adjustment types for this provider as an array of string." } ] } ] }, { "name": "initiatePaymentsOptions", "type": "object", "mandatory": false, "description": "Parameters for initiating payment", "reqParams": [ { "name": "paymentMethod", "type": "string", "mandatory": false, "conditional": true, "description": "Payment method to use" }, { "name": "amount", "type": "number", "mandatory": false, "description": "Amount to charge in smallest currency units." }, { "name": "paymentMethodParams", "type": "object", "mandatory": false, "description": "Method-specific parameters", "reqParams": [ { "name": "tokenId", "type": "string", "mandatory": false, "conditional": true, "description": "Saved payment token ID" }, { "name": "bic", "type": "string", "mandatory": false, "conditional": true, "description": "The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank in cross-border transactions. It is mandatory for the ACC2ACC payment method." }, { "name": "swishMode", "type": "string", "mandatory": false, "conditional": true, "description": "Swish mode (e.g., ECOM)" }, { "name": "payeePhoneNumber", "type": "object", "mandatory": false, "description": "Mandatory phone number for SWISH payments.", "conditional": true, "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "giftCard", "type": "object", "mandatory": false, "comingSoon": true, "conditional": true, "description": "Gift card payment details", "reqParams": [ { "name": "giftCardId", "type": "string", "mandatory": false, "description": "Gift card identifier" }, { "name": "giftCardRedemptionMode", "type": "string", "mandatory": false, "description": "Redemption mode (e.g., WALLET)" } ] }, { "name": "invoice", "type": "object", "mandatory": false, "description": "Invoice payment configuration", "reqParams": [ { "name": "invoiceDistribution", "type": "string", "mandatory": false, "conditional": true, "description": "Distribution channel (e.g., EMAIL)" }, { "name": "contractReference", "type": "string", "mandatory": false, "description": "Contract reference identifier" }, { "name": "debtCollectionEnabled", "type": "boolean", "mandatory": false, "description": "Enable debt collection" }, { "name": "dueDate", "type": "string", "mandatory": false, "conditional": true, "description": "Due date or relative duration (e.g., 30d)" }, { "name": "invoicePaymentMethods", "type": "array", "mandatory": false, "conditional": true, "description": "Allowed payment methods for invoice" }, { "name": "reminder", "type": "boolean", "mandatory": false, "conditional": true, "description": "Enable reminders" } ] } ] }, { "name": "serialSplitPaymentsMode", "type": "array", "mandatory": false, "description": "An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments." }, { "name": "refundProcessingParams", "type": "object", "mandatory": false, "description": "Parameters for processing refunds", "reqParams": [ { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Original purchase payment ID" }, { "name": "refundReason", "type": "string", "mandatory": false, "description": "Reason for refund (as provided)" }, { "name": "otherReason", "type": "string", "mandatory": false, "description": "Other reason details" } ] } ] }, { "name": "tipsMode", "type": "string", "mandatory": false, "description": "Tips configuration (STANDARD | ROUNDUP | NONE)" }, { "name": "cardStatementDescriptor", "type": "string", "mandatory": false, "description": "Statement descriptor text" }, { "name": "includeAdjustmentsForRefund", "type": "boolean", "mandatory": false, "description": "Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false." }, { "name": "lockToPaymentMethods", "type": "array", "mandatory": false, "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']" }, { "name": "tapBeforeAmount", "type": "boolean", "mandatory": false, "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment." }, { "name": "delayCapture", "type": "boolean", "mandatory": false, "description": "Allows capture at a later time. " }, { "name": "delayPayout", "type": "string", "mandatory": false, "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' ." }, { "name": "fulfillmentDate", "type": "string", "mandatory": false, "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "callBackUrl", "type": "string", "mandatory": false, "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment." }, { "name": "throwErrorIfTerminalInactiveFor", "type": "number", "mandatory": false, "description": "Threshold in ms if the respective terminal has been inactive for the given time frame." }, { "name": "clearingCutOff", "type": "string", "mandatory": false, "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "currency", "type": "string", "mandatory": false, "description": "Order currency override" }, { "name": "authMode", "type": "string", "mandatory": false, "description": "It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true." }, { "name": "receipt", "type": "object", "mandatory": false, "description": "Receipt handling options", "reqParams": [ { "name": "autoPrintReceipt", "type": "boolean", "mandatory": false, "description": "Auto-print setting" }, { "name": "autoSendReceiptIfEmailAvailable", "type": "boolean", "mandatory": false, "description": "Auto-send if email present" }, { "name": "sequenceNumber", "type": "string", "mandatory": false, "description": "Receipt sequence number" }, { "name": "cashRegisterName", "type": "string", "mandatory": false, "description": "Cash register name" }, { "name": "controlUnitSerialNumber", "type": "string", "mandatory": false, "description": "Control unit serial number" }, { "name": "receiptRedirectURL", "type": "string", "mandatory": false, "description": "Receipt redirect URL" }, { "name": "cashierName", "type": "string", "mandatory": false, "description": "Cashier name" }, { "name": "promotionsToDisplay", "type": "array", "mandatory": false, "description": "Promotions to display on receipt" } ] }, { "name": "surcharges", "comingSoon": true, "mandatory": false, "type": "object", "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers.", "reqParams": [ { "name": "domestic", "type": "object", "mandatory": false, "description": "Surcharges for domestic transactions (same country).", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in domestic transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00)." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%)." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in domestic transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "international", "type": "object", "mandatory": false, "description": "Surcharges for international transactions (outside the merchant’s country).", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in international transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in international transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "eea", "type": "object", "mandatory": false, "description": "Surcharges for EEA (European Economic Area) transactions.", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in EEA transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in EEA transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] } ] }, { "name": "readTags", "type": "string", "mandatory": false, "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,", "possibleValues": [ { "value": "NONE", "description": "This value indicates that no tags are allowed for reading." }, { "value": "SINGLE", "description": "Single read allowed for the order." }, { "value": "MULTIPLE_EDITABLE", "description": "Multiple tags can be read and edited." }, { "value": "MULTIPLE_NONEDITABLE", "description": "Multiple tags can be read, but cannot be modified." } ] }, { "name": "ecrEnabled", "type": "boolean", "mandatory": false, "description": "Whether ECR (electronic cash register) mode is enabled." }, { "name": "online", "type": "object", "mandatory": false, "description": "Online payment/link settings", "reqParams": [ { "name": "enforceTokenization", "type": "boolean", "mandatory": false, "description": "Denotes whether the card is tokenised for a future transaction or not." }, { "name": "paymentPageValidFor", "type": "string", "mandatory": false, "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d')." }, { "name": "enforce3DSecure", "type": "boolean", "mandatory": false, "description": "Force 3-D Secure authentication when available." }, { "name": "relaxed3ds", "type": "boolean", "mandatory": false, "description": "Allow relaxed 3-D Secure handling." }, { "name": "addressRequirements", "type": "boolean", "mandatory": false, "description": "Require an address on the payment page." }, { "name": "redirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter." }, { "name": "accountNameVerification", "type": "string", "mandatory": false, "description": "Account-name verification mode applied during the payment." }, { "name": "errorIfTokenizationFails", "type": "boolean", "mandatory": false, "description": "If true, fail the flow when card tokenization cannot be completed." }, { "name": "failureRedirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter." }, { "name": "tokenisationIfPossible", "type": "boolean", "mandatory": false, "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable." }, { "name": "subscription", "type": "boolean", "mandatory": false, "description": "Marks this as a subscription/recurring-capable order." }, { "name": "payButtonType", "type": "string", "mandatory": false, "description": "UI pay button label/type used on the payment page.", "possibleValues": [ { "value": "ADD_MONEY", "description": "Add money to balance" }, { "value": "BOOK", "description": "Book a service" }, { "value": "CHECKOUT", "description": "Standard checkout" }, { "value": "CONTINUE", "description": "Continue flow" }, { "value": "CONTRIBUTE", "description": "Contribute to a cause" }, { "value": "DONATE", "description": "Donate money" }, { "value": "ORDER", "description": "Place an order" }, { "value": "PAY", "description": "Pay now" }, { "value": "RENT", "description": "Rent item/service" }, { "value": "SUPPORT", "description": "Support a creator/cause" }, { "value": "TIP", "description": "Leave a tip" }, { "value": "TOP_UP", "description": "Top up balance" } ] }, { "name": "generateShortLink", "type": "boolean", "mandatory": false, "description": "If true, generates a short URL for the payment page. Default is false." }, { "name": "generateOnlineLinkWith", "type": "string", "mandatory": false, "description": "The terminal identifier used to generate the online payment link." }, { "name": "recurring", "mandatory": false, "type": "object", "description": "Encompasses all controls related to recurring payments.", "reqParams": [ { "name": "subscriptionAmountType", "type": "string", "description": "Determines the type of the subscription amount for order.", "mandatory": false, "possibleValues": [ { "value": "fixed", "description": "A fixed amount is collected." }, { "value": "variable", "description": "A variable amount is collected." } ] }, { "name": "maxAmount", "type": "number", "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "mandatory": false }, { "name": "frequency", "type": "string", "conditional": true, "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'.", "mandatory": true }, { "name": "numberOfPayments", "type": "number", "description": "Total number of payments expected for this order.", "mandatory": false }, { "name": "uniqueReference", "type": "string", "description": "A unique reference for the recurring order.", "mandatory": false }, { "name": "validation", "type": "string", "conditional": true, "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'.", "mandatory": false } ] }, { "name": "currency", "type": "string", "mandatory": false, "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK." }, { "name": "selfCardCharging", "type": "boolean", "mandatory": false, "description": "Allow the customer to self-charge their card." } ] }, { "name": "taxHandlingStrategy", "type": "object", "mandatory": false, "description": "Tax calculation strategy", "reqParams": [ { "name": "treatAmountAsTaxExclusive", "type": "boolean", "mandatory": false, "description": "Prices exclude tax" }, { "name": "taxTreatmentStrategy", "type": "string", "mandatory": false, "description": "Rounding strategy configuration" } ] } ] } ], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "data", "type": "object", "mandatory": true, "description": "Response data.", "resParams": [ { "name": "orderId", "type": "string", "description": "Order ID of the order created." }, { "name": "paymentId", "type": "string", "description": "A payment ID assigned to each payment instance. Ensure that this ID is stored securely and tied to an identifiable entity until payment completion." }, { "name": "interAppJWT", "type": "string", "description": "This key can be used in the inter-app flow to be passed in as part of the app switch. This is an optional key that can improve inter-app transaction initiation performance. This is currently only functional for CARD payments." }, { "name": "nonce", "type": "string", "description": "The authorization key required to process online payments through a SelfHostedPage terminal." }, { "name": "paymentPageLink", "type": "string", "description": "This is the payment page link where payments can be made, applicable to both PaymentPage and iFrame terminals." }, { "name": "shortLinkUrl", "type": "string", "description": "Short link to the payment page URL when generateShortLink is set to true." }, { "name": "invoiceDetails", "type": "object", "description": "Invoice details for the payment when applicable.", "resParams": [ { "name": "invoiceId", "type": "number", "description": "Unique identifier for the invoice." }, { "name": "invoicePdfUrl", "type": "string", "description": "URL to download the invoice PDF." }, { "name": "iban", "type": "string", "description": "International Bank Account Number for the invoice." }, { "name": "accountHolderName", "type": "string", "description": "Name of the account holder for the invoice." }, { "name": "bic", "type": "string", "description": "Bank Identifier Code for the invoice." }, { "name": "bankgiro", "type": "string", "description": "Bankgiro number for the invoice." }, { "name": "ocr", "type": "string", "description": "OCR reference number for the invoice payment." } ] }, { "name": "paymentUrl", "type": "string", "description": "Direct URL for payment processing." }, { "name": "qr", "type": "string", "description": "QR code data for payment." }, { "name": "qrData", "type": "string", "description": "Raw QR code data for payment processing." }, { "name": "qrVisibleFor", "type": "string", "description": "Duration for which the QR code remains visible." }, { "name": "qrLink", "type": "string", "description": "Link to the QR code for payment." }, { "name": "klarnaClientToken", "type": "string", "description": "Client token for Klarna payment processing." }, { "name": "paymentToken", "type": "string", "description": "Token for payment processing." }, { "name": "sveaInitiationParams", "type": "object", "description": "Initiation parameters for Svea payment processing." } ] }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "POST", "path": "/orders", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ], "body": "\n{\n\t\"terminal$id\": \"8386af3b0f71b80b04\",\n\t\"orderLines\": [\n\t\t{\n\t\t\t\"id\": \"TERM123\",\n\t\t\t\"name\": \"Nike Shoes\",\n\t\t\t\"quantity\": 1,\n\t\t\t\"amount\": {\n\t\t\t\t\"regular\": 500,\n\t\t\t\t\"campaign\": 0,\n\t\t\t\t\"shipping\": 0,\n\t\t\t\t\"total\": 500,\n\t\t\t\t\"currency\": \"752\",\n\t\t\t\t\"tax\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"amount\": 20,\n\t\t\t\t\t\t\"percentage\": 20,\n\t\t\t\t\t\t\"type\": \"VAT\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t}\n\t\t}\n\t],\n\t\"controlFunctions\": {\n\t\t\"initiatePaymentsOptions\": {\n\t\t\t\"paymentMethod\": \"CARD\"\n\t\t}\n\t}\n}" }, "response": [ { "code": 201, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"orderId\": \"8381a26eae26f0900b\",\n\t\t\"paymentId\": \"8381a26eae26f2af06\",\n\t\t\"interAppJWT\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvaWQiOiI4MzgxYTI2ZWFlMjZmMDkwMGIiLCJ0aWQiOiI4MzNjZWI4MjQwNGU3MDBiMDQiLCJwaWQiOiI4MzgxYTI2ZWFlMjZmMmFmMDYiLCJwbSI6IkNBU0giLCJhIjoxMDAwMCwiYyI6Ijc1MiIsImNvbnRyb2xGdW5jdGlvbnNFbmNvZGVyIjoiMCIsImlzc3VlZEJ5Ijoic2IucHMiLCJpYXQiOjE3NTg2NDk5NDk3MzN9.3pp94sCLJ_AnfkTmgcEhqv2HnGkxwXD3-ckP-TQGA94\"\n\t},\n\t\"message\": \"Order created successfully\"\n}" }, { "code": 401, "response": "\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}" } ] } }, { "heading": "Update Order", "new": true, "description": "Updates the details of an existing order. This API allows you to modify order information while retaining the same Order ID as the original order. Once a payment has been initiated for the order, further updates are no longer permitted.", "reqParams": [ { "name": "terminal$id", "type": "string", "mandatory": true, "description": "ID of the checkout or payment terminal" }, { "name": "referenceId", "type": "string", "mandatory": false, "description": "External reference ID for the order" }, { "name": "comments", "type": "string", "mandatory": false, "description": "Additional comments or notes for the order" }, { "name": "customer", "type": "object", "mandatory": false, "description": "Customer details for the order", "reqParams": [ { "name": "customerId", "type": "string", "mandatory": false, "description": "Unique identifier for the customer" }, { "name": "person", "type": "object", "mandatory": false, "description": "Personal information of the customer", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Person identifier." }, { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the customer", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the customer" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the customer" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the customer" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Email address of the customer" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number of the customer", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "birthDate", "type": "string", "mandatory": false, "description": "Date of birth in YYYY-MM-DD format" }, { "name": "personalNumber", "type": "string", "mandatory": false, "description": "Personal identification number" }, { "name": "coordinationNumber", "type": "string", "mandatory": false, "description": "Coordination number" }, { "name": "countryResidence", "type": "string", "description": "Country of residence of the customer" }, { "name": "gdNumber", "type": "string", "description": "Government-issued identification number of the customer" } ] }, { "name": "company", "type": "object", "mandatory": false, "description": "Company information for corporate purchases", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Company identifier." }, { "name": "vatId", "type": "string", "mandatory": false, "description": "VAT ID of the company" }, { "name": "poDetails", "type": "string", "mandatory": false, "description": "Purchase order details for the company" }, { "name": "companyName", "type": "string", "mandatory": false, "description": "Company display name." }, { "name": "registrationNumber", "type": "string", "mandatory": false, "description": "Company registration number." }, { "name": "gln", "type": "string", "mandatory": false, "description": "GLN of the buyer's e-invoice department, used to route e-invoices." } ] } ] }, { "name": "billing", "type": "object", "mandatory": false, "description": "Billing contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the billing contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the billing contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the billing contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the billing contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Billing email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for billing", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Billing address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "shipping", "type": "object", "mandatory": false, "description": "Shipping contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the shipping contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the shipping contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the shipping contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the shipping contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Recipient email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for shipping", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Shipping address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "orderLines", "type": "array", "mandatory": true, "description": "List of items in the order", "reqParams": [ { "name": "id", "type": "string", "mandatory": true, "description": "Order line identifier" }, { "name": "externalItemId", "type": "string", "mandatory": false, "description": "External order line identifier" }, { "name": "name", "type": "string", "mandatory": true, "description": "Product name" }, { "name": "categoryId", "type": "string", "mandatory": false, "description": "Product category identifier" }, { "name": "description", "type": "string", "mandatory": false, "description": "Line item description" }, { "name": "quantity", "type": "number", "mandatory": true, "description": "Quantity ordered. A negative value indicates a refund." }, { "name": "amount", "type": "object", "mandatory": true, "description": "Pricing details for the line item", "reqParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "shipping", "type": "number", "mandatory": false, "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "total", "type": "number", "mandatory": true, "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Currency (numeric ISO 4217 as string)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Tax breakdown", "reqParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Tax amount" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Tax type (e.g., VAT)" } ] } ] }, { "name": "unit", "type": "string", "mandatory": false, "description": "Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. " }, { "name": "gtin", "type": "string", "mandatory": false, "description": "Global Trade Item Number" }, { "name": "imageUrl", "type": "string", "mandatory": false, "description": "Image URL for the product" }, { "name": "brand", "type": "string", "mandatory": false, "description": "Brand name" }, { "name": "purchaseOrderId", "type": "string", "mandatory": false, "conditional": true, "description": "Mandatory purchase order identifier if it's a return item, i.e. a negative quantity." }, { "name": "promotionApplied", "type": "string", "mandatory": false, "description": "Product promotional campaign identifier." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary metadata for the line" }, { "name": "storeId", "type": "string", "mandatory": false, "description": "Store identifier" }, { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Purchase payment identifier associated with the order line" } ] }, { "name": "totalOrderAmount", "type": "object", "mandatory": false, "description": "Total amount details of the order.", "reqParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Total campaign or discount amount applied to the order in the smallest currency unit" }, { "name": "total", "type": "number", "mandatory": true, "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Order-level tax breakdown across applied tax categories", "reqParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Total tax amount for the order in the smallest currency unit" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Applied tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Type of tax applied (e.g., VAT, GST)" } ] } ] }, { "name": "date", "type": "string", "mandatory": false, "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items" }, { "name": "adjustments", "type": "array", "mandatory": false, "description": "Order-level adjustments", "reqParams": [ { "name": "type", "type": "string", "mandatory": true, "description": "Adjustment type" }, { "name": "value", "type": "number", "mandatory": true, "description": "Adjustment value" }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items." } ] }, { "name": "controlFunctions", "type": "object", "mandatory": false, "description": "Advanced order/payment control configuration", "reqParams": [ { "name": "cancelPreviousPendingOrder", "type": "boolean", "mandatory": false, "description": "Set as true when you want to cancel all previous pending orders" }, { "name": "orderLineLevelCalculation", "type": "boolean", "mandatory": false, "description": " Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false." }, { "name": "serviceProviders", "type": "array", "mandatory": false, "description": "External service providers participating in the transaction", "reqParams": [ { "name": "serviceProviderId", "type": "string", "mandatory": true, "description": "Service provider identifier" }, { "name": "amount", "type": "object", "mandatory": false, "description": "Share/fee configuration", "reqParams": [ { "name": "percentage", "type": "number", "mandatory": false, "description": "Percentage share" }, { "name": "fixed", "type": "number", "mandatory": false, "description": "Fixed share amount" }, { "name": "adjustmentTypes", "type": "array", "mandatory": false, "description": "Allowed adjustment types for this provider as an array of string." } ] } ] }, { "name": "initiatePaymentsOptions", "type": "object", "mandatory": false, "description": "Parameters for initiating payment", "reqParams": [ { "name": "paymentMethod", "type": "string", "mandatory": false, "description": "Payment method to use" }, { "name": "amount", "type": "number", "mandatory": false, "description": "Amount to charge in smallest currency units." }, { "name": "paymentMethodParams", "type": "object", "mandatory": false, "description": "Method-specific parameters", "reqParams": [ { "name": "tokenId", "type": "string", "mandatory": false, "description": "Saved payment token ID" }, { "name": "swishMode", "type": "string", "mandatory": false, "description": "Swish mode (e.g., ECOM)" }, { "name": "payeePhoneNumber", "type": "object", "mandatory": false, "description": "Mandatory phone number for SWISH payments.", "conditional": true, "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "giftCard", "type": "object", "mandatory": false, "comingSoon": true, "description": "Gift card payment details", "reqParams": [ { "name": "giftCardId", "type": "string", "mandatory": false, "description": "Gift card identifier" }, { "name": "giftCardRedemptionMode", "type": "string", "mandatory": false, "description": "Redemption mode (e.g., WALLET)" } ] }, { "name": "invoice", "type": "object", "mandatory": false, "description": "Invoice payment configuration", "reqParams": [ { "name": "invoiceDistribution", "type": "string", "mandatory": false, "description": "Distribution channel (e.g., EMAIL)" }, { "name": "contractReference", "type": "string", "mandatory": false, "description": "Contract reference identifier" }, { "name": "debtCollectionEnabled", "type": "boolean", "mandatory": false, "description": "Enable debt collection" }, { "name": "dueDate", "type": "string", "mandatory": false, "description": "Due date or relative duration (e.g., 30d)" }, { "name": "invoicePaymentMethods", "type": "array", "mandatory": false, "description": "Allowed payment methods for invoice" }, { "name": "reminder", "type": "boolean", "mandatory": false, "description": "Enable reminders" } ] } ] }, { "name": "serialSplitPaymentsMode", "type": "array", "mandatory": false, "description": "An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments." }, { "name": "refundProcessingParams", "type": "object", "mandatory": false, "description": "Parameters for processing refunds", "reqParams": [ { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Original purchase payment ID" }, { "name": "refundReason", "type": "string", "mandatory": false, "description": "Reason for refund (as provided)" }, { "name": "otherReason", "type": "string", "mandatory": false, "description": "Other reason details" } ] } ] }, { "name": "tipsMode", "type": "string", "mandatory": false, "description": "Tips configuration (STANDARD | ROUNDUP | NONE)" }, { "name": "cardStatementDescriptor", "type": "string", "mandatory": false, "description": "Statement descriptor text" }, { "name": "includeAdjustmentsForRefund", "type": "boolean", "mandatory": false, "description": "Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false." }, { "name": "lockToPaymentMethods", "type": "array", "mandatory": false, "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']" }, { "name": "tapBeforeAmount", "type": "boolean", "mandatory": false, "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment." }, { "name": "delayCapture", "type": "boolean", "mandatory": false, "description": "Allows capture at a later time. " }, { "name": "delayPayout", "type": "string", "mandatory": false, "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' ." }, { "name": "fulfillmentDate", "type": "string", "mandatory": false, "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "callBackUrl", "type": "string", "mandatory": false, "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment." }, { "name": "throwErrorIfTerminalInactiveFor", "type": "number", "mandatory": false, "description": "Threshold in ms if the respective terminal has been inactive for the given time frame." }, { "name": "clearingCutOff", "type": "string", "mandatory": false, "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "currency", "type": "string", "mandatory": false, "description": "Order currency override" }, { "name": "authMode", "type": "string", "mandatory": false, "description": "It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true." }, { "name": "receipt", "type": "object", "mandatory": false, "description": "Receipt handling options", "reqParams": [ { "name": "autoPrintReceipt", "type": "boolean", "mandatory": false, "description": "Auto-print setting" }, { "name": "autoSendReceiptIfEmailAvailable", "type": "boolean", "mandatory": false, "description": "Auto-send if email present" }, { "name": "sequenceNumber", "type": "string", "mandatory": false, "description": "Receipt sequence number" }, { "name": "cashRegisterName", "type": "string", "mandatory": false, "description": "Cash register name" }, { "name": "controlUnitSerialNumber", "type": "string", "mandatory": false, "description": "Control unit serial number" }, { "name": "receiptRedirectURL", "type": "string", "mandatory": false, "description": "Receipt redirect URL" }, { "name": "cashierName", "type": "string", "mandatory": false, "description": "Cashier name" }, { "name": "promotionsToDisplay", "type": "array", "mandatory": false, "description": "Promotions to display on receipt" } ] }, { "name": "surcharges", "comingSoon": true, "mandatory": false, "type": "object", "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers.", "reqParams": [ { "name": "domestic", "type": "object", "mandatory": false, "description": "Surcharges for domestic transactions (same country).", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in domestic transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00)." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%)." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in domestic transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "international", "type": "object", "mandatory": false, "description": "Surcharges for international transactions (outside the merchant’s country).", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in international transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in international transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "eea", "type": "object", "mandatory": false, "description": "Surcharges for EEA (European Economic Area) transactions.", "reqParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in EEA transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in EEA transactions.", "reqParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "reqParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] } ] }, { "name": "readTags", "type": "string", "mandatory": false, "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,", "possibleValues": [ { "value": "NONE", "description": "This value indicates that no tags are allowed for reading." }, { "value": "SINGLE", "description": "Single read allowed for the order." }, { "value": "MULTIPLE_EDITABLE", "description": "Multiple tags can be read and edited." }, { "value": "MULTIPLE_NONEDITABLE", "description": "Multiple tags can be read, but cannot be modified." } ] }, { "name": "ecrEnabled", "type": "boolean", "mandatory": false, "description": "Whether ECR (electronic cash register) mode is enabled." }, { "name": "online", "type": "object", "mandatory": false, "description": "Online payment/link settings", "reqParams": [ { "name": "enforceTokenization", "type": "boolean", "mandatory": false, "description": "Denotes whether the card is tokenised for a future transaction or not." }, { "name": "paymentPageValidFor", "type": "string", "mandatory": false, "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d')." }, { "name": "enforce3DSecure", "type": "boolean", "mandatory": false, "description": "Force 3-D Secure authentication when available." }, { "name": "relaxed3ds", "type": "boolean", "mandatory": false, "description": "Allow relaxed 3-D Secure handling." }, { "name": "addressRequirements", "type": "boolean", "mandatory": false, "description": "Require an address on the payment page." }, { "name": "redirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter." }, { "name": "accountNameVerification", "type": "string", "mandatory": false, "description": "Account-name verification mode applied during the payment." }, { "name": "errorIfTokenizationFails", "type": "boolean", "mandatory": false, "description": "If true, fail the flow when card tokenization cannot be completed." }, { "name": "failureRedirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter." }, { "name": "tokenisationIfPossible", "type": "boolean", "mandatory": false, "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable." }, { "name": "subscription", "type": "boolean", "mandatory": false, "description": "Marks this as a subscription/recurring-capable order." }, { "name": "payButtonType", "type": "string", "mandatory": false, "description": "UI pay button label/type used on the payment page.", "possibleValues": [ { "value": "ADD_MONEY", "description": "Add money to balance" }, { "value": "BOOK", "description": "Book a service" }, { "value": "CHECKOUT", "description": "Standard checkout" }, { "value": "CONTINUE", "description": "Continue flow" }, { "value": "CONTRIBUTE", "description": "Contribute to a cause" }, { "value": "DONATE", "description": "Donate money" }, { "value": "ORDER", "description": "Place an order" }, { "value": "PAY", "description": "Pay now" }, { "value": "RENT", "description": "Rent item/service" }, { "value": "SUPPORT", "description": "Support a creator/cause" }, { "value": "TIP", "description": "Leave a tip" }, { "value": "TOP_UP", "description": "Top up balance" } ] }, { "name": "generateShortLink", "type": "boolean", "mandatory": false, "description": "If true, generates a short URL for the payment page. Default is false." }, { "name": "generateOnlineLinkWith", "type": "string", "mandatory": false, "description": "The terminal identifier used to generate the online payment link." }, { "name": "recurring", "mandatory": false, "type": "object", "description": "Encompasses all controls related to recurring payments.", "reqParams": [ { "name": "subscriptionAmountType", "type": "string", "description": "Determines the type of the subscription amount for order.", "mandatory": false, "possibleValues": [ { "value": "fixed", "description": "A fixed amount is collected." }, { "value": "variable", "description": "A variable amount is collected." } ] }, { "name": "maxAmount", "type": "number", "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "mandatory": false }, { "name": "frequency", "type": "string", "conditional": true, "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'.", "mandatory": true }, { "name": "numberOfPayments", "type": "number", "description": "Total number of payments expected for this order.", "mandatory": false }, { "name": "uniqueReference", "type": "string", "description": "A unique reference for the recurring order.", "mandatory": false }, { "name": "validation", "type": "string", "conditional": true, "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'.", "mandatory": false } ] }, { "name": "currency", "type": "string", "mandatory": false, "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK." }, { "name": "selfCardCharging", "type": "boolean", "mandatory": false, "description": "Allow the customer to self-charge their card." } ] }, { "name": "taxHandlingStrategy", "type": "object", "mandatory": false, "description": "Tax calculation strategy", "reqParams": [ { "name": "treatAmountAsTaxExclusive", "type": "boolean", "mandatory": false, "description": "Prices exclude tax" }, { "name": "taxTreatmentStrategy", "type": "string", "mandatory": false, "description": "Rounding strategy configuration" } ] } ] } ], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "PUT", "path": "/orders/:orderId", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ], "body": "\n{\n\t\"terminal$id\": \"8386af3b0f71b80b04\",\n\t\"orderLines\": [\n\t\t{\n\t\t\t\"id\": \"TERM123\",\n\t\t\t\"name\": \"Nike Shoes\",\n\t\t\t\"quantity\": 1,\n\t\t\t\"amount\": {\n\t\t\t\t\"regular\": 500,\n\t\t\t\t\"campaign\": 0,\n\t\t\t\t\"shipping\": 0,\n\t\t\t\t\"total\": 500,\n\t\t\t\t\"currency\": \"752\",\n\t\t\t\t\"tax\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"amount\": 20,\n\t\t\t\t\t\t\"percentage\": 20,\n\t\t\t\t\t\t\"type\": \"VAT\"\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t}\n\t\t}\n\t],\n\t\"controlFunctions\": {\n\t\t\"initiatePaymentsOptions\": {\n\t\t\t\"paymentMethod\": \"CARD\"\n\t\t}\n\t}\n}" }, "response": [ { "code": 201, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Order updated successfully\"\n}" }, { "code": 401, "response": "\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}" } ] } }, { "heading": "Fetch Order Status", "new": true, "description": "Retrieves the status of the given order. Use this API to obtain information about the current status of the order including the respective payment and transaction details.", "reqParams": [], "resParams": [ { "name": "status", "type": "string", "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "data", "type": "object", "description": "Response data.", "resParams": [ { "name": "orderStatus", "type": "string", "mandatory": true, "description": "Describes the status of the order. The possible values are:", "possibleValues": [ { "value": "PENDING", "description": "An order has been created and is waiting for payment processing." }, { "value": "PAYMENT_COMPLETED", "description": "The payment has been completed for the order." }, { "value": "PAYMENT_CANCELLED", "description": "The payment attempt has been cancelled for the order." }, { "value": "PARTIAL_PAYMENT_COMPLETED", "description": "A partial payment was completed for the order" }, { "value": "PAYMENT_PROCESSED", "description": "The payment has been authorized." } ] }, { "name": "payments", "type": "array", "mandatory": true, "description": "Retrieves the status of all payments related to the order.", "resParams": [ { "name": "paymentId", "type": "string", "description": "Unique identifier of the payment" }, { "name": "paymentStatus", "type": "string", "mandatory": true, "description": "Describes the status of the payment. The possible values are:", "possibleValues": [ { "value": "PAYMENT_INITIATED", "description": "A payment attempt has been initiated." }, { "value": "PAYMENT_PROCESSING", "description": "The payment is being authorized." }, { "value": "PAYMENT_PROCESSED", "description": "The payment has been authorized." }, { "value": "PAYMENT_COMPLETED", "description": "The payment has been completed." }, { "value": "PAYMENT_FAILED", "description": "The payment attempt has failed." }, { "value": "PAYMENT_CANCELLED", "description": "The payment attempt has been cancelled." } ] }, { "name": "failureReason", "type": "string", "mandatory": false, "description": "Indicates the reason of the payment failure if it is available. You can refer to Concepts → Payments for a complete list of payment failure reasons." }, { "name": "paymentMethod", "type": "string", "description": "Denotes the payment method used." }, { "name": "amount", "type": "number", "description": "Amount involved with the payment attempt." } ] }, { "name": "paymentIds", "type": "array", "description": "An array of successful Payment Id(s) related to an order. Payment Ids are available once order reaches 'PAYMENT_COMPLETED' or 'PARTIAL_PAYMENT_COMPLETED' state." }, { "name": "transactions", "type": "array", "description": "Retrieves all transaction details for the order. This information is only available when orderStatus is 'PAYMENT_COMPLETED' or 'PARTIAL_PAYMENT_COMPLETED'", "resParams": [ { "name": "transactionId", "type": "string", "description": "Transaction ID of the transaction." }, { "name": "merchantId", "type": "string", "description": "Merchant ID of the merchant who performed the transaction." }, { "name": "storeId", "type": "string", "description": "Store ID of the store in which the transaction was performed" }, { "name": "terminalId", "type": "string", "description": "Terminal ID of the checkout or payment terminal from which the transaction was performed." }, { "name": "orderId", "type": "string", "description": "Order ID of the order for which the transaction was performed." }, { "name": "paymentId", "type": "string", "description": "Payment ID of the transaction." }, { "name": "referenceId", "type": "string", "description": "Reference ID of the transaction." }, { "name": "rrn", "type": "string", "description": "Displays the Retrieval Reference Number(RRN) of the transaction. RRN is a key to uniquely identify a card transaction based on the ISO 8583 standard." }, { "name": "amount", "type": "string", "description": "Amount involved in the transaction, either received or refunded by the merchant, in the minor unit of the currency. For example, 10 SEK is 1000 in amount." }, { "name": "currency", "type": "string", "description": "Three digit numeric code representing the currency of the transaction." }, { "name": "method", "type": "string", "description": "The method in which the transaction was carried out. The payment method currently supported is 'CARD'." }, { "name": "type", "type": "string", "description": "Type of the transaction. It can be either 'purchase' or 'return." }, { "name": "orderSummary", "type": "string", "description": "Specifies a short summary of the order. Usually contains the initial line items included in the order." }, { "name": "timestamp", "type": "string", "description": "Timestamp of the transaction in ISO 8601 format represented as 'YYYY-MM-DDTHH:mm:ss.sssZ'." }, { "name": "voided", "type": "boolean", "description": "A boolean value that denotes if the transaction has been voided or not." }, { "name": "issuerCountry", "type": "string", "description": "Country of the card issuer." }, { "name": "interchangeDomain", "type": "string", "description": "Interchange domain of the transaction. It can be Domestic | Intraregional-EEA | Interregional-Non-EEA." }, { "name": "cardCategory", "type": "string", "description": "Denotes the card category, which can be Consumer | Commercial." }, { "name": "cardUsage", "type": "string", "description": "Denotes the card type, whether it is Debit, Credit or Prepaid." }, { "name": "fee", "type": "string", "description": "The fee collected for each transaction. Fee associated with your settlements are determined by the billing plan you have chosen. These costs may include transaction fees, processing charges, and any additional fees specified in your subscription plan." }, { "name": "settlementStatus", "type": "string", "description": "Denotes the status of the settlement.", "possibleValues": [ { "value": "PROCESSED", "description": "Settlement processed. Waiting on amount to be credited to merchant's bank account." }, { "value": "SETTLED", "description": "The transaction was settled." }, { "value": "NOT_SETTLED", "description": "The transaction is not settled." }, { "value": "ERROR", "description": "Error occurred during the settlement process." } ] }, { "name": "payout", "type": "string", "description": "Payout is the final amount Surfboard credits to the merchant's bank account. This represents the merchant's actual earnings, which are then transferred to their bank account." }, { "name": "settlementRef", "type": "string", "description": "Reference Id for the payout which includes this transaction." }, { "name": "settlementDate", "type": "string", "description": "Date of the settlement for the transaction. Date in ISO string format." }, { "name": "truncatedPan", "type": "string", "description": "The last four digits of the PAN (Primary Account Number) from the card used for the transaction." }, { "name": "cardLabel", "type": "string", "description": "The designated label of the card brand for the transaction, often referred to as the AID (Application Identifier) Label." }, { "name": "posEntryMode", "type": "string", "description": "Indicates the mode of entry for the card during the transaction, which is based on EMV specifications. This determines whether the card was used in a contact or contactless manner." }, { "name": "issuerApplication", "type": "string", "description": "Specifies the payment application used in the transaction. Usually present when cards with both Debit and Credit facility are used." }, { "name": "terminalVerificationResult", "type": "string", "description": " Specifies the additional results if the transaction underwent EMV terminal verification." }, { "name": "aid", "type": "string", "description": "Specifies the Application Identifier (AID) associated with the card used for the transaction." }, { "name": "customerResponseCode", "type": "string", "description": "A two-character response code of the transaction. For all approved transactions, this code is '00'." }, { "name": "cvmMethod", "type": "string", "description": "Indicates the Card Holder Verification Method (CVM) used in the transaction." }, { "name": "cvmMethodDescription", "type": "string", "description": "Specifies the cvmMethod applied for the provided CARD transaction." }, { "name": "authMode", "type": "string", "description": "Indicates the authentication mode of the payment. This can be either 'ISSUER' or 'CARD'." }, { "name": "cardBrand", "type": "string", "description": "Denotes the brand of card used for the transaction. This is an optional normalized field available only for CARD payments. Eg., VISA, MASTERCARD, AMEX." } ] }, { "name": "orderLines", "type": "array", "mandatory": false, "description": "List of items in the order", "resParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Unique identifier of the order line." }, { "name": "name", "type": "string", "mandatory": false, "description": "Display name of the actor, or null." }, { "name": "quantity", "type": "number", "mandatory": false, "description": "Quantity ordered. A negative value indicates a refund." }, { "name": "amount", "type": "object", "mandatory": false, "description": "Pricing details for the order line.", "resParams": [ { "name": "regular", "type": "number", "mandatory": false, "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "total", "type": "number", "mandatory": false, "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "currency", "type": "string", "mandatory": false, "description": "ISO currency code of the amount." } ] }, { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Original purchase payment ID" } ] } ] }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "GET", "path": "/orders/:orderId/status", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"orderStatus\": \"PAYMENT_COMPLETED\",\n\t\t\"payments\": [\n\t\t\t{\n\t\t\t\t\"paymentId\": \"838a071326f1330706\",\n\t\t\t\t\"paymentStatus\": \"PAYMENT_COMPLETED\",\n\t\t\t\t\"paymentMethod\": \"CARD\",\n\t\t\t\t\"amount\": 200\n\t\t\t}\n\t\t],\n\t\t\"transactions\": [\n\t\t\t{\n\t\t\t\t\"transactionId\": \"838a071326f1333319\",\n\t\t\t\t\"merchantId\": \"8280577d677b18050e\",\n\t\t\t\t\"terminalId\": \"828057b63d8e480804\",\n\t\t\t\t\"orderId\": \"838a071326f130950b\",\n\t\t\t\t\"paymentId\": \"838a071326f1330706\",\n\t\t\t\t\"rrn\": \"526506000001\",\n\t\t\t\t\"amount\": \"200\",\n\t\t\t\t\"currency\": \"752\",\n\t\t\t\t\"method\": \"CARD\",\n\t\t\t\t\"type\": \"PURCHASE\",\n\t\t\t\t\"timestamp\": \"2025-10-08T07:25:11.144Z\",\n\t\t\t\t\"voided\": false,\n\t\t\t\t\"settlementStatus\": \"NOT_SETTLED\",\n\t\t\t\t\"truncatedPan\": \"0010\",\n\t\t\t\t\"posEntryMode\": \"07\",\n\t\t\t\t\"customerResponseCode\": \"00\",\n\t\t\t\t\"cvmMethodDescription\": \"No CVM\",\n\t\t\t\t\"authMode\": \"ISSUER\",\n\t\t\t\t\"cardBrand\": \"VISA\"\n\t\t\t}\n\t\t],\n\t\t\"orderLines\": [\n\t\t\t{\n\t\t\t\t\"id\": \"838a071326f1330707\",\n\t\t\t\t\"name\": \"Sample Product\",\n\t\t\t\t\"quantity\": 2,\n\t\t\t\t\"amount\": {\n\t\t\t\t\t\"regular\": 10000,\n\t\t\t\t\t\"total\": 20000,\n\t\t\t\t\t\"currency\": \"752\"\n\t\t\t\t},\n\t\t\t\t\"purchasePaymentId\": \"838a071326f1330706\"\n\t\t\t}\n\t\t],\n\t\t\"paymentIds\": [\n\t\t\t\"838a071326f1330706\"\n\t\t]\n\t},\n\t\"message\": \"Fetched order status successfully\"\n}" } ] } }, { "heading": "Fetch Order By Id", "new": true, "description": "Retrieves the details of an existing order using its Order Id.", "resParams": [ { "name": "status", "type": "string", "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "data", "type": "object", "description": "Contains the respective order details.", "resParams": [ { "name": "terminal$id", "type": "string", "mandatory": true, "description": "ID of the checkout or payment terminal" }, { "name": "referenceId", "type": "string", "mandatory": false, "description": "External reference ID for the order" }, { "name": "comments", "type": "string", "mandatory": false, "description": "Additional comments or notes for the order" }, { "name": "customer", "type": "object", "mandatory": false, "description": "Customer details for the order", "resParams": [ { "name": "customerId", "type": "string", "mandatory": false, "description": "Unique identifier for the customer" }, { "name": "person", "type": "object", "mandatory": false, "description": "Personal information of the customer", "resParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Person identifier." }, { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the customer", "resParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the customer" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the customer" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the customer" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Email address of the customer" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number of the customer", "resParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "birthDate", "type": "string", "mandatory": false, "description": "Date of birth in YYYY-MM-DD format" }, { "name": "personalNumber", "type": "string", "mandatory": false, "description": "Personal identification number" }, { "name": "coordinationNumber", "type": "string", "mandatory": false, "description": "Coordination number" }, { "name": "countryResidence", "type": "string", "description": "Country of residence of the customer" }, { "name": "gdNumber", "type": "string", "description": "Government-issued identification number of the customer" } ] }, { "name": "company", "type": "object", "mandatory": false, "description": "Company information for corporate purchases", "resParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Company identifier." }, { "name": "vatId", "type": "string", "mandatory": false, "description": "VAT ID of the company" }, { "name": "poDetails", "type": "string", "mandatory": false, "description": "Purchase order details for the company" }, { "name": "companyName", "type": "string", "mandatory": false, "description": "Company display name." }, { "name": "registrationNumber", "type": "string", "mandatory": false, "description": "Company registration number." }, { "name": "gln", "type": "string", "mandatory": false, "description": "GLN of the buyer's e-invoice department, used to route e-invoices." } ] } ] }, { "name": "billing", "type": "object", "mandatory": false, "description": "Billing contact and address", "resParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the billing contact", "resParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the billing contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the billing contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the billing contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Billing email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for billing", "resParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Billing address", "resParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "shipping", "type": "object", "mandatory": false, "description": "Shipping contact and address", "resParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the shipping contact", "resParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the shipping contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the shipping contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the shipping contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Recipient email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for shipping", "resParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Shipping address", "resParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "orderLines", "type": "array", "mandatory": true, "description": "List of items in the order", "resParams": [ { "name": "id", "type": "string", "mandatory": true, "description": "Order line identifier" }, { "name": "externalItemId", "type": "string", "mandatory": false, "description": "External order line identifier" }, { "name": "name", "type": "string", "mandatory": true, "description": "Product name" }, { "name": "categoryId", "type": "string", "mandatory": false, "description": "Product category identifier" }, { "name": "description", "type": "string", "mandatory": false, "description": "Line item description" }, { "name": "quantity", "type": "number", "mandatory": true, "description": "Quantity ordered. A negative value indicates a refund." }, { "name": "amount", "type": "object", "mandatory": false, "description": "Pricing details for the line item", "resParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "shipping", "type": "number", "mandatory": false, "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "total", "type": "number", "mandatory": true, "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Currency (numeric ISO 4217 as string)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Tax breakdown", "resParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Tax amount" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Tax type (e.g., VAT)" } ] } ] }, { "name": "unit", "type": "string", "mandatory": false, "description": "Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. " }, { "name": "gtin", "type": "string", "mandatory": false, "description": "Global Trade Item Number" }, { "name": "imageUrl", "type": "string", "mandatory": false, "description": "Image URL for the product" }, { "name": "brand", "type": "string", "mandatory": false, "description": "Brand name" }, { "name": "purchaseOrderId", "type": "string", "mandatory": false, "conditional": true, "description": "Mandatory purchase order identifier if it's a return item." }, { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Purchase payment identifier associated with the order line." }, { "name": "promotionApplied", "type": "string", "mandatory": false, "description": "Product promotional campaign identifier." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary metadata for the line" }, { "name": "storeId", "type": "string", "mandatory": false, "description": "Store identifier" } ] }, { "name": "totalOrderAmount", "type": "object", "mandatory": false, "description": "Total amount details of the order.", "resParams": [ { "name": "regular", "type": "number", "mandatory": true, "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)" }, { "name": "campaign", "type": "number", "mandatory": false, "description": "Total campaign or discount amount applied to the order in the smallest currency unit" }, { "name": "total", "type": "number", "mandatory": true, "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)" }, { "name": "currency", "type": "string", "mandatory": true, "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)" }, { "name": "tax", "type": "array", "mandatory": false, "description": "Order-level tax breakdown across applied tax categories", "resParams": [ { "name": "amount", "type": "number", "mandatory": true, "description": "Total tax amount for the order in the smallest currency unit" }, { "name": "percentage", "type": "number", "mandatory": true, "description": "Applied tax rate percentage" }, { "name": "type", "type": "string", "mandatory": true, "description": "Type of tax applied (e.g., VAT, GST)" } ] } ] }, { "name": "date", "type": "string", "mandatory": false, "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used." }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items" }, { "name": "adjustments", "type": "array", "mandatory": false, "description": "Order-level adjustments", "resParams": [ { "name": "type", "type": "string", "mandatory": true, "description": "Adjustment type" }, { "name": "value", "type": "number", "mandatory": true, "description": "Adjustment value" }, { "name": "metadata", "type": "object", "mandatory": false, "description": "Arbitrary key-value style metadata items." }, { "name": "adjustmentId", "type": "string", "mandatory": false, "description": "Unique identifier of the adjustment." } ] }, { "name": "controlFunctions", "type": "object", "mandatory": false, "description": "Advanced order/payment control configuration", "resParams": [ { "name": "cancelPreviousPendingOrder", "type": "boolean", "mandatory": false, "description": "Set as true when you want to cancel all previous pending orders" }, { "name": "orderLineLevelCalculation", "type": "boolean", "mandatory": false, "description": " Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false." }, { "name": "serviceProviders", "type": "array", "mandatory": false, "description": "External service providers participating in the transaction", "resParams": [ { "name": "serviceProviderId", "type": "string", "mandatory": true, "description": "Service provider identifier" }, { "name": "amount", "type": "object", "mandatory": false, "description": "Share/fee configuration", "resParams": [ { "name": "percentage", "type": "number", "mandatory": false, "description": "Percentage share" }, { "name": "fixed", "type": "number", "mandatory": false, "description": "Fixed share amount" }, { "name": "adjustmentTypes", "type": "array", "mandatory": false, "description": "Allowed adjustment types for this provider as an array of string." } ] } ] }, { "name": "initiatePaymentsOptions", "type": "object", "mandatory": false, "description": "Parameters for initiating payment", "resParams": [ { "name": "paymentMethod", "type": "string", "mandatory": false, "description": "Payment method to use" }, { "name": "amount", "type": "number", "mandatory": false, "description": "Amount to charge in smallest currency units." }, { "name": "paymentMethodParams", "type": "object", "mandatory": false, "description": "Method-specific parameters", "resParams": [ { "name": "tokenId", "type": "string", "mandatory": false, "description": "Saved payment token ID" }, { "name": "swishMode", "type": "string", "mandatory": false, "description": "Swish mode (e.g., ECOM)" }, { "name": "giftCard", "type": "object", "mandatory": false, "comingSoon": true, "description": "Gift card payment details", "resParams": [ { "name": "giftCardId", "type": "string", "mandatory": false, "description": "Gift card identifier" }, { "name": "giftCardRedemptionMode", "type": "string", "mandatory": false, "description": "Redemption mode (e.g., WALLET)" } ] }, { "name": "invoice", "type": "object", "mandatory": false, "description": "Invoice payment configuration", "resParams": [ { "name": "invoiceDistribution", "type": "string", "mandatory": false, "description": "Distribution channel (e.g., EMAIL)" }, { "name": "contractReference", "type": "string", "mandatory": false, "description": "Contract reference identifier" }, { "name": "debtCollectionEnabled", "type": "boolean", "mandatory": false, "description": "Enable debt collection" }, { "name": "dueDate", "type": "string", "mandatory": false, "description": "Due date or relative duration (e.g., 30d)" }, { "name": "invoicePaymentMethods", "type": "array", "mandatory": false, "description": "Allowed payment methods for invoice" }, { "name": "reminder", "type": "boolean", "mandatory": false, "description": "Enable reminders" } ] } ] }, { "name": "serialSplitPaymentsMode", "type": "array", "mandatory": false, "description": "An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments." }, { "name": "refundProcessingParams", "type": "object", "mandatory": false, "description": "Parameters for processing refunds", "resParams": [ { "name": "purchasePaymentId", "type": "string", "mandatory": false, "description": "Original purchase payment ID" }, { "name": "refundReason", "type": "string", "mandatory": false, "description": "Reason for refund (as provided)" }, { "name": "otherReason", "type": "string", "mandatory": false, "description": "Other reason details" } ] } ] }, { "name": "tipsMode", "type": "string", "mandatory": false, "description": "Tips configuration (STANDARD | ROUNDUP | NONE)" }, { "name": "cardStatementDescriptor", "type": "string", "mandatory": false, "description": "Statement descriptor text" }, { "name": "includeAdjustmentsForRefund", "type": "boolean", "mandatory": false, "description": "Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false." }, { "name": "lockToPaymentMethods", "type": "array", "mandatory": false, "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']" }, { "name": "tapBeforeAmount", "type": "boolean", "mandatory": false, "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment." }, { "name": "delayCapture", "type": "boolean", "mandatory": false, "description": "Allows capture at a later time. " }, { "name": "delayPayout", "type": "string", "mandatory": false, "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' ." }, { "name": "fulfillmentDate", "type": "string", "mandatory": false, "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "callBackUrl", "type": "string", "mandatory": false, "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment." }, { "name": "throwErrorIfTerminalInactiveFor", "type": "number", "mandatory": false, "description": "Threshold in ms if the respective terminal has been inactive for the given time frame." }, { "name": "clearingCutOff", "type": "string", "mandatory": false, "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)" }, { "name": "currency", "type": "string", "mandatory": false, "description": "Order currency override" }, { "name": "authMode", "type": "string", "mandatory": false, "description": "It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true." }, { "name": "receipt", "type": "object", "mandatory": false, "description": "Receipt handling options", "resParams": [ { "name": "autoPrintReceipt", "type": "boolean", "mandatory": false, "description": "Auto-print setting" }, { "name": "autoSendReceiptIfEmailAvailable", "type": "boolean", "mandatory": false, "description": "Auto-send if email present" }, { "name": "sequenceNumber", "type": "string", "mandatory": false, "description": "Receipt sequence number" }, { "name": "cashRegisterName", "type": "string", "mandatory": false, "description": "Cash register name" }, { "name": "controlUnitSerialNumber", "type": "string", "mandatory": false, "description": "Control unit serial number" }, { "name": "receiptRedirectURL", "type": "string", "mandatory": false, "description": "Receipt redirect URL" }, { "name": "cashierName", "type": "string", "mandatory": false, "description": "Cashier name" }, { "name": "promotionsToDisplay", "type": "array", "mandatory": false, "description": "Promotions to display on receipt" } ] }, { "name": "surcharges", "comingSoon": true, "mandatory": false, "type": "object", "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers.", "resParams": [ { "name": "domestic", "type": "object", "mandatory": false, "description": "Surcharges for domestic transactions (same country).", "resParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in domestic transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00)." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%)." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in domestic transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "international", "type": "object", "mandatory": false, "description": "Surcharges for international transactions (outside the merchant’s country).", "resParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in international transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in international transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] }, { "name": "eea", "type": "object", "mandatory": false, "description": "Surcharges for EEA (European Economic Area) transactions.", "resParams": [ { "name": "consumer", "type": "object", "mandatory": false, "description": "Surcharges for consumer cards in EEA transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for consumer credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] }, { "name": "corporate", "type": "object", "mandatory": false, "description": "Surcharges for corporate cards in EEA transactions.", "resParams": [ { "name": "debit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate debit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] }, { "name": "credit", "type": "object", "mandatory": false, "description": "Surcharge definitions for corporate credit cards.", "resParams": [ { "name": "fixedAmount", "type": "number", "mandatory": false, "description": "A flat surcharge amount in minor currency units." }, { "name": "fixedPercentage", "type": "number", "mandatory": false, "description": "A percentage-based surcharge." } ] } ] } ] } ] }, { "name": "readTags", "type": "string", "mandatory": false, "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,", "possibleValues": [ { "value": "NONE", "description": "This value indicates that no tags are allowed for reading." }, { "value": "SINGLE", "description": "Single read allowed for the order." }, { "value": "MULTIPLE_EDITABLE", "description": "Multiple tags can be read and edited." }, { "value": "MULTIPLE_NONEDITABLE", "description": "Multiple tags can be read, but cannot be modified." } ] }, { "name": "ecrEnabled", "type": "boolean", "mandatory": false, "description": "Whether ECR (electronic cash register) mode is enabled." }, { "name": "online", "type": "object", "mandatory": false, "description": "Online payment/link settings", "resParams": [ { "name": "enforceTokenization", "type": "boolean", "mandatory": false, "description": "Denotes whether the card is tokenised for a future transaction or not." }, { "name": "paymentPageValidFor", "type": "string", "mandatory": false, "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d')." }, { "name": "enforce3DSecure", "type": "boolean", "mandatory": false, "description": "Force 3-D Secure authentication when available." }, { "name": "relaxed3ds", "type": "boolean", "mandatory": false, "description": "Allow relaxed 3-D Secure handling." }, { "name": "addressRequirements", "type": "boolean", "mandatory": false, "description": "Require an address on the payment page." }, { "name": "redirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter." }, { "name": "accountNameVerification", "type": "string", "mandatory": false, "description": "Account-name verification mode applied during the payment." }, { "name": "errorIfTokenizationFails", "type": "boolean", "mandatory": false, "description": "If true, fail the flow when card tokenization cannot be completed." }, { "name": "failureRedirectUrl", "type": "string", "mandatory": false, "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter." }, { "name": "tokenisationIfPossible", "type": "boolean", "mandatory": false, "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable." }, { "name": "subscription", "type": "boolean", "mandatory": false, "description": "Marks this as a subscription/recurring-capable order." }, { "name": "payButtonType", "type": "string", "mandatory": false, "description": "UI pay button label/type used on the payment page.", "possibleValues": [ { "value": "ADD_MONEY", "description": "Add money to balance" }, { "value": "BOOK", "description": "Book a service" }, { "value": "CHECKOUT", "description": "Standard checkout" }, { "value": "CONTINUE", "description": "Continue flow" }, { "value": "CONTRIBUTE", "description": "Contribute to a cause" }, { "value": "DONATE", "description": "Donate money" }, { "value": "ORDER", "description": "Place an order" }, { "value": "PAY", "description": "Pay now" }, { "value": "RENT", "description": "Rent item/service" }, { "value": "SUPPORT", "description": "Support a creator/cause" }, { "value": "TIP", "description": "Leave a tip" }, { "value": "TOP_UP", "description": "Top up balance" } ] }, { "name": "generateShortLink", "type": "boolean", "mandatory": false, "description": "If true, generates a short URL for the payment page. Default is false." }, { "name": "generateOnlineLinkWith", "type": "string", "mandatory": false, "description": "The terminal identifier used to generate the online payment link." }, { "name": "recurring", "mandatory": false, "type": "object", "description": "Encompasses all controls related to recurring payments.", "resParams": [ { "name": "subscriptionAmountType", "type": "string", "description": "Determines the type of the subscription amount for order.", "mandatory": false, "possibleValues": [ { "value": "fixed", "description": "A fixed amount is collected." }, { "value": "variable", "description": "A variable amount is collected." } ] }, { "name": "maxAmount", "type": "number", "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "mandatory": false }, { "name": "frequency", "type": "string", "conditional": true, "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'.", "mandatory": true }, { "name": "numberOfPayments", "type": "number", "description": "Total number of payments expected for this order.", "mandatory": false }, { "name": "uniqueReference", "type": "string", "description": "A unique reference for the recurring order.", "mandatory": false }, { "name": "validation", "type": "string", "conditional": true, "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'.", "mandatory": false } ] }, { "name": "currency", "type": "string", "mandatory": false, "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK." }, { "name": "selfCardCharging", "type": "boolean", "mandatory": false, "description": "Allow the customer to self-charge their card." } ] }, { "name": "taxHandlingStrategy", "type": "object", "mandatory": false, "description": "Tax calculation strategy", "resParams": [ { "name": "treatAmountAsTaxExclusive", "type": "boolean", "mandatory": false, "description": "Prices exclude tax" }, { "name": "taxTreatmentStrategy", "type": "string", "mandatory": false, "description": "Rounding strategy configuration" } ] } ] } ] }, { "name": "message", "type": "string", "description": "A message that describes the status of the request." } ], "method": "GET", "path": "/orders/:orderId", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 201, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"terminal$id\": \"8386af3b0f71b80b04\",\n\t\t\"referenceId\": \"838f324b016d7009\",\n\t\t\"date\": \"2025-10-14T07:39:02.812Z\",\n\t\t\"adjustments\": [\n\t\t\t{\n\t\t\t\t\"adjustmentId\": \"838f324b016d703e36\",\n\t\t\t\t\"type\": \"TIPS\",\n\t\t\t\t\"value\": 100\n\t\t\t}\n\t\t],\n\t\t\"orderLines\": [\n\t\t\t{\n\t\t\t\t\"id\": \"TERM123NAL\",\n\t\t\t\t\"name\": \"Nike Shoes\",\n\t\t\t\t\"quantity\": 1,\n\t\t\t\t\"amount\": {\n\t\t\t\t\t\"regular\": 500,\n\t\t\t\t\t\"total\": 500,\n\t\t\t\t\t\"currency\": \"752\",\n\t\t\t\t\t\"tax\": [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\"amount\": 20,\n\t\t\t\t\t\t\t\"percentage\": 20,\n\t\t\t\t\t\t\t\"type\": \"VAT\"\n\t\t\t\t\t\t}\n\t\t\t\t\t]\n\t\t\t\t}\n\t\t\t}\n\t\t],\n\t\t\"totalOrderAmount\": {\n\t\t\t\"regular\": 500,\n\t\t\t\"total\": 600,\n\t\t\t\"currency\": \"752\"\n\t\t},\n\t\t\"controlFunctions\": {\n\t\t\t\"cancelPreviousPendingOrder\": false,\n\t\t\t\"orderLineLevelCalculation\": false\n\t\t}\n\t},\n\t\"message\": \"Order fetched successfully\"\n}" }, { "code": 401, "response": "\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}" } ] } }, { "heading": "Update Customer Details", "new": true, "description": "Replaces the customer, billing and shipping contact details on an existing order. Use this API to set or correct who the order is for and where it is billed and shipped, identified by the Order ID in the URL.", "reqParams": [ { "name": "customer", "type": "object", "mandatory": false, "description": "Customer details for the order", "reqParams": [ { "name": "customerId", "type": "string", "mandatory": false, "description": "Unique identifier for the customer" }, { "name": "person", "type": "object", "mandatory": false, "description": "Personal information of the customer", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Person identifier." }, { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the customer", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the customer" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the customer" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the customer" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Email address of the customer" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number of the customer", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "birthDate", "type": "string", "mandatory": false, "description": "Date of birth in YYYY-MM-DD format" }, { "name": "personalNumber", "type": "string", "mandatory": false, "description": "Personal identification number" }, { "name": "coordinationNumber", "type": "string", "mandatory": false, "description": "Coordination number" }, { "name": "countryResidence", "type": "string", "description": "Country of residence of the customer" }, { "name": "gdNumber", "type": "string", "description": "Government-issued identification number of the customer" } ] }, { "name": "company", "type": "object", "mandatory": false, "description": "Company information for corporate purchases", "reqParams": [ { "name": "id", "type": "string", "mandatory": false, "description": "Company identifier." }, { "name": "vatId", "type": "string", "mandatory": false, "description": "VAT ID of the company" }, { "name": "poDetails", "type": "string", "mandatory": false, "description": "Purchase order details for the company" }, { "name": "companyName", "type": "string", "mandatory": false, "description": "Company display name." }, { "name": "registrationNumber", "type": "string", "mandatory": false, "description": "Company registration number." }, { "name": "gln", "type": "string", "mandatory": false, "description": "GLN of the buyer's e-invoice department, used to route e-invoices." } ] } ] }, { "name": "billing", "type": "object", "mandatory": false, "description": "Billing contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the billing contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the billing contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the billing contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the billing contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Billing email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for billing", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Billing address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] }, { "name": "shipping", "type": "object", "mandatory": false, "description": "Shipping contact and address", "reqParams": [ { "name": "name", "type": "object", "mandatory": false, "description": "Full name of the shipping contact", "reqParams": [ { "name": "firstName", "type": "string", "mandatory": false, "description": "First name of the shipping contact" }, { "name": "middleName", "type": "string", "mandatory": false, "description": "Middle name of the shipping contact" }, { "name": "lastName", "type": "string", "mandatory": false, "description": "Last name of the shipping contact" } ] }, { "name": "email", "type": "string", "mandatory": false, "description": "Recipient email" }, { "name": "phoneNumber", "type": "object", "mandatory": false, "description": "Phone number for shipping", "reqParams": [ { "name": "code", "type": "string", "mandatory": true, "description": "International dialing code (Eg., 46 for Sweden without '+')" }, { "name": "number", "type": "string", "mandatory": true, "description": "National subscriber number (digits only)" } ] }, { "name": "address", "type": "object", "mandatory": false, "description": "Shipping address", "reqParams": [ { "name": "careOf", "type": "string", "mandatory": false, "description": "Care of / attention" }, { "name": "addressLine1", "type": "string", "mandatory": true, "description": "Primary address line" }, { "name": "addressLine2", "type": "string", "mandatory": false, "description": "Address line 2" }, { "name": "addressLine3", "type": "string", "mandatory": false, "description": "Address line 3" }, { "name": "city", "type": "string", "mandatory": true, "description": "City name" }, { "name": "postalCode", "type": "string", "mandatory": true, "description": "Postal/ZIP code" }, { "name": "countryCode", "type": "string", "mandatory": true, "description": "Country code (ISO 3166-1 alpha-2)" } ] } ] } ], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "data", "type": "object", "description": "Updated customer, billing and shipping details returned by the service." }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "PUT", "path": "/orders/:orderId/customer", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ], "body": "{\n \"customer\": {\n \"customerId\": \"825a37d0aa1048120e\",\n \"person\": {\n \"name\": {\n \"firstName\": \"Tom\",\n \"middleName\": \"A\",\n \"lastName\": \"Andersson\"\n },\n \"email\": \"tom.andersson@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"birthDate\": \"1990-05-14\",\n \"personalNumber\": \"199005141234\",\n \"coordinationNumber\": \"199005741234\",\n \"countryResidence\": \"SE\",\n \"gdNumber\": \"GD123456\"\n },\n \"company\": {\n \"vatId\": \"SE556677889901\",\n \"poDetails\": \"PO-2024-0098\"\n }\n },\n \"billing\": {\n \"name\": {\n \"firstName\": \"Tom\",\n \"middleName\": \"A\",\n \"lastName\": \"Andersson\"\n },\n \"email\": \"tom.andersson@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"address\": {\n \"careOf\": \"c/o Reception\",\n \"addressLine1\": \"Storgatan 1\",\n \"addressLine2\": \"Floor 2\",\n \"addressLine3\": \"Door 4\",\n \"city\": \"Stockholm\",\n \"postalCode\": \"11122\",\n \"countryCode\": \"SE\"\n }\n },\n \"shipping\": {\n \"name\": {\n \"firstName\": \"Sam\",\n \"middleName\": \"A\",\n \"lastName\": \"Berg\"\n },\n \"email\": \"sam.berg@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"709876543\"\n },\n \"address\": {\n \"careOf\": \"c/o Reception\",\n \"addressLine1\": \"Kungsgatan 9\",\n \"addressLine2\": \"Floor 2\",\n \"addressLine3\": \"Door 4\",\n \"city\": \"Stockholm\",\n \"postalCode\": \"11122\",\n \"countryCode\": \"SE\"\n }\n }\n}" }, "response": [ { "code": 200, "response": "{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {},\n\t\"message\": \"Customer details updated successfully.\"\n}" }, { "code": 400, "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Invalid order id\"\n}" }, { "code": 401, "response": "{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Authentication failed\"\n}" } ] } }, { "heading": "Cancel an Order", "description": "Cancels a specific order. Use this API to cancel any created order using its Order ID. However, you cannot cancel orders that are already completed.", "reqParams": [], "resParams": [ { "name": "status", "type": "string", "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'." }, { "name": "message", "type": "string", "description": "A message that describes the status of the request." } ], "method": "DELETE", "path": "/orders/:orderId", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Order cancelled successfully\"\n}" } ] } }, { "heading": "Add Receipt Information", "description": "This API allows you to store cash register details for receipts.", "reqParams": [ { "name": "merchantId", "type": "string", "mandatory": false, "description": "Merchant the receipt belongs to." }, { "name": "sequenceNumber", "type": "string", "mandatory": false, "description": "Receipt sequence number." }, { "name": "cashRegisterName", "type": "string", "mandatory": false, "description": "Name of the cash register." }, { "name": "controlUnitSerialNumber", "type": "string", "mandatory": false, "description": "Serial number of the fiscal control unit." }, { "name": "cashierName", "type": "string", "mandatory": false, "description": "Name of the cashier." }, { "name": "customerName", "type": "string", "mandatory": false, "description": "Name of the customer on the receipt." } ], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request 'SUCCESS' | 'ERROR'." }, { "name": "message", "type": "string", "mandatory": true, "description": "Status message of the request is displayed." } ], "method": "PUT", "path": "/orders/:orderId/receipt", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ], "body": "{\n \"merchantId\": \"825a376eeed1200600\",\n \"sequenceNumber\": \"1234567\",\n \"cashRegisterName\": \"Test\",\n \"controlUnitSerialNumber\": \"1234567\",\n \"cashierName\": \"Amanda\",\n \"customerName\": \"Tom\"\n}" }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Receipt data updated successfully.\"\n}" } ] } }, { "heading": "Fetch Order Adjustments", "pagination": true, "description": "Fetch all adjustments created under an order.", "query": "To fetch adjustments made under a certain date range send in startDate and endDate as query params", "reqParams": [ { "name": "startDate", "type": "string", "mandatory": false, "description": "Start of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when endDate is also sent." }, { "name": "endDate", "type": "string", "mandatory": false, "description": "End of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when startDate is also sent." } ], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request." }, { "name": "data", "type": "array", "description": "Response data.", "resParams": [ { "name": "adjustmentId", "type": "string", "description": "Adjustment ID of the adjustment." }, { "name": "transactionId", "type": "string", "description": "Transaction the adjustment is associated with." }, { "name": "orderId", "type": "string", "description": "Order the adjustment belongs to." }, { "name": "adjustmentType", "type": "string", "description": "Type of the adjustment" }, { "name": "amount", "type": "number", "description": "Amount of the adjustment." }, { "name": "currency", "type": "string", "description": "Currency of the adjustment amount." }, { "name": "metadata", "type": "object", "description": "Free-form metadata for the adjustment." }, { "name": "createdAt", "type": "string", "description": "Timestamp when the adjustment was created." } ] }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "GET", "path": "/orders/:orderId/adjustments", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": [\n\t\t{\n\t\t\t\"adjustmentId\": \"81efdbe975ebc800ff\",\n\t\t\t\"transactionId\": \"8267defa6150700b48\",\n\t\t\t\"orderId\": \"82674cfdf77f500001\",\n\t\t\t\"adjustmentType\": \"tips\",\n\t\t\t\"amount\": 100,\n\t\t\t\"currency\": \"SEK\",\n\t\t\t\"metadata\": {},\n\t\t\t\"createdAt\": \"2026-06-22T07:39:02.812Z\"\n\t\t}\n\t],\n\t\"message\": \"Adjustments fetched successfully\"\n}" } ] } }, { "heading": "Fetch Tokens from Order", "description": "Fetch all tokenized card information collected for online orders.", "reqParams": [], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request." }, { "name": "data", "type": "array", "description": "Response data.", "resParams": [ { "name": "cardBrand", "type": "string", "description": "Denotes the brand of the card. E.g. VISA, MASTERCARD, AMEX." }, { "name": "cardholderName", "type": "string", "description": "Name of the card holder." }, { "name": "tokenId", "type": "string", "description": "Tokenized card information." }, { "name": "createdAt", "type": "string", "description": "Date of tokenization in ISO string format." }, { "name": "expiryMonth", "type": "number", "description": "Expiration month of the card." }, { "name": "expiryYear", "type": "number", "description": "Expiration year of the card." }, { "name": "truncatedPan", "type": "string", "description": "The last four digits of the PAN (Primary Account Number) from the card." }, { "name": "cardArt", "type": "string", "description": "Denotes the visual images of the card. Eg., VISA, MASTERCARD, AMEX." } ] }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "GET", "path": "/orders/:orderId/tokens", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": [\n\t\t{\n\t\t\t\"cardBrand\": \"VISA\",\n\t\t\t\"cardholderName\": \"Tom\",\n\t\t\t\"tokenId\": \"822d544dc48c200308\",\n\t\t\t\"createdAt\": \"2024-04-25T11:22:24.845Z\",\n\t\t\t\"expiryMonth\": 7,\n\t\t\t\"expiryYear\": 2026,\n\t\t\t\"truncatedPan\": \"8907\",\n\t\t\t\"cardArt\":\"iVBORw0KGgoAAAANSUhEUgAAAUQAAA......\"\n\t\t},\n\t\t{\n\t\t\t\"cardBrand\": \"VISA\",\n\t\t\t\"cardholderName\": \"Sam\",\n\t\t\t\"tokenId\": \"822d544dc48c200308\",\n\t\t\t\"createdAt\": \"2024-04-25T11:22:24.845Z\",\n\t\t\t\"expiryMonth\": 5,\n\t\t\t\"expiryYear\": 2025,\n\t\t\t\"truncatedPan\": \"0987\",\n\t\t\t\"cardArt\":\"YAAAAAXNSR0IArs4c6QAAAARnQU1BA......\"\n\t\t}\n\t],\n\t\"message\": \"Fetched the card information.\"\n}" } ] } }, { "heading": "Fetch Online Orders", "description": "This API retrieves a list of all online orders created under a terminal.", "reqParams": [], "resParams": [ { "name": "status", "type": "string", "mandatory": true, "description": "Status of the request." }, { "name": "data", "type": "array", "description": "Response data.", "resParams": [ { "name": "orderId", "type": "string", "description": "Id of the order." }, { "name": "status", "type": "string", "description": "Status of the order." }, { "name": "terminalId", "type": "string", "description": "Id of the payment terminal." }, { "name": "totalOrderAmount", "type": "string", "description": "Total order value." }, { "name": "currency", "type": "string", "description": "Type of currency." }, { "name": "paymentPageUrl", "type": "string", "description": "This is the URL of the payment page. " }, { "name": "nonceId", "type": "string", "description": "Single-use identifier issued for the order's online payment session." } ] }, { "name": "message", "type": "string", "mandatory": true, "description": "A message that describes the status of the request." } ], "method": "GET", "path": "/orders/:terminalId/online", "examples": { "request": { "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "API-KEY", "value": "YOUR_API_KEY" }, { "name": "API-SECRET", "value": "YOUR_API_SECRET" }, { "name": "MERCHANT-ID", "value": "YOUR_MERCHANT_ID" } ] }, "response": [ { "code": 200, "response": "\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": [\n \t{\n \"orderId\": \"825a37cb9e2048070b\",\n \"status\": \"PENDING\",\n \"terminalId\": \"825a376eeed1200604\",\n \"totalOrderAmount\": \"450\",\n \"currency\": \"SEK\",\n \"paymentPageUrl\": \"https://pay.beta.surfboard.se/825a37cb9e2048070b?pi=w60wGmUUE-k5XN1iT1RyYo-TzaiUl8wsIyO9IEZf4KE-wmDDnl-cxJ4IWkhnCqRvuk6P1WRPDaZP23_LevN0G5JqG_hDgZI9dEn4ooF3ELZMUHiE-ocL_LGc4nT1Cbuv&add=IzNDMkEyMSB8Q0FSRA==\",\n \"nonceId\": \"825a37cd2f1048090c\"\n },\n {\n \"orderId\": \"825a37ca1e20480e0b\",\n \"status\": \"PENDING\",\n \"terminalId\": \"825a376eeed1200604\",\n \"totalOrderAmount\": \"450\",\n \"currency\": \"SEK\",\n \"paymentPageUrl\": \"https://pay.beta.surfboard.se/825a37ca1e20480e0b?pi=gav_crJ4iqayHI05XyMgNdVbTW78QmRMJGm5QFaN0vCvydZfzw8_KQ9j5dd90Yf-OLEq72cpN905QNRXGVki4jxdmvDTPoW8RTNFIC_TPqiCcV80rdpXIuR1Tw6El8PI&add=IzNDMkEyMSB8Q0FSRA==\",\n \"nonceId\": \"825a37cb6e10480f0d\"\n }\n\t],\n\t\"message\": \"Fetched online orders successfully.\"\n}" } ] } } ] }