Ödeme Linki

Ödeme linki, adresi bilen herkesin tekrar tekrar ödeyebildiği bir ödeme sayfasıdır: bağış, etkinlik kaydı, sabit fiyatlı hizmet. Tutar linkin kalemlerinden gelir ya da ödeme sayfasında ödeyen tarafından belirlenir; para birimi sabit ya da ödeyenin seçimine açık olabilir. Link kapatılana ya da son geçerlilik günü geçene kadar ödeme alır; her ödeme 3D Secure ile alınır. Linkte customer gönderilmez; ödeyenin bilgileri ödeme sayfasında alınır ve işlemin customer alanında döner.

1. Açma — Sunucunuz create-payment-link çağırır. Yanıt payment_link.token ve payment_link.checkout_url döner.
2. Paylaşma — checkout_url adresini müşterilerinizle paylaşırsınız.
3. İzleme — Linkten yapılan ödemeleri retrieve-link-payments ile, ödeme denemelerini retrieve-payment-links (son 50 deneme ve toplam deneme sayısı) ya da retrieve-payments ile okursunuz.
4. Kapatma — update-payment-link ile is_active: false gönderirsiniz.

Ön koşullar

• Çalışma alanının planı ödeme linklerini kapsamalı ve panelde Modüller sayfasından Link ile Ödeme modülü açılmış olmalıdır; değilse 403.
• Linkin ödeneceği hesap 3D ödeme almalıdır.

1. Açma

currency her zaman zorunludur. Varsayılan tutar tipi fixed'dir: items zorunludur, tutar kalemlerden hesaplanır ve her ödeme linkin o anki kalemleriyle alınır. Aşağıdaki örnekler fixed tipte bir link açar; tutarı ödeyenin belirlediği link için Tutar tipleri.

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

PHP

use Gurmehub\Odemehub\Enum\Currency;
use Gurmehub\Odemehub\Request\{CreatePaymentLink, Item};

$created = $client->createPaymentLink(new CreatePaymentLink(
    currency: Currency::TRY,
    items: [new Item(name: 'Bağış', unitAmount: '100.00', quantity: 1, taxRate: '0')],
    reference: 'LNK-1',
    expiresAt: '2026-12-31',
));

$linkToken = $created->paymentLink->token;     // saklayın
$created->paymentLink->checkoutUrl;            // paylaşılacak adres

Node.js

const created = await client.createPaymentLink({
    items: [{ name: 'Bağış', unitAmount: '100.00', quantity: 1, taxRate: '0' }],
    currency: 'TRY',
    reference: 'LNK-1',
    expiresAt: '2026-12-31',
});

const linkToken = created.paymentLink.token;   // saklayın
created.paymentLink.checkoutUrl;               // paylaşılacak adres

Python

from odemehub.enums import Currency
from odemehub.request import CreatePaymentLink, Item

created = client.create_payment_link(CreatePaymentLink(
    items=[Item(name="Bağış", unit_amount="100.00", quantity=1, tax_rate="0")],
    currency=Currency.TRY,
    reference="LNK-1",
    expires_at="2026-12-31",
))

link_token = created.payment_link.token   # saklayın
created.payment_link.checkout_url         # paylaşılacak adres

Java

import com.odemehub.enums.Currency;
import com.odemehub.request.CreatePaymentLink;
import com.odemehub.request.Item;
import java.util.List;

var created = client.createPaymentLink(CreatePaymentLink.builder()
    .items(List.of(Item.builder().name("Bağış").unitAmount("100.00").quantity(1).taxRate("0").build()))
    .currency(Currency.TRY)
    .reference("LNK-1")
    .expiresAt("2026-12-31")
    .build());

String linkToken = created.getPaymentLink().getToken();   // saklayın
created.getPaymentLink().getCheckoutUrl();                // paylaşılacak adres

• reference gönderilmezse LINK1, LINK2 … biçiminde üretilir. Referans tekil değildir: aynı reference ile yapılan her create-payment-link çağrısı yeni bir link ve yeni bir token açar; önceki linkler olduğu gibi kalır ve 422 dönmez. Var olan linki değiştirmek için update-payment-link kullanın. Yanıttaki token'ı saklayın ve linki token'la izleyin; retrieve-payment-links reference ile sorulduğunda o referanstaki bütün linkleri döndürür.
• expires_at çalışma alanının saat dilimindeki son gündür; yanıtta o günün sonu ISO 8601 UTC olarak döner (2026-12-31 → 2026-12-31T20:59:59.999999Z, Türkiye saati için).

Tutar tipleri

amount_type linkin tutarının nasıl belirlendiğini seçer:

amount_type	Ödenen tutar	Zorunlu alanlar
fixed (varsayılan)	Kalemlerin toplamı.	items
custom	Ödeyenin yazdığı tutar (0.01–10000000.00).	item_name
predefined	predefined_amounts listesinden seçilen tutar.	item_name, predefined_amounts (1–10)
predefined_and_custom	Listeden seçilen ya da ödeyenin yazdığı tutar.	item_name, predefined_amounts (1–10)

