Install Jentic One Beta

Connect the Paytrail Payment API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Paytrail Payment API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpaytrail.com%2Fpaytrail" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpaytrail.com%2Fpaytrail" | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with Paytrail Payment API.

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

GET STARTED

Start building with Paytrail Payment API

Explore with Jentic One

View OpenAPI Document

Use Cases

Patterns agents use Paytrail Payment API for, with concrete tasks.

★ 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.

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.

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.

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.

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

18 endpoints — paytrail payment api provides payment processing for finnish e-commerce merchants.

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

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

Why Jentic?

What agents get from Jentic-routed access to this vendor.

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 isolation

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.

Intent-based discovery

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.

FAQs

Specific to using Paytrail Payment API through Jentic.

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.

Paytrail Payment API

Name: Paytrail Payment API
Brand: Paytrail Payment API
Availability: InStock

AI ReadinessAI-Aware (B-)60/100

See full scorecard

Official vendor OpenAPI document · agent-readyPaymentsPayment ProcessingapiKey18 EndpointsREST

For Agents

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

Use for: I need to create a payment for a Finnish online order, I want to process a refund for a completed transaction, Retrieve the available payment methods for my merchant account, Check whether a specific payment was completed

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

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.

Jentic One on Github View OpenAPI Document

Show dimension breakdown

Foundational Compliance

Base layer of spec validity and structural soundness.

Grade: A+Signals: 4

97%

Lint Results

Aggregated quality score from linter diagnostics, weighted by severity.

100%

Resolution Completeness

Percentage of `$ref` references that resolve successfully.

100%

Specification Validity

Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).

100%

Structural Integrity

Structural correctness score based on schema issues using logarithmic dampening.

Developer Experience & Jentic Compatibility

Clarity, completeness, and ingestion readiness for developers and tooling.

Grade: B-Signals: 4

Example Density

How richly the API is illustrated with examples.

100%

Example Validity

Percentage of examples that conform to their schemas.

49%

Response Coverage

Percentage of operations with complete response definitions (success, client error, server error).

100%

Tooling Readiness

Health of API ingestion, bundling, and resolution within Jentic pipelines.

AI-Readiness & Agent Experience

Semantic breadth, depth, and agent comprehension for AI systems.

Grade: D-Signals: 4

16%

Description Coverage

Coverage of descriptions across API elements.

Error Standardization

Coverage of RFC 9457 Problem Details for error responses.

100%

OperationId Quality

Coverage, uniqueness, and casing consistency of operationIds for AI inference.

50%

Summary Coverage

Coverage of summaries across operations/tags/info.

Agent Usability

Functional utility, complexity comfort, and AI orchestration readiness.

Grade: A+Signals: 1

94%

Complexity Comfort

Agent comfort level based on API operational and structural complexity.

Security

Trust, risk posture, and security compliance.

Grade: C-Signals: 1

50%

Authentication Strength

Average quality of security schemes based on authentication method strength (weakest link for OAuth2).

AI Discoverability

Findability, semantic richness, and reasoning readiness.

Grade: CSignals: 1

55%

Descriptive Richness

Clarity and depth of descriptions across API elements.

Connect the Paytrail Payment API to your agent

Capabilities

Start building with Paytrail Payment API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs

Paytrail Payment API

Jentic AI Readiness Score

Paytrail Payment API

Foundational Compliance

Lint Results

Resolution Completeness

Specification Validity

Structural Integrity

Developer Experience & Jentic Compatibility

Example Density

Example Validity

Response Coverage

Tooling Readiness

AI-Readiness & Agent Experience

Description Coverage

Error Standardization

OperationId Quality

Summary Coverage

Agent Usability

Complexity Comfort

Security

Authentication Strength

AI Discoverability

Descriptive Richness