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

# PayTR Payment API

PayTR Payment API provides payment processing services for Turkish merchants. It supports transaction status inquiries, refund processing, BIN lookups for card identification, installment rate queries, and payment reporting. The API uses HMAC-SHA256 token authentication computed from merchant credentials and handles transactions in Turkish Lira across credit and debit cards with installment support.

## For AI agents

Query transaction statuses, process refunds, look up BIN details, and retrieve installment rates for Turkish payment processing.

## Scope

Does not handle payment page rendering, card tokenization, or subscription management - use for transaction queries, refunds, and reporting only.

## Capabilities

- Query payment status and transaction details by merchant order ID
- Process full and partial refunds for completed transactions
- Look up BIN details to identify card issuer, type, and brand
- Retrieve available installment rates by card BIN for Turkish banks
- Generate payment detail reports for reconciliation
- Export bulk payment data for accounting and settlement tracking

## Use cases

### Transaction Status Monitoring

Check the real-time status of payments processed through PayTR. Merchants query the status endpoint with their merchant order ID to confirm whether a payment succeeded, failed, or is pending. This is critical for order fulfillment systems that need to verify payment completion before shipping goods or activating services in the Turkish e-commerce market.

Example prompt: Query the payment status for merchant order ID 'ORDER-2024-5678' via POST `/odeme/durum-sorgu` and return the transaction status and amount

### Refund Processing

Issue refunds for completed PayTR transactions. The API supports full and partial refunds via POST `/odeme/iade` with the original transaction reference and refund amount. Refunds are processed back to the original payment method and appear on the customer's statement within 5-10 business days depending on the issuing bank.

Example prompt: Submit a partial refund of 150 TRY for merchant order ID 'ORDER-2024-1234' via POST `/odeme/iade` and confirm the refund status

### Installment Rate Lookup

Retrieve available installment options for Turkish bank cards before checkout. The API returns installment rates (2, 3, 6, 9, 12 months) with associated commission percentages based on the card BIN. This enables merchants to display accurate installment pricing to customers at checkout, a common expectation in Turkish e-commerce.

Example prompt: Look up available installment rates for BIN 454360 via POST `/odeme/taksit-oranlari` and return the available month options with commission rates

### AI Agent Payment Operations via Jentic

AI agents use the PayTR API through Jentic to check transaction statuses, process refunds, and look up card details for Turkish merchants. Agents search by intent, receive typed schemas with HMAC token generation handled by Jentic, and execute calls without managing the complex token computation from merchant_id, merchant_key, and merchant_salt.

Example prompt: Search Jentic for 'check PayTR transaction status', load the schema for POST `/odeme/durum-sorgu`, and execute with merchant_oid 'ORDER-2024-9999'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/odeme/durum-sorgu` | Query transaction status by merchant order ID |
| POST | `/odeme/iade` | Process a full or partial refund |
| POST | `/odeme/api/bin-detail` | Look up BIN details for card identification |
| POST | `/odeme/taksit-oranlari` | Retrieve installment rates by card BIN |
| POST | `/rapor/odeme-detayi/` | Get payment detail report |
| POST | `/rapor/odeme-dokumu/` | Export bulk payment data |

## Key resources

- **Status Inquiries** — Query payment status and transaction details by order reference
- **Refunds** — Process full and partial refunds for settled transactions
- **BIN Lookups** — Identify card issuer, type, and brand from BIN prefix
- **Installment Rates** — Retrieve available installment options by card BIN
- **Reports** — Generate payment detail and settlement reports

## Why Jentic

- **Setup:** Wiring the PayTR Payment API by hand means computing the HMAC-SHA256 paytr_token from your merchant_id, merchant_key, and merchant_salt for every request and handling its Turkish-named endpoints yourself. Through Jentic you install once, import PayTR from the API Directory, store the merchant credentials once, and your agent calls it.
- **Permission scoping:** PayTR carries its payment and report details in the request body, so scope the agent by the operations it needs, such as checking payment status or reading a payment detail report. You choose that set, so operations like refund are not included unless you add them.
- **Credential handling:** Your PayTR merchant credentials are stored once, encrypted, by your own Jentic One instance, which computes the required paytr_token and injects it at execution time. The raw signing material never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a payment status in Turkey' or 'issue a refund', and Jentic returns the matching PayTR operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Paytrail Payment API** — Finnish payment gateway with similar payment-and-refund model but targeting Nordic markets
- **Stripe API** — Global payment processor with broader features but no Turkish installment rate support
- **PayTabs API** — MENA payment gateway serving Middle Eastern markets with similar hosted payment model

## FAQ

### What authentication does the PayTR API use?

The PayTR API uses HMAC-SHA256 token authentication. Each request requires a paytr_token computed from your merchant_id, merchant_key, merchant_salt, and request-specific parameters, then base64-encoded. Through Jentic, this token generation is handled automatically so agents never manage the raw merchant credentials.

### Can I process partial refunds with the PayTR API?

Yes. The POST `/odeme/iade` endpoint accepts a refund amount that can be less than the original transaction total. You provide the merchant order ID and the partial amount in TRY to refund back to the customer's original payment method.

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

PayTR applies per-merchant rate limits based on your integration tier. Standard integrations support up to 60 requests per minute. The reporting endpoints (payment detail and bulk export) have lower limits due to heavier processing.

### How do I look up installment rates through Jentic?

Search Jentic for 'PayTR installment rates', load the schema for POST `/odeme/taksit-oranlari`, and execute with the card BIN. Jentic computes the HMAC token automatically and returns the available installment months with their commission percentages.

### Does the PayTR API support multiple currencies?

PayTR primarily processes transactions in Turkish Lira (TRY). For international transactions, the conversion is handled at the payment page level. The API endpoints for status, refund, and reporting all return amounts in TRY.

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

Yes. Because you run Jentic One yourself, you decide which PayTR operations your agent may call and which merchant credentials it may use. You can grant read-only access, such as checking payment status via POST `/odeme/durum-sorgu` or reading a payment detail report via POST `/rapor/odeme-detayi`/, while withholding write operations. A sensitive call like issuing a refund via POST `/odeme/iade` is only available to the agent if you add it to that allowed set.