fixed dışındaki tiplerde items yok sayılır; ödeme, adı item_name olan tek bir kalemden oluşur. KDV tax_rate ile verilir; tax_mode: inclusive (varsayılan) KDV'yi tutarın içinden ayırır, exclusive tutarın üstüne ekler (%20 ile 100.00 → 120.00 çekilir). Bu tiplerde linkin subtotal, tax_amount ve amount alanları null'dır; her ödemenin tutarı link ödemesinde döner.

PHP

use Gurmehub\Odemehub\Enum\{AmountType, Currency};
use Gurmehub\Odemehub\Request\CreatePaymentLink;

$created = $client->createPaymentLink(new CreatePaymentLink(
    currency: Currency::TRY,
    amountType: AmountType::PredefinedAndCustom,
    itemName: 'Bağış',
    predefinedAmounts: ['100.00', '250.00', '500.00'],
));

$created->paymentLink->amount;   // null: tutarı ödeyen belirler

Node.js

const created = await client.createPaymentLink({
    currency: 'TRY',
    amountType: 'predefined_and_custom',
    itemName: 'Bağış',
    predefinedAmounts: ['100.00', '250.00', '500.00'],
});

created.paymentLink.amount;   // null: tutarı ödeyen belirler

Python

from odemehub.enums import AmountType, Currency
from odemehub.request import CreatePaymentLink

created = client.create_payment_link(CreatePaymentLink(
    currency=Currency.TRY,
    amount_type=AmountType.PREDEFINED_AND_CUSTOM,
    item_name="Bağış",
    predefined_amounts=["100.00", "250.00", "500.00"],
))

created.payment_link.amount   # None: tutarı ödeyen belirler

Java

import com.odemehub.enums.AmountType;
import com.odemehub.enums.Currency;
import com.odemehub.request.CreatePaymentLink;
import java.util.List;

var created = client.createPaymentLink(CreatePaymentLink.builder()
    .currency(Currency.TRY)
    .amountType(AmountType.PREDEFINED_AND_CUSTOM)
    .itemName("Bağış")
    .predefinedAmounts(List.of("100.00", "250.00", "500.00"))
    .build());

created.getPaymentLink().getAmount();   // null: tutarı ödeyen belirler

JSON

{
  "payment_link": {
    "currency": "TRY",
    "amount_type": "predefined_and_custom",
    "item_name": "Bağış",
    "predefined_amounts": ["100.00", "250.00", "500.00"]
  }
}

Para birimi seçimi

currency_type: selectable ve currencies (en az bir para birimi) gönderilirse ödeyen, currency ve currencies içinden birini seçer; currency listeye her zaman eklenir. Tutarlar çevrilmez: kalem tutarları ya da belirlenen tutar, seçilen para biriminde aynı rakamla alınır. Varsayılan currency_type: fixed'dir; ödeme currency ile alınır. SDK örneği: create-payment-link (ikinci örnek).

Ödeyene e-posta

emails_customer: true gönderilirse linkten yapılan her başarılı ödemeden sonra ödeyene, ödeme sayfasında verdiği e-posta adresine e-posta gönderilir. Varsayılan false'tur.

Bütün alanlar ve kurallar: create-payment-link.

2. Ödeme sayfası

checkout_url yalnızca link ödenebilirken doludur: link açık (is_active: true), son geçerlilik günü geçmemiş ve Link ile Ödeme modülü açık. Bu koşullardan biri sağlanmıyorsa yanıtta checkout_url null'dır. Linkin her ödemesi is_test değerinin gösterdiği modda alınır.

3. Ödemeleri izlemek

