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

# Merchantsafeunipay Payten MSU API

Jentic publishes the only available OpenAPI specification for Payten MSU API, keeping it validated and agent-ready. MerchantSafeUnipay (Payten) is a payment gateway widely used across Turkey and South-Eastern Europe for card-not-present transactions, recurring billing, and saved-card commerce. The v2 API covers session management, sale and pre-authorisation flows, voids and refunds, saved-card vault operations, and pay-by-link generation, exposing the merchant operations needed to run an end-to-end checkout from a single integration.

## For AI agents

Process card payments, manage saved cards, issue refunds, and generate pay-by-link URLs through the Payten MSU gateway.

## Scope

Does not handle accounting ledgers, tax filings, payouts to merchant bank accounts, or fraud scoring beyond gateway checks - use for card payment processing, vaulting, and pay-by-link only.

## Capabilities

- Authenticate merchants with session tokens and refresh or kill sessions during long-running operations
- Process card sales and pre-authorisations, then capture or void the held amount
- Issue full or partial refunds against a prior MSU transaction
- Vault, edit, and delete saved cards for one-click and recurring checkouts
- Generate, edit, and cancel pay-by-link URLs for invoices and remote sales
- Query historical transactions for reconciliation and dispute handling

## Use cases

### Card-Not-Present Checkout

E-commerce merchants in Turkey and the wider region can route checkout charges through Payten MSU using POST /sale for direct sales or POST /preauth followed by POST /postauth when funds need to be held before capture. The API also handles voids and refunds, so the full checkout lifecycle sits behind a single gateway integration.

Example prompt: Call POST /session to obtain a session token, then POST /sale with amount 199.90 TRY and the card token to charge a customer.

### Saved-Card Recurring Billing

Subscription businesses can vault customer cards via POST `/card/add` and charge them on a schedule with /sale calls referencing the saved card. POST `/card/edit` and POST `/card/delete` keep the vault aligned with customer changes, supporting recurring SaaS, utilities, and instalment use cases.

Example prompt: Call POST `/card/add` to vault a card, then POST /sale on the next billing date referencing that saved card.

### Pay-By-Link Invoicing

Service businesses sending invoices over WhatsApp, SMS, or email can generate hosted payment URLs via POST `/payByLink/add` and edit or cancel them through `/payByLink/edit` and `/payByLink/cancel.` Customers complete the payment on Payten-hosted pages, removing the need to host a checkout for ad hoc sales.

Example prompt: Call POST `/payByLink/add` with amount 1500 TRY and customer email to create a payment link, then send the URL to the customer.

### Reconciliation and Refund Workflows

Finance teams can use POST /query to look up the status of historical transactions and POST /refund to issue refunds against settled charges. Combined with /void for pre-capture cancellations, this supports daily reconciliation, dispute responses, and customer service refund requests.

Example prompt: Call POST /query with the original transaction reference, then POST /refund with the matching amount to refund the customer.

### Agent-Built Payment Workflows

An AI agent assembling a checkout, refund, or recurring-billing workflow can discover Payten MSU operations via Jentic's intent search, load the schema for /sale, /refund, or `/payByLink/add`, and execute the call without writing custom MSU client code or handling raw merchant credentials.

Example prompt: Search Jentic for 'process a card payment with Payten MSU', load the POST /sale schema, and execute the call with session token, amount, and card details.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/session` | Create merchant session token |
| POST | `/sale` | Process a card sale |
| POST | `/preauth` | Pre-authorize a payment |
| POST | `/postauth` | Capture a pre-authorized payment |
| POST | `/refund` | Refund a transaction |
| POST | `/card/add` | Vault a saved card |
| POST | `/payByLink/add` | Create a pay-by-link URL |
| POST | `/query` | Query historical transactions |

## Key resources

- **Session** — Create, extend, and kill merchant API sessions
- **Transactions** — Sale, pre-auth, post-auth, void, and refund operations
- **Cards** — Vault management for saved customer cards
- **Pay By Link** — Create, edit, and cancel hosted payment links
- **Query** — Look up historical transaction status and details
- **Recurring** — Recurring payment configuration
- **Customers** — Customer-level metadata for vaulted cards and recurring plans

## Why Jentic

- **Setup:** Wiring the Payten MSU API by hand means managing the MERCHANTUSER and MERCHANTPASSWORD Authorization credentials, shaping the session, sale, and pay-by-link request bodies against the msu host, and handling retries yourself. Through Jentic you install once, import the Payten MSU API from the API Directory, store the merchant credentials once, and your agent calls it.
- **Permission scoping:** The Payten MSU API takes its targets in the request body rather than as URL path resources, so scope your agent to the operations it needs: limit it to, say, POST /sale and POST `/payByLink/add`, and destructive operations such as refund or postauth stay out of reach unless you add them.
- **Credential handling:** Your MSU merchant credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a card payment' or 'create a pay-by-link', and Jentic returns the matching Payten MSU operation such as POST /sale or POST `/payByLink/add` with its request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Global card processor with broader currency and method coverage than Payten MSU
- **Adyen Checkout API** — Enterprise unified-commerce gateway covering more regions and acquirers
- **PayPal Payments API** — Wallet-led alternative for cross-border consumer payments

## FAQ

### Why is there no official OpenAPI spec for Payten MSU API?

MerchantSafeUnipay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Payten MSU API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Payten MSU API use?

Authentication uses an Authorization header carrying MERCHANTUSER and MERCHANTPASSWORD credentials, exchanged via POST /session for a session token reused on subsequent calls. Through Jentic, the merchant credentials live in the vault and the agent only ever sees a scoped Jentic token.

### Can I issue partial refunds with the Payten MSU API?

Yes. POST /refund accepts an amount that can be less than the original transaction total, so partial refunds work the same way as full refunds. Use POST /query first if you need to confirm the original charge is in a refundable state.

### What are the rate limits for the Payten MSU API?

The OpenAPI spec does not declare explicit rate limits. Payten enforces gateway-side throttling per merchant and per acquirer; recurring batch jobs should sequence calls and use POST `/session/extend` to keep a single token alive rather than re-authenticating per request.

### How do I generate a pay-by-link through Jentic?

Install the SDK with pip install jentic, search for 'create a Payten pay-by-link', load the POST `/payByLink/add` operation, and execute it with the amount, currency, and customer details. Jentic returns the hosted URL you can send to the customer.

### Does the Payten MSU API support recurring billing?

Yes. Combine POST `/card/add` to vault the customer card with scheduled POST /sale calls referencing the saved card to charge subscriptions. The Recurring tag groups operations specific to recurring plan configuration.

### Can I limit what my agent is allowed to do with the Payten MSU API?

Yes. The Payten MSU API takes its targets in the request body rather than as URL path resources, so with your self-hosted Jentic One instance you write the rules that decide which operations and credentials the agent may use. You can scope it to only the calls it needs, such as POST /sale and POST `/payByLink/add`, and destructive operations like POST /refund, POST /void, or POST /postauth stay out of reach unless you explicitly add them. Your MSU merchant credentials are injected at execution time under those same rules, so the agent can only exercise the operations you have allowed.