canonical: https://jentic.com/apis/paytrail.com/paytrail

# Paytrail Payment API

Paytrail Payment API provides payment processing for Finnish e-commerce merchants. It supports payment creation with multiple Finnish bank and card methods, refund processing, tokenized card-on-file payments (CIT and MIT), settlement reporting, and payment provider listings. The API uses HMAC signature authentication and handles transactions in EUR for the Finnish market.

## For AI agents

Create payments, process refunds, manage tokenized cards, and retrieve settlement reports for Finnish e-commerce merchants operating in EUR.

## Scope

Does not handle accounting, inventory, or shipping logistics - use for payment collection, refunds, and settlement reporting only.

## Capabilities

- Create payment sessions with Finnish bank, card, and invoice methods
- Process full and partial refunds with email notification to customers
- Store and charge tokenized cards for customer-initiated and merchant-initiated transactions
- Retrieve available payment providers filtered by amount and merchant configuration
- Generate settlement reports with payment-level detail
- Activate invoices for deferred payment collection

## Use cases

### Finnish E-Commerce Checkout

Accept payments from Finnish consumers using their preferred bank, card, or invoice method. Paytrail creates a payment session via POST /payments with the order details, customer info, and callback URLs. The customer selects from Finnish banks (Nordea, OP, Danske), cards (Visa, Mastercard), or invoice providers (Collector, Jousto). Settlement occurs in EUR on a configurable cycle.

Example prompt: Create a payment for 49.90 EUR with stamp 'order-12345', reference '1234', and two line items via POST /payments, then return the checkout URL

### Tokenized Recurring Payments

Store customer card details securely and charge them for repeat purchases or subscriptions without the customer re-entering card data. Paytrail supports customer-initiated (CIT) and merchant-initiated (MIT) token transactions. CIT requires 3D Secure on the initial save, while MIT tokens enable background charges for subscriptions and installments.

Example prompt: Create a CIT authorization-hold for 99.00 EUR using token ID 'card_token_abc' via POST `/payments/token/cit/authorization-hold`, then commit the token

### Refund and Settlement Management

Issue refunds for completed Paytrail transactions and track settlement details. The API supports full and partial refunds via POST `/payments/{transactionId}/refund` with optional email notification to the customer. Settlement reports provide payment-level reconciliation data for accounting.

Example prompt: Process a refund of 25.00 EUR for transaction ID '12345678-abcd' via POST `/payments/{transactionId}/refund` with email notification enabled

### AI Agent Payment Operations via Jentic

AI agents use the Paytrail API through Jentic to create payments, check statuses, and process refunds for Finnish merchants. Jentic handles the HMAC signature computation from merchant ID and secret key, so agents execute payment operations without managing cryptographic signing. This enables automated order processing workflows for Finnish e-commerce.

Example prompt: Search Jentic for 'create Finnish payment', load the schema for POST /payments, and execute with order details for a 75.00 EUR purchase

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Create a new payment session |
| GET | `/payments/{transactionId}` | Retrieve payment details by transaction ID |
| POST | `/payments/{transactionId}/refund` | Process a refund for a transaction |
| POST | `/payments/token/cit/charge` | Charge a customer-initiated token |
| POST | `/payments/token/mit/charge` | Charge a merchant-initiated token |
| GET | `/merchants/payment-providers` | List available payment providers |
| GET | `/settlements` | Retrieve settlement reports |
| POST | `/tokenization/addcard-form` | Generate a card tokenization form |

## Key resources

- **Payments** — Create payment sessions and retrieve payment details
- **Refunds** — Process full and partial refunds with email notifications
- **Tokenization** — Store and charge card tokens for CIT and MIT flows
- **Payment Providers** — List available banks, cards, and invoice methods
- **Settlements** — Retrieve settlement reports and payment reconciliation data

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 60 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 42 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 55 / 100
- **View full report:** https://jentic.com/apis/paytrail.com/paytrail/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Paytrail Payment API by hand means computing the HMAC SHA256 or SHA512 signature over your checkout headers and body for every request and sequencing payment, refund, and settlement calls yourself. Through Jentic you install once, import Paytrail from the API Directory, store the merchant id and secret key once, and your agent calls it.
- **Permission scoping:** Paytrail carries its payment details in the request body and identifies a payment by transaction id in the path, so scope the agent by the operations it needs, such as creating a payment or reading one by transaction id. You choose that set, so operations like refund or token charges are not included unless you add them.
- **Credential handling:** Your Paytrail merchant id and secret key are stored once, encrypted, by your own Jentic One instance, which computes the required signature and injects it at execution time. The raw cryptographic material never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a payment in Finland' or 'read a settlement report', and Jentic returns the matching Paytrail operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Mollie API** — European payment gateway with broader country coverage but fewer Finnish bank integrations
- **Stripe API** — Global payment processor with extensive features but limited Finnish bank method support
- **PayTR Payment API** — Turkish payment gateway with installment support for a different regional market

## FAQ

### What authentication does the Paytrail Payment API use?

The Paytrail API uses HMAC SHA256 or SHA512 signature authentication. Each request includes a signature header computed over checkout-specific headers and the request body using your merchant secret key. Through Jentic, signature computation is automatic so agents do not handle raw signing keys.

### Which payment methods does the Paytrail API support?

Paytrail supports Finnish online banks (Nordea, OP, Danske Bank, S-Pankki, Aktia, and others), cards (Visa, Mastercard), mobile wallets (MobilePay, Pivo), and invoice/installment providers (Collector, Jousto). Available methods depend on your merchant configuration and can be queried via GET `/merchants/payment-providers.`

### What are the rate limits for the Paytrail API?

Paytrail applies per-merchant rate limits. Standard merchants can submit up to 300 API calls per minute. Token charge endpoints and payment creation share the same pool. Settlement and report endpoints have separate, lower limits.

### How do I create a payment through Jentic?

Search Jentic for 'create Finnish payment', load the returned schema for POST /payments, and execute with your order stamp, reference, amount in cents, currency EUR, and item details. Jentic handles the HMAC signature computation and returns the hosted checkout URL for customer redirect.

### Does Paytrail support merchant-initiated token charges?

Yes. After a customer saves their card via CIT flow with 3D Secure, you can charge the token for subsequent transactions without customer interaction using POST `/payments/token/mit/charge.` This enables subscription billing and installment payments.

### Can I issue partial refunds with the Paytrail API?

Yes. POST `/payments/{transactionId}/refund` accepts a refund amount less than the original. You specify line items being refunded and can optionally trigger an email notification to the customer with the refund details.

### Can I limit what my agent is allowed to do with the Paytrail Payment API?

Yes. Because you run Jentic One yourself, your own rules decide which Paytrail operations and credentials the agent may use, so you can grant only what a task needs, such as creating a payment with POST /payments or reading one with GET `/payments/{transactionId}.` Operations like processing a refund via POST `/payments/{transactionId}/refund` or charging a stored token via POST `/payments/token/cit/charge` and POST `/payments/token/mit/charge` stay off unless you add them to the allowed set. Your merchant id and secret key are held encrypted by your own instance, which computes the HMAC signature at execution time, so the agent never sees the raw signing material.