Linkten yapılan her ödeme bir link ödemesidir: LINKPAY1, LINKPAY2 … referanslı, kendi token'ı olan bir kayıt. Link ödemesi status: open ile açılır, bir deneme başarılı olunca paid olur; ödenen kalemleri, tutarları, uygulanan kuponu (discount), ödeyenin fatura adresini ve ödeyen işlemi taşır. Bir link ödemesinin her denemesi bir işlemdir ve işlemin reference değeri link ödemesinin referansıdır (LINKPAY1); linkin kendi referansı değildir. İşlem yanıtlarında ve payment_link.* webhook gövdelerinde payment_link.token ile birlikte link_payment.token gelir; SDK'larda linkPaymentToken (Python'da link_payment_token).

Uç	Ne döner
retrieve-link-payments	Link ödemeleri: token, LINKPAY{n} referansı ya da en fazla 7 günlük tarih aralığıyla. Her biri payment_link, kalemler, tutarlar, discount, customer ve ödeyen transaction ile döner.
retrieve-payment-links	Linkin hâli, son 50 deneme (yeniden eskiye) ve transactions_count.
retrieve-payments	LINKPAY{n} referansıyla: o link ödemesinin bütün denemeleri. Token'la: tek bir denemenin güncel hâli.

Belirli bir linkin ödemelerini listelemek için retrieve-link-payments'ı tarih aralığıyla sorgulayıp sonuçları payment_link.token alanına göre ayırın:

PHP

use Gurmehub\Odemehub\Request\RetrieveLinkPayments;

$linkPayments = $client->retrieveLinkPayments(RetrieveLinkPayments::between('2026-09-26', '2026-10-02'))->linkPayments;

foreach ($linkPayments as $linkPayment) {
    if ($linkPayment->paymentLink->token !== $linkToken || !$linkPayment->isPaid()) {
        continue;
    }

    $linkPayment->reference;            // LINKPAY1
    $linkPayment->amount;               // çekilen tutar, kupon düşülmüş
    $linkPayment->currency;             // ödenen para birimi
    $linkPayment->transaction->token;   // iade ve iptal bununla
}

Node.js

const { linkPayments } = await client.retrieveLinkPayments({ createdFrom: '2026-09-26', createdTo: '2026-10-02' });

for (const linkPayment of linkPayments) {
    if (linkPayment.paymentLink.token !== linkToken || !linkPayment.isPaid()) {
        continue;
    }

    linkPayment.reference;             // LINKPAY1
    linkPayment.amount;                // çekilen tutar, kupon düşülmüş
    linkPayment.currency;              // ödenen para birimi
    linkPayment.transaction?.token;    // iade ve iptal bununla
}

Python

from odemehub.request import RetrieveLinkPayments

link_payments = client.retrieve_link_payments(RetrieveLinkPayments(created_from="2026-09-26", created_to="2026-10-02")).link_payments

for link_payment in link_payments:
    if link_payment.payment_link.token != link_token or not link_payment.is_paid():
        continue

    link_payment.reference             # LINKPAY1
    link_payment.amount                # çekilen tutar, kupon düşülmüş
    link_payment.currency              # ödenen para birimi
    link_payment.transaction.token     # iade ve iptal bununla

Java

import com.odemehub.request.RetrieveLinkPayments;

var linkPayments = client.retrieveLinkPayments(RetrieveLinkPayments.between("2026-09-26", "2026-10-02")).getLinkPayments();

for (var linkPayment : linkPayments) {
    if (!linkPayment.getPaymentLinkToken().equals(linkToken) || !linkPayment.isPaid()) {
        continue;
    }

    linkPayment.getReference();                // LINKPAY1
    linkPayment.getAmount();                   // çekilen tutar, kupon düşülmüş
    linkPayment.getCurrency();                 // ödenen para birimi
    linkPayment.getTransaction().getToken();   // iade ve iptal bununla
}

Başarılı bir link ödemesi, işlemin token değeriyle refund-payment ve cancel-payment ile geri verilir.

4. Kapatmak, değiştirmek, yeniden açmak

PHP

use Gurmehub\Odemehub\Request\UpdatePaymentLink;

$client->updatePaymentLink(new UpdatePaymentLink(token: $linkToken, isActive: false));                            // kapat
$client->updatePaymentLink(new UpdatePaymentLink(token: $linkToken, isActive: true, expiresAt: '2027-01-31'));    // süresi geçmiş linki yeniden aç

Node.js

await client.updatePaymentLink({ token: linkToken, isActive: false });                              // kapat
await client.updatePaymentLink({ token: linkToken, isActive: true, expiresAt: '2027-01-31' });     // süresi geçmiş linki yeniden aç

Python

from odemehub.request import UpdatePaymentLink

client.update_payment_link(UpdatePaymentLink(token=link_token, is_active=False))                            # kapat
client.update_payment_link(UpdatePaymentLink(token=link_token, is_active=True, expires_at="2027-01-31"))    # süresi geçmiş linki yeniden aç

Java

import com.odemehub.request.UpdatePaymentLink;

client.updatePaymentLink(UpdatePaymentLink.builder(linkToken).isActive(false).build());                              // kapat
client.updatePaymentLink(UpdatePaymentLink.builder(linkToken).isActive(true).expiresAt("2027-01-31").build());       // süresi geçmiş linki yeniden aç

• Yalnızca gönderilen alanlar değişir; items gönderilirse kalemlerin tamamı yenilenir ve sonraki ödemeler yeni tutarla alınır.
• Link fixed tipte kalıyorsa ya da bu tipe dönüyorsa linkte kalem olmalıdır; seçimli tipten fixed'e dönen link items ile birlikte gönderilir, yoksa payment_link.items için En az bir kalem gönderilmeli. döner.
• Son geçerlilik günü geçmiş bir linke bugün ya da sonrası bir expires_at (ya da expires_at: null) göndermek linki yeniden etkinleştirir; is_active göndermek gerekmez. Yeni tarih olmadan yalnızca is_active: true 422 döner.
• Link üzerinde sonuçlanmamış bir ödeme olması değişikliği engellemez.