# PayTR Module

https://docs.wisecp.com/en/paytr-module

Collect credit card payments through your PayTR merchant account, with installment plans, stored cards and refunds handled from the panel.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways**, open **All Modules** and click the **PayTR** card: `{admin}/modules/payment?module=PayTR`

Adding the gateway to the method list clients see is covered in [Payment Modules](https://docs.wisecp.com/en/payment-modules).

## What Is on the Screen

Two tabs. **General Settings** holds the merchant credentials, the card entry choice and the shared gateway settings. **Installment Settings** holds the rate table clients pay by.

The client pays without leaving your site, either inside the PayTR payment frame or on your own card form. The card form needs this module as the **Card Storage Module** and **Card Entry** on the Direct API. PayTR then notifies your install, the invoice becomes paid and the order is activated.

The module also stores cards for later use, charges a stored card automatically, and refunds a payment from the invoice screen. It does not open subscriptions.

## Before You Configure It

- A PayTR merchant account with its merchant ID, key and salt.
- Direct API and 2D authorisation on the account if you want the card form on your own site.
- This module selected under **Card Storage Module** in **Initial Settings**. Stored cards, automatic renewal payments and the card form on this site all need it.

## Fields

### General Settings

- **Card Entry**: Where the client types the card. **PayTR payment page (iframe)** shows the provider frame inside your page. **Card form on this site (Direct API)** uses your own form, but only while this module is the **Card Storage Module**; otherwise clients keep seeing the frame. The frame is the default.
- **Merchant ID**: The store number on your PayTR store settings page. Required.
- **Merchant Key**: The store key from the same page. It signs every request and every incoming result. Required.
- **Merchant Salt**: The store salt from the same page, used in the same signature. Required.
- **Installment Options**: Offers installment plans to clients. On by default.
- **Maximum number of installments**: The highest number of installments a client can choose, from 1 to 12. Visible while the option above is ticked.
- **Test Mode**: Runs the module against the PayTR test environment. Off by default.
- **Debug Mode**: This option has no effect in the current version. The debug flag PayTR actually receives is a separate setting the panel does not edit, so ticking this box changes nothing.

**Status**, **Commission Rate (%)**, **Converting Currency**, **Accepted Amount Range** and the country lists work the same way in every gateway. See [Payment Modules](https://docs.wisecp.com/en/payment-modules). **Callback URL**, **Success URL** and **Failed URL** cannot be edited: copy them with the icon at the end of the field.

### Installment Settings

A rate table with one column per card family and one row per installment count, from two to twelve. Each box holds the percentage added to the total for that plan.

The table is read only with the card form on this site. With the payment frame, PayTR applies the rates set in your PayTR store panel. Only **Installment Options** and **Maximum number of installments** reach PayTR.

- An empty box turns that plan off for that card family.
- A box holding `0` offers the plan without an installment charge.
- The refresh button above the table pulls the current rates from PayTR.

## Tasks

### Enter the merchant credentials

1. In your PayTR merchant panel open **Destek & Kurulum** and go to the **Bilgi** page. Only the main user and the technical user reach it.
2. Open the module card and tick **Status**. The other fields stay locked until you do.
3. On **General Settings** copy **Mağaza No** into **Merchant ID**, **Mağaza Parola** into **Merchant Key** and **Mağaza Gizli Anahtar** into **Merchant Salt**. Then choose the **Card Entry** you are authorised for.
4. Click **Save Changes**. Clients who pick this method now reach the card step.

### Register the notification address at PayTR

1. Copy **Callback URL** from the module card.
2. In the PayTR merchant panel open **Ayarlar** under **Destek & Kurulum**, then find **Bildirim URL Ayarı**.
3. Click **Değiştir**, write the address you copied and save it. Pick the HTTPS form when your site has an SSL certificate.
4. Payments now close their invoice on their own. A result signed with the wrong key is refused, so update the address after any key change.

### Set the installment plans

1. Tick **Installment Options** and pick a value under **Maximum number of installments**. With the payment frame PayTR needs nothing else.
2. With the card form on this site, open **Installment Settings**. Click the refresh button to pull the current rates, or type them yourself.
3. Clear the boxes of the plans you do not want to offer, then save.
4. Clients on your card form now see the plans allowed for their card. The chosen plan adds its charge to the invoice.

### What the client goes through

1. The client selects this method at checkout, on an invoice or when adding funds.
2. The client types the card, or picks a card kept earlier, and selects an installment plan when one is offered.
3. The bank verification step opens, and the client returns to your site afterwards.
4. The result closes the invoice and the service is activated.

### Refund a payment

1. Open the paid invoice: `{admin}/invoices/detail?id={invoice}`
2. Change the invoice status to **Refunded**, choose **Refund via payment gateway** as the refund method and confirm.
3. The module sends the refund to PayTR for that invoice. When PayTR turns the request down, the invoice keeps its status and the reason appears on screen.

## Things to Watch

> **The Direct API needs authorisation first**
> 
> Without Direct API and 2D authorisation, the card form fails every payment. Request them from **Destek** under **Destek & Kurulum** in your PayTR panel. These are two separate permissions, and PayTR grants each after its own review. Stay on the payment frame until they confirm.

> **An empty rate box is a closed plan**
> 
> Empty means the plan is not offered; `0` means it is offered without a charge. Clearing the whole column for a card family removes installments for those cards, while single payment stays available.

> **Test Mode does not change the credentials**
> 
> The module keeps using the merchant values you entered and only asks the test environment. Untick it before you take real payments, and check the first live payment on your PayTR account.

> **Saving a card starts with a refunded charge**
> 
> Adding a card runs a one-unit verification charge through PayTR. When the result arrives the module queues its refund a few minutes later. That refund only goes through while the cron is running. The client sees both on their statement, so mention it where you invite them to store a card.

> **PayTR may not appear by name**
> 
> As the **Card Storage Module** with **Card Entry** on the Direct API, PayTR fills the single **Credit or Debit Card** row instead of a row of its own. With the PayTR payment frame the gateway keeps its own name in the list.

## Required Privileges

**Payment Module Settings** (`MODULES_PAYMENT_SETTINGS`) is required.

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [Module Management](https://docs.wisecp.com/en/module-management)