---
title: "Process transaction"
method: POST
path: "/api/transactions/{transactionId}"
tags: ["Transactions"]
---

# Process transaction

`POST /api/transactions/{transactionId}`

## Request

- Base URL: `https://api.payware.eu`
- URL: `https://api.payware.eu/api/transactions/{transactionId}`
- Auth: HTTP bearer

Processes an existing transaction by transaction ID with updated details

## Path parameters

- `transactionId` string, required

## Headers

- `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 processed successfully. A replay of an earlier call with the same Idempotency-Key carries the header Idempotent-Replayed: true. Processing the same transaction again, by the same partner with the same body, returns it as stored without changing it.

- TransactionResponse
  - `transactionId` string
  - `imageData` string
  - `initiationMethod` string
  - `timeToLive` integer

## Other responses

- `400`: Invalid transaction ID or request parameters, or an invalid Idempotency-Key (ERR_INVALID_IDEMPOTENCY_KEY)
- `401`: Unauthenticated - missing, malformed or expired credentials
- `403`: Forbidden - the caller is authenticated but not permitted (plan or capability gate, KYC state, or tenant scope)
- `404`: Transaction not found (ERR_MISSING_TRANSACTION), or it has expired (ERR_TRANSACTION_EXPIRED)
- `409`: ERR_ALREADY_PROCESSED - the transaction has already been processed by another partner or with a different body. The request was well formed; this is the answer to a conflicting submission, not to a bad one. Thrown by both the FI and merchant validators. Also 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 path or 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`: The transaction could not be priced: no fee configuration exists for its currency (ERR_FEE_CONFIGURATION_UNAVAILABLE), or no exchange rate was available to express the EUR fixed fee in the transaction's currency (ERR_MISSING_EXCHANGE_RATE). Both are payware-side configuration gaps - the caller did nothing wrong and the request was not applied, so retrying later is correct.

---

[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)