--- title: "Generate new transaction" method: POST path: "/api/transactions" tags: ["Transactions"] --- # Generate new transaction `POST /api/transactions` ## Request - Base URL: `https://api.payware.eu` - URL: `https://api.payware.eu/api/transactions` - Auth: HTTP bearer Creates a new transaction with QR code or barcode for payment processing. The same path with a multipart/form-data body is soundbite recognition (an audio fingerprint), answered only at https://soundbite.payware.eu (sandbox: https://soundbite-sandbox.payware.eu); api.payware.eu and sandbox.payware.eu refuse it with 421 ERR_SOUNDBITE_HOST. ## Headers - `Soundbite-Session` string - `Idempotency-Key` string ## Request body - TransactionRequest - `shippable` boolean - `deliveryAddress` DeliveryAddressDTO - `country` string - `fullName` string - `streetAddressLine1` string - `streetAddressLine2` string - `city` string - `region` string - `zipCode` string - `phoneNumber` string - `email` string - `role` string - `paymentMethod` 'A2A' | 'CARD_FUNDED' | 'BNPL' | 'INSTANT_CREDIT': Payment method chosen by customer. Used by banks when processing transactions. A2A = direct transfer (lower fee, no rewards). CARD_FUNDED = card-linked account (higher fee, rewards eligible). BNPL = buy now pay later (installments). INSTANT_CREDIT = credit line approved at purchase. - `producerPartnerId` string: partnerId of the POS terminal producer whose terminal produced this transaction. Must be a partner registered with payware and flagged as a producer; an unrecognised value is rejected. Determines the producer's revenue share and does NOT affect what the merchant is charged, which always follows the fee hierarchy. Omit it entirely when there is no producer. Not returned in any response. - `terminalId` string: Opaque identifier of the physical terminal, scoped to the producer's own estate. payware assumes no format and enforces no uniqueness; it is recorded for provenance and never affects attribution or pricing. - `terminalManufacturer` string: Device manufacturer as reported by the terminal. Recorded for provenance; a mismatch against the expected producer is surfaced in settlement review, never blocked. - `shop` string - `skipImageGeneration` boolean - `account` string - `friendlyName` string - `callbackUrl` string - `passbackParams` string - `trData` TransactionData - `amount` string - `currency` string - `reasonL1` string - `reasonL2` string - `trOptions` TransactionOptions - `type` string - `timeToLive` string - `qrOptions` QrOptions - `qrFormat` string - `qrErrorCorrection` string - `qrVersion` string - `qrBorder` string - `qrScale` string - `barOptions` BarcodeOptions - `barFormat` string - `barModuleWidth` string - `barBarHeight` string - `barFontSize` string - `barHumanReadableLocation` string - `vloginId` string ## Response `200` Transaction created successfully. A replay of an earlier call with the same Idempotency-Key carries the header Idempotent-Replayed: true. - union - TransactionResponse - `transactionId` string - `imageData` string - `initiationMethod` string - `timeToLive` integer - TransactionDTO - `transactionId` string - `initiatingId` string - `transactionType` string - `initiatedBy` string - `payerBIC` string - `payerFriendlyName` string - `payerAccount` string - `payeeBIC` string - `payeeFriendlyName` string - `payeeAccount` string - `currency` string - `amount` string: Transaction amount, as a decimal string at the smallest unit `currency` can be paid in. That is not always two decimal places - it follows the currency. Parse it as a decimal, never as a fixed-width string, and do not compare amounts as strings. - `fee` string: The fee payware calculated and will enforce at finalize, as a decimal string at the smallest unit `currency` can be paid in - the amount the institution can actually withhold. Echo it back UNCHANGED at finalize: do not recompute it from feeFixed/feeRate and do not re-round it, or the call is rejected with ERR_FEE_MISMATCH. Omitted (not zero) when the transaction carries no recorded fee; absence means unknown, not free. - `reasonL1` string - `reasonL2` string - `created` integer - `finalized` integer: Finalization moment, UNIX epoch milliseconds. Omitted for EXPIRED transactions, which are closed by the platform's expiry sweep and carry no finalization moment. - `timeToLive` integer - `status` 'ACTIVE' | 'CONFIRMED' | 'CANCELLED' | 'DECLINED' | 'FAILED' | 'EXPIRED': Transaction status. ACTIVE = awaiting payment (initial state, only status returned by GET). CONFIRMED = payment completed successfully. CANCELLED = cancelled before completion (requires statusMessage). DECLINED = payment declined by financial institution (requires statusMessage). FAILED = processing failed (requires statusMessage). EXPIRED = TTL exceeded before payment. - `statusMessage` string - `paymentMethod` 'A2A' | 'CARD_FUNDED' | 'BNPL' | 'INSTANT_CREDIT': Payment method chosen by customer. Used by banks when processing transactions. A2A = direct transfer (lower fee, no rewards). CARD_FUNDED = card-linked account (higher fee, rewards eligible). BNPL = buy now pay later (installments). INSTANT_CREDIT = credit line approved at purchase. - `passbackParams` string: Opaque string supplied by the initiating partner at creation and passed back unmodified on every response and callback for this transaction. payware never interprets it. - `payeeAmount` string - `payeeCurrencyCode` string - `payerAmount` string - `payerCurrencyCode` string - `feeFixed` string: Fixed fee component of the fee configuration stored on this transaction, in the transaction currency, at full stored precision. INFORMATIONAL - for reconciliation and for showing the merchant how the fee arose. Do not compute the fee from it: MAX(feeFixed, amount * feeRate) is the unrounded intermediate, and submitting that value at finalize is rejected with ERR_FEE_MISMATCH. The value to submit is `fee`. - `feeRate` string: Variable rate of the fee configuration stored on this transaction, at full stored precision - up to six decimal places, e.g. "0.001250" = 0.125%. Do not assume four: rounding a negotiated rate to four places produces a different fee from the one payware enforces. INFORMATIONAL, same as feeFixed. - `product` ProductPresentationDTO: Product presentation block, present only for product-originated transactions. - `productId` string: Product reference identifier. - `type` string: Product type: ITEM or SERVICE. - `name` string: Structured product name. - `shortDescription` string: Short product description. - `longDescription` string: Long product description. - `imageUrl` string: Product image URL to display to the payer. Availability depends on merchant plan. Permitted image types: PNG, JPEG, WebP, GIF. - `imageDigest` string: SHA-256 hex digest of the image at imageUrl, pinned by payware. The institution must verify the fetched bytes against this digest before rendering and fall back to a neutral placeholder on mismatch. - `imageContentType` string: Content type of the image as observed by payware on fetch (e.g. image/png). - `imageBytes` integer: Byte length of the image as observed by payware on fetch. - `termsUrl` string: URL of the terms and conditions applying to the purchase. Availability depends on merchant plan. - `termsText` string: Inline terms and conditions text applying to the purchase. - `regularPrice` string: Product regular (pre-discount) list price, in the Transaction currency. Present only when it is higher than the Transaction amount, i.e. when there is a genuine saving to display; omitted when the amount equals or exceeds the regular price (a price schedule may set the sale price at or above the regular price). The Transaction amount and currency are authoritative and are not repeated here. For display only. - `shippable` boolean: Whether the product requires a delivery address. - `shopName` string: Merchant outlet (shop) name. - `quickPay` boolean: When true, the client application may skip the product detail screen and proceed directly to payment confirmation, provided the minimum transaction information and access to the terms in full remain available to the payer. Intended for high-speed, fixed-price scenarios such as transit gates, event entry, or toll booths. Product preview responses only. - `deliveryAddress` DeliveryAddressDTO - `country` string - `fullName` string - `streetAddressLine1` string - `streetAddressLine2` string - `city` string - `region` string - `zipCode` string - `phoneNumber` string - `email` string - `recognition` RecognitionDTO: Confidence of a soundbite recognition. Present on answers to soundbite fingerprints; a transaction preview without it is a certain answer. - `confidence` 'CERTAIN' | 'PROBABLE': CERTAIN: the ad was recognised. PROBABLE: the ad was probably recognised; ask the shopper to confirm it ("Is this the ad?") before continuing, and report the answer to POST /api/transactions/recognitions/{id}. - `id` string: Identifier of this recognition answer (UUID), used to report the shopper's confirmation. ## Other responses - `400`: Invalid request parameters, or an invalid Idempotency-Key (ERR_INVALID_IDEMPOTENCY_KEY) - `401`: Unauthorized - Invalid or missing authentication - `403`: Forbidden - the caller is authenticated but not permitted (plan or capability gate, KYC state, or tenant scope) - `404`: The referenced product does not exist or is not active - `409`: ERR_IDEMPOTENCY_KEY_IN_PROGRESS - a request with the same Idempotency-Key is still running. Retry shortly to get its response. - `422`: ERR_IDEMPOTENCY_KEY_REUSED - the Idempotency-Key was used in the last 24 hours for a request with a different body. - `429`: Too many requests - the caller exceeded its per-partner rate limit. Carries errorCode ERR_RATE_LIMIT_EXCEEDED and a Retry-After header, in seconds. The request was not processed, so the identical request is safe to retry once the window has passed. - `500`: Internal server error - `503`: ERR_RECOGNITION_BUSY - recognition is at capacity. Keep the recording and send it again after the Retry-After header's seconds; the window was not evaluated. --- [API](https://skmtc.dev/payware/apis/payware-api.md) · [All operations](https://skmtc.dev/payware/apis/payware-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payware/apis/payware-api/revisions/7b3352ca947b?raw)