PayTR Payment API
Official vendor OpenAPI document · agent-readyPaymentsPayment ProcessingapiKey6 EndpointsREST
For Agents
Query transaction statuses, process refunds, look up BIN details, and retrieve installment rates for Turkish payment processing.
Use for: I need to check the status of a payment in Turkey, I want to process a refund for a Turkish transaction, Get the BIN details for a card number to identify the issuing bank, Retrieve installment rates available for a specific card
Not supported: Does not handle payment page rendering, card tokenization, or subscription management - use for transaction queries, refunds, and reporting only.
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.
Install Jentic One Beta
Connect the PayTR Payment API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the PayTR 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.
1
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%2Fpaytr.com%2Fpaytr" | sh2
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%2Fpaytr.com%2Fpaytr" | sh
jentic register # connects your agent to your Jentic One instanceJentic 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 PayTR Payment API.
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
Patterns agents use PayTR Payment API for, with concrete tasks.
★ 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.
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.
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.
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.
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
6 endpoints — paytr payment api provides payment processing services for turkish merchants.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Global payment processor with broader features but no Turkish installment rate support
Choose Stripe when the merchant needs global coverage and does not require Turkish bank installment rate lookups.
FAQs
Specific to using PayTR Payment API through Jentic.
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.
GET STARTED