Paytrail Payment API

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

✓ Official Vendor SpecPaymentsPayment ProcessingapiKey18 EndpointsREST

For Agents

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

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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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

GET STARTED

Start building with Paytrail Payment API

Explore with Jentic

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Paytrail merchant ID and secret key are stored encrypted in the Jentic vault. Jentic computes the HMAC signature for each request so agents never handle raw cryptographic material.

Intent-based discovery

Agents search by intent (e.g., 'create a payment in Finland') and Jentic returns matching Paytrail operations with typed schemas and automatic signature generation.

Time to first call

Direct Paytrail integration: 2-4 days for HMAC implementation, callback handling, and payment method testing. Through Jentic: under 1 hour — search, load schema, execute with automatic signing.

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.

Paytrail Payment API

Connect the Paytrail Payment API to your agent

Capabilities

Start building with Paytrail Payment API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs