From 656cb8d78e40537cd64bf1547c9ee4474beb49bb Mon Sep 17 00:00:00 2001 From: MarcusM <129057892+marcusksm@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:51:53 +0000 Subject: [PATCH] platformname, callbackUrl and missing reportfields --- README.md | 17 ----------------- docs/README.md | 12 +++++++----- 2 files changed, 7 insertions(+), 22 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index 816d6ec..0000000 --- a/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Paytrail Payment API documentation - -## Developing locally - -```bash -npm install -npm run serve -``` - -Requires docsify-cli https://www.npmjs.com/package/docsify-cli - -## Run Swagger UI locally - -```bash -docker run -p 80:8080 -e SWAGGER_JSON=/docs/paytrail-api.yaml -v $PWD/docs:/docs swaggerapi/swagger-ui -open http://localhost:80/ -``` diff --git a/docs/README.md b/docs/README.md index 816d423..464fc62 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,8 @@ The signature is transmitted in the `signature` HTTP header. Signature payload c The headers are: +The headers are: + | Field | Type | Description | | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `checkout-account` | numeric | Paytrail account ID, e.g. `375917` | @@ -31,7 +33,7 @@ The headers are: | `checkout-nonce` | string | A unique value (e.g., UUID) required for each request, used to prevent replay attacks. Duplicate nonces may be rejected | | `checkout-timestamp` | string | ISO 8601 date time | | `checkout-transaction-id` | string | Paytrail transaction ID when accessing single transaction - not required for a new payment request | -| `platform-name` | string | For SaaS services, use the marketing name of the platform (for example, `shopify`). For third party eCommerce platform plugins, use the platform name and your identifier, like company name (for example, `woocommerce-yourcompany`). Platform and integrator information helps customer service to provide better assistance for the merchants using the integration. | +| `platform-name` | string | Platform and integrator information helps customer service provide better assistance to merchants using the integration.

For partners, this value is also used to calculate provisions. Paytrail calculates partners payments by this value, so it must match the identifier agreed with Paytrail exactly and consistently on every request. | The HTTP verb, nonce and timestamp are used to mitigate various replay and timing attacks. Below is an example payload passed to a HMAC function: @@ -993,7 +995,7 @@ A Shop-in-Shop aggregate merchant can also fetch its submerchant's payment repor | startDate | string |
| | Only trades created after this datetime will be included in the report. Expects date as `ISO` format. | | endDate | string |
| | Only trades created before this datetime will be included in the report. Expects date as `ISO` format. | | limit | integer |
| `50000` | Limit the amount of payments included in the report. Maximum 50000. | -| reportFields | string[] |
| all | Limit the fields that will be included in the report. Leaving this empty will include all fields. Possible values: `entryDate`, `created`, `amount`, `status`, `firstname`, `familyname`, `description`, `reference`, `paymentMethod`, `stamp`, `address`, `postcode`, `postoffice`, `country`, `checkoutReference`, `archiveNumber`, `payerName`, `settlementId`, `settlementDate`, `settlementReference`, `originalTradeReference`, `vatPercentage`, `vatAmount`, `paymentMethodFee`, `paymentMethodCommission`, `shopInShopCommission`, `shopInShopCommissionVatPercentage`, `shopInShopCommissionVatAmount`, `companyName`, `vatId`, `refunditems` and `terminalDisplayId`

**Note:** It is recommended to limit `reportFields` only to the fields that are actually needed, as new fields may be added without prior notice. | +| reportFields | string[] |
| all | Limit the fields that will be included in the report. Leaving this empty will include all fields. Possible values: `entryDate`, `created`, `amount`, `status`, `firstname`, `familyname`, `description`, `reference`, `paymentMethod`, `stamp`, `transactionid`, `address`, `postcode`, `postoffice`, `country`, `checkoutReference`, `archiveNumber`, `payerName`, `settlementId`, `settlementDate`, `settlementDueDate`, `settlementReference`, `originalTradeReference`, `vatPercentage`, `vatAmount`, `paymentMethodFee`, `paymentMethodCommission`, `shopInShopCommission`, `shopInShopCommissionVatPercentage`, `shopInShopCommissionVatAmount`, `companyName`, `vatId`, `refunditems` and `terminalDisplayId`

