Ana içeriğe geç

create-payment-link

POST /api/{team}/gateway/create-payment-link

Bir ödeme linki açar. Link, kapatılana ya da son geçerlilik gününe kadar checkout_url adresindeki ödeme sayfasında tekrar tekrar ödenebilir; 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. Tutar gönderilmez: amount_type fixed (varsayılan) ise kalemlerden hesaplanır, öteki tiplerde ödeme sayfasında ödeyen tarafından belirlenir (Tutar tipleri). Akış: Ödeme Linki rehberi.

Referans tekrar edebilir

reference tekil değildir. Her create-payment-link çağrısı yeni bir link açar ve yeni bir token döndürür; aynı reference daha önce gönderilmiş olsa da. Aynı referanslı önceki linkler olduğu gibi kalır, hiçbiri değiştirilmez ve tekrarlanan referans 422 döndürmez. Var olan bir linki değiştirmek için update-payment-link/{token} kullanın; yanıttaki token'ı saklayın ve linkleri token'la eşleştirin. Ayrıntılar: Aynı referansla tekrarlanan create-* istekleri.

Ön koşullar​

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

Kimlik doğrulama​

X-Api-Key, X-Timestamp, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek​

{
  "payment_link": {
    "reference": "LNK-1",
    "description": "Atölye kaydı",
    "currency": "TRY",
    "expires_at": "2026-12-31",
    "items": [
      { "name": "Atölye kaydı", "quantity": 1, "unit_amount": "750.00", "tax_rate": "20" }
    ]
  }
}

Tutarı ödeyenin belirlediği, para birimini ödeyenin seçtiği bir link:

{
  "payment_link": {
    "description": "Bağış",
    "currency": "TRY",
    "amount_type": "predefined_and_custom",
    "item_name": "Bağış",
    "predefined_amounts": ["100.00", "250.00", "500.00"],
    "tax_rate": "0",
    "currency_type": "selectable",
    "currencies": ["USD", "EUR"],
    "emails_customer": true
  }
}

payment_link nesnesinde yalnızca aşağıdaki anahtarlar gönderilebilir; başka bir anahtar 422 döner.

AlanTipZorunluAçıklama
currencystringevetTRY, USD, EUR, GBP. currency_type selectable ise currencies listesine her zaman eklenir.
amount_typestringhayırLinkin tutarının nasıl belirlendiği: fixed, custom, predefined, predefined_and_custom. Gönderilmezse fixed. Bkz. Tutar tipleri.
itemsarrayfixed tipte evet1–100 kalem. Alanlar: Kalemler. Kalemlerin toplamı en fazla 10000000.00. amount_type custom, predefined ya da predefined_and_custom ise gönderilse de yok sayılır ve linke kalem yazılmaz.
item_namestringseçimli tiplerde evetamount_type custom, predefined ya da predefined_and_custom ise zorunlu: ödemenin tek kaleminin adı. En çok 255 karakter. fixed tipte yok sayılır.
predefined_amountsarraypredefined ve predefined_and_custom tipte evetÖdeyenin seçebileceği tutarlar: 1–10 tutar; her biri en az 0.01, en fazla 10000000.00, en çok iki ondalık, tekrarsız. Öteki tiplerde yok sayılır.
tax_ratestring | numberhayırSeçimli tiplerde ödenen tutarın KDV oranı, 0–100, en çok iki ondalık. Gönderilmezse KDV yok. fixed tipte yok sayılır; KDV kalemlerin kendi tax_rate alanından gelir.
tax_modestringhayırSeçimli tiplerde tax_rate'in tutara nasıl uygulandığı: inclusive ya da exclusive. Gönderilmezse inclusive. Bkz. Tutar tipleri.
currency_typestringhayırfixed: ödeme currency ile alınır. selectable: ödeyen currencies listesinden birini seçer. Gönderilmezse fixed. Bkz. Para birimi seçimi.
currenciesarrayselectable ise evetÖdeyenin currency dışında seçebileceği para birimleri: en az bir; TRY, USD, EUR, GBP, tekrarsız. currency_type fixed ise yok sayılır.
referencestringhayırLinkin sizin sisteminizdeki referansı. En çok 255 karakter, en az bir rakam. Gönderilmezse LINK1, LINK2 … biçiminde üretilir. Tekil değildir: aynı referansla her çağrı yeni bir link ve yeni bir token açar, önceki linkler değişmez. Linki token'la izleyin.
descriptionstringhayırAçıklama. En çok 255 karakter.
payment_provider_tokenstring (UUID)hayırLinkin ödeneceği hesap. Gönderilmezse ödeme anında ödeme hesabı seçimi uygulanır.
emails_customerbooleanhayırtrue ise linkten yapılan her başarılı ödemeden sonra ödeyene, ödeme sayfasında verdiği e-posta adresine e-posta gönderilir. Gönderilmezse false.
expires_atstringhayırLinkin ödenebileceği son gün, YYYY-MM-DD, çalışma alanının saat diliminde; bugün ya da sonrası. Gönderilmezse süresizdir.
is_activebooleanhayırLinkin ödeme alıp almadığı. Gönderilmezse true.

Tutar tipleri​

amount_typeÖdenen tutar
fixedKalemlerin toplamı. Her ödemede linkin o anki kalemleri alınır.
customÖdeyenin ödeme sayfasında yazdığı tutar: en az 0.01, en fazla 10000000.00.
predefinedpredefined_amounts listesinden ödeyenin seçtiği tutar.
predefined_and_custompredefined_amounts listesinden seçilen ya da ödeyenin yazdığı tutar.