**Note:** It is recommended to limit `reportFields` only to the fields that are actually needed, as new fields may be added without prior notice. | | submerchant | integer |
| | Get submerchant's payment report (aggregate only) | | includeItems | boolean |
| false | Include trade items in generated report. Only applicable when requestType is set to `json` | @@ -1073,7 +1075,7 @@ Example of the refunditems serialised into CSV | ------------ | -------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | requestType | string |
x
| | In which format will the response be delivered in, currently supported are `json` and `csv`. | | callbackUrl | string |
x
| | The url the system will send the report to as a `POST` request. Callback URLs must use HTTPS. | -| reportFields | string[] |
| all | Limit the fields that will be included in the report. Leaving this empty will include all fields. Possible values: `entryDate`, `created`, `amount`, `status`, `firstname`, `familyname`, `description`, `reference`, `paymentMethod`, `stamp`, `address`, `postcode`, `postoffice`, `country`, `checkoutReference`, `archiveNumber`, `payerName`, `settlementId`, `settlementDate`, `settlementReference`, `originalTradeReference`, `vatPercentage`, `vatAmount`, `paymentMethodFee`, `paymentMethodCommission`, `shopInShopCommission`, `shopInShopCommissionVatPercentage`, `shopInShopCommissionVatAmount` and `terminalDisplayId`

**Note:** It is recommended to limit `reportFields` only to the fields that are actually needed, as new fields may be added without prior notice. | +| reportFields | string[] |
| all | Limit the fields that will be included in the report. Leaving this empty will include all fields. Possible values: `entryDate`, `created`, `amount`, `status`, `firstname`, `familyname`, `description`, `reference`, `paymentMethod`, `stamp`, `transactionId`, `address`, `postcode`, `postoffice`, `country`, `checkoutReference`, `archiveNumber`, `payerName`, `settlementId`, `settlementDate`, `settlementReference`, `settlementDueDate`, `originalTradeReference`, `vatPercentage`, `vatAmount`, `paymentMethodFee`, `paymentMethodCommission`, `shopInShopCommission`, `shopInShopCommissionVatPercentage`, `shopInShopCommissionVatAmount` and `terminalDisplayId`

**Note:** It is recommended to limit `reportFields` only to the fields that are actually needed, as new fields may be added without prior notice. | | submerchant | integer |
| | Get submerchant's payment report (aggregate only) | | includeItems | boolean |
| false | Include trade items in generated report. Only applicable when requestType is set to `json` | @@ -1210,7 +1212,7 @@ General API HTTP status codes and what to expect of them. | invoicingAddress | [Address](#address) |
-
| Invoicing address | | manualInvoiceActivation | boolean |
-
| If paid with invoice payment method, the invoice will not be activated automatically immediately. Supported with Walley and Klarna. | | redirectUrls | [CallbackUrl](#callbackurl) |
x
| Where to redirect browser after a payment is paid or cancelled. A single redirect URL can have maximum of 300 characters. | -| callbackUrls | [CallbackUrl](#callbackurl) |
-
| Which url to ping after this payment is paid or cancelled. | +| callbackUrls | [CallbackUrl](#callbackurl) |
-
| Which url to ping after this payment is paid or cancelled

**Note:** If not given and payment is cancelled, `redirectUrls`is called instead | | callbackDelay | number |
-
| Callback URL polling delay in seconds. If callback URLs are given, the call can be delayed up to 900 seconds. Default: 0 | | groups | [PaymentMethodGroup](#paymentmethodgroup)[] |
-
| Instead of all enabled payment methods, return only those of given groups. It is highly recommended to use [list providers](#list-providers) before initiating the payment if filtering by group. If the payment methods are rendered in the webshop the grouping functionality can be implemented based on the `group` attribute of each returned payment instead of filtering when creating a payment. | | usePricesWithoutVat | boolean |
-
| If true, `amount` and `items.unitPrice` should be sent to API not including VAT, and final amount is calculated by Paytrail's system using the items' `unitPrice` and `vatPercentage` (with amounts rounded to closest cent). Also, when true, **items must be included** and all item unit prices must be positive. | @@ -1261,7 +1263,7 @@ These URLs must use HTTPS. | Field | Type | Required | Example | Description | | ------- | ------ | ------------------ | ------------------------------ | ---------------------------- | | success | string |
x
| https://example.org/51/success | Called on successful payment | -| cancel | string |
x
| https://example.org/51/cancel | Called on cancelled payment | +| cancel | string |
x
| https://example.org/51/cancel | Called on successful payment | ##### Commission