Seçimli tiplerde (custom, predefined, predefined_and_custom) ödeme, adı item_name olan tek bir kalemden oluşur ve KDV tax_rate ile tax_mode'a göre hesaplanır:

  • inclusive: KDV ödenen tutarın içinden ayrılır. %20 ile 100.00 → 83.33 ara toplam + 16.67 KDV; çekilen tutar 100.00.
  • exclusive: KDV tutarın üstüne eklenir. %20 ile 100.00 → çekilen tutar 120.00, bunun 20.00'si KDV.

Seçimli tipteki linkin yanıtında subtotal, tax_amount ve amount null'dır; her ödemenin tutarı retrieve-link-payments ile okunur.

Para birimi seçimi​

currency_type: selectable ile ödeyen, currency ve currencies listesindeki para birimlerinden birini seçer. Yanıttaki currencies alanı currency dahil bütün listeyi döndürür. Tutarlar çevrilmez: kalem tutarları ya da ödeyenin belirlediği tutar, seçilen para biriminde aynı rakamla alınır.

SDK örnekleri​

not

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

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

$created = $client->createPaymentLink(new CreatePaymentLink(
    currency: Currency::TRY,
    items: [new Item(name: 'Atölye kaydı', unitAmount: '750.00', quantity: 1, taxRate: '20')],
    reference: 'LNK-1',
    description: 'Atölye kaydı',
    expiresAt: '2026-12-31',
));

$created->paymentLink->checkoutUrl;   // paylaşılacak adres

Tutarı ödeyenin belirlediği, para birimini ödeyenin seçtiği link (ikinci istek örneği):

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

$created = $client->createPaymentLink(new CreatePaymentLink(
    currency: Currency::TRY,
    description: 'Bağış',
    amountType: AmountType::PredefinedAndCustom,
    itemName: 'Bağış',
    predefinedAmounts: ['100.00', '250.00', '500.00'],
    taxRate: '0',
    currencyType: CurrencyType::Selectable,
    currencies: [Currency::USD, Currency::EUR],
    emailsCustomer: true,
));

$created->paymentLink->amount;       // null: tutarı ödeyen belirler
$created->paymentLink->currencies;   // [Currency::TRY, Currency::USD, Currency::EUR]

Yanıt​

{
  "result": { "successful": true, "message": null },
  "payment_link": {
    "token": "7c1e3a5b-9d2f-4b6e-8a1c-3e5f7b9d1a2c",
    "reference": "LNK-1",
    "description": "Atölye kaydı",
    "payment_provider_token": null,
    "amount_type": "fixed",
    "item_name": null,
    "predefined_amounts": null,
    "tax_rate": null,
    "tax_mode": "inclusive",
    "items": [
      { "reference": null, "name": "Atölye kaydı", "image": null, "quantity": 1, "unit_amount": "750.00", "tax_rate": "20.00" }
    ],
    "subtotal": "625.00",
    "tax_amount": "125.00",
    "amount": "750.00",
    "currency": "TRY",
    "currency_type": "fixed",
    "currencies": null,
    "emails_customer": false,
    "is_active": true,
    "is_test": false,
    "expires_at": "2026-12-31T20:59:59.999999Z",
    "checkout_url": "https://sandbox.odemehub.com/checkout/link/7c1e3a5b-9d2f-4b6e-8a1c-3e5f7b9d1a2c",
    "created_at": "2026-10-02T09:20:00.000000Z"
  }
}

Seçimli tipteki link (ikinci istek örneği) için payment_link:

{
  "token": "9a4d2c6e-1b3f-4e5a-8c7d-2f4b6d8e0a1c",
  "reference": "LINK7",
  "description": "Bağış",
  "payment_provider_token": null,
  "amount_type": "predefined_and_custom",
  "item_name": "Bağış",
  "predefined_amounts": ["100.00", "250.00", "500.00"],
  "tax_rate": "0.00",
  "tax_mode": "inclusive",
  "items": [],
  "subtotal": null,
  "tax_amount": null,
  "amount": null,
  "currency": "TRY",
  "currency_type": "selectable",
  "currencies": ["TRY", "USD", "EUR"],
  "emails_customer": true,
  "is_active": true,
  "is_test": false,
  "expires_at": null,
  "checkout_url": "https://sandbox.odemehub.com/checkout/link/9a4d2c6e-1b3f-4e5a-8c7d-2f4b6d8e0a1c",
  "created_at": "2026-10-02T09:25:00.000000Z"
}

Alanlar: Ödeme linki nesnesi.

HTTP durum kodları​

KodDurum
200Yeni link açıldı.
401API anahtarı ya da imza geçersiz.
403Çalışma alanı işlem yapamıyor, planı ödeme linklerini kapsamıyor ya da Link ile Ödeme modülü kapalı.
422Doğrulama hatası.
429İstek sınırı aşıldı.

Hatalar​

AlanMesaj
payment_link.referenceReferans en az bir rakam içermeli (örneğin LNK1).
payment_link.expires_atSon geçerlilik tarihi geçmiş bir gün olamaz.
payment_link.payment_provider_tokenBu ödeme hesabı ödeme sayfasından ödeme alamıyor. / Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.
payment_link.itemsEn az bir kalem gönderilmeli. / Kalemlerin toplamı en fazla 10.000.000,00 olabilir.
payment_link.items.*.unit_amount… en fazla 10.000.000,00 olabilir.
payment_link.item_nameÖdeyen tutarı seçtiğinde ödemenin kalem adı gönderilmeli.
payment_link.predefined_amountsSeçilebilecek en az bir tutar gönderilmeli.
payment_link.predefined_amounts.*… en fazla 10.000.000,00 olabilir.
payment_link.currenciesÖdeyenin seçebileceği en az bir para birimi daha gönderilmeli.