Link Oluşturma
Örneklerdeki değişkenler için: Genel Bakış ve Token
Ürün Türleri
| Portal seçeneği | metadata."magaza.product_type" | Ürün kaydı | amount_mode |
|---|---|---|---|
| Tahsilat | collection | Yok | fixed |
| Fiziksel | physical | Var, fotoğraf yüklenir | line_items |
| Dijital | digital | Var, fotoğrafsız | line_items |
Metadata Anahtarları
Değerler metin olarak gönderilir.
| Anahtar | Değer | Açıklama |
|---|---|---|
magaza.page | storefront | Zorunlu. Gönderilmezse link yine oluşur ama Mağaza sayfası açılmaz (storefront_url boş gelir) ve link magaza=true listesinde görünmez |
magaza.product_type | collection / physical / digital | Ürün türü |
magaza.display_name | metin | Sayfada görünen işletme adı |
magaza.collect_buyer_details | "true" / "false" | Alıcının ad, e-posta, telefon bilgisi istensin mi |
magaza.external_id | metin | Sipariş/ürün referansınız (yalnız Fiziksel/Dijital). İşlemde <external_id>-<oturum-id> olarak döner |
magaza.basket_id | metin | Sepet referansınız (yalnız Fiziksel/Dijital) |
Link Alanları
| Alan | Açıklama |
|---|---|
title | Ürün adı / tahsilat başlığı. Zorunlu, en fazla 200 karakter |
description | Açıklama. Fiziksel/Dijital için doldurulması önerilir |
amount_mode | fixed (Tahsilat) veya line_items (Fiziksel/Dijital) |
fixed_amount | Tahsilat tutarı, kuruş. 0'dan büyük olmalı. line_items için null |
currency | TRY |
items | Fiziksel/Dijital: [{ "product_id", "quantity_adjustable", "max_quantity" }] |
installments_disabled | true = tek çekim. false = üye işyerinin taksit seçenekleri sunulur |
payment_mode | three_d_secure |
collect_email / collect_phone | E-posta / telefon istensin mi |
collect_billing_address | Fatura adresi istensin mi |
collect_invoice_details | TCKN/VKN istensin mi (e-fatura için) |
require_terms_acceptance | Mesafeli satış sözleşmesi onayı (true önerilir) |
max_uses | Linkin kullanım sınırı: bu kadar başarılı ödemeden sonra link kapanır (is_active: false) ve sayfada "Ödeme limiti doldu" yazar. Başarısız ödemeler sayılmaz. Ödeme sayısını sayar, ürün adedini değil: 2 adetlik bir ödeme 1 kullanım düşer. Adet bazlı stok için ürün stoğunu kullanın. Boşsa sınırsız |
expires_at | Son geçerlilik zamanı. Boşsa süresiz |
success_url / cancel_url | Ödeme sonrası yönlendirme adresleri (isteğe bağlı) |
slug | Link kısaltması (isteğe bağlı). Boşsa 10 karakterlik küçük harfli bir değer üretilir; verilen değer küçük harfe çevrilir |
allow_pre_auth / collect_shipping_address / allow_promotion_codes | Bu dokümanın kapsamı dışında; örneklerdeki gibi false gönderin |
Mağaza özelliği
Mağaza özelliği üye işyeri için kapalıysa istek PV_MAGAZA_DISABLED koduyla reddedilir.
Tahsilat Linki
Ürün kaydı gerekmez; sabit tutarlı bir ödeme linki oluşturur.
curl -X POST "$API_URL/api/v1/payment-links" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-H "Content-Type: application/json" \
-d '{
"title": "Kasım ayı aidat ödemesi",
"description": null,
"amount_mode": "fixed",
"fixed_amount": 150000,
"currency": "TRY",
"installments_disabled": false,
"payment_mode": "three_d_secure",
"allow_pre_auth": false,
"collect_email": true,
"collect_phone": true,
"collect_billing_address": false,
"collect_shipping_address": false,
"collect_invoice_details": false,
"require_terms_acceptance": true,
"allow_promotion_codes": false,
"metadata": {
"magaza.page": "storefront",
"magaza.product_type": "collection",
"magaza.display_name": "Örnek İşletme",
"magaza.collect_buyer_details": "true"
}
}'Cevap (201 Created, kısaltılmış):
{
"id": "d52625bf-fb62-4c2a-a572-78a7a2d549cd",
"slug": "48ht6vcbwl",
"title": "Kasım ayı aidat ödemesi",
"amount_mode": "fixed",
"fixed_amount": 150000,
"currency": "TRY",
"allowed_installments": [1, 2, 3, 4, 6, 9, 12],
"max_uses": null,
"current_uses": 0,
"is_active": true,
"checkout_url": "https://vpos-api.stg.odeal.com/l/48ht6vcbwl",
"storefront_url": "https://vpos-api.stg.odeal.com/m/48ht6vcbwl",
"metadata": { "magaza.page": "storefront", "magaza.product_type": "collection", "...": "..." }
}Müşteriye gönderilecek adres
Müşteriye storefront_url gönderilir. id değerini linki yönetmek için saklayın.
Fiziksel Ürün Linki
Üç adımdır: ürün oluştur → fotoğraf yükle → link oluştur.
Ürün Oluşturma
curl -X POST "$API_URL/api/v1/products" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-H "Content-Type: application/json" \
-d '{
"name": "Deri Cüzdan",
"description": "El yapımı, hakiki deri cüzdan.",
"category": "ÖdeLink",
"price": 89900,
"unit": "C62",
"vat_rate": 20,
"accommodation_tax": false,
"stock_tracked": false,
"stock": 0,
"attributes": [],
"is_active": true
}'Cevap 201 Created; id değerini saklayın:
export PRODUCT_ID="<urun-id>"price kuruş cinsindendir. vat_rate gönderilmezse 0 kabul edilir.
Stok. Adet bazlı stok tutmak için stock_tracked: true ve stock: <adet> gönderin. Her başarılı ödemede satılan adet kadar düşer; ödeme sayfası müşterinin seçebileceği adedi kalan stokla sınırlar. Stok bitince ürün satılamaz (is_out_of_stock: true). Stok takibi istemiyorsanız örneklerdeki gibi stock_tracked: false gönderin.
Fotoğraf Yükleme
multipart/form-data, alan adı file. PNG, JPG veya WebP; en fazla 2 MB.
curl -X POST "$API_URL/api/v1/products/$PRODUCT_ID/images" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-F "file=@./cuzdan.jpg;type=image/jpeg"Cevap 200 OK; ürünün güncel hâlini images listesiyle birlikte döner.
Linki Oluşturma
curl -X POST "$API_URL/api/v1/payment-links" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-H "Content-Type: application/json" \
-d '{
"title": "Deri Cüzdan",
"description": "El yapımı, hakiki deri cüzdan.",
"amount_mode": "line_items",
"fixed_amount": null,
"currency": "TRY",
"items": [
{ "product_id": "'"$PRODUCT_ID"'", "quantity_adjustable": false, "max_quantity": 1 }
],
"installments_disabled": false,
"payment_mode": "three_d_secure",
"allow_pre_auth": false,
"max_uses": 25,
"collect_email": true,
"collect_phone": true,
"collect_billing_address": true,
"collect_shipping_address": false,
"collect_invoice_details": false,
"require_terms_acceptance": true,
"allow_promotion_codes": false,
"metadata": {
"magaza.page": "storefront",
"magaza.product_type": "physical",
"magaza.display_name": "Örnek İşletme",
"magaza.collect_buyer_details": "true",
"magaza.external_id": "SIP-2026-0001",
"magaza.basket_id": "SEPET-778"
}
}'Cevap 201 Created, Tahsilat linkiyle aynı biçimde. Tutar ürün fiyatından (price) alınır. max_uses linkin kaç başarılı ödeme alacağını sınırlar; adet stoğu ürün üzerinden tutulur.
Dijital Ürün Linki
Fiziksel ürünle aynıdır; fotoğraf yüklenmez ve magaza.product_type değeri digital olur.
curl -X POST "$API_URL/api/v1/products" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-H "Content-Type: application/json" \
-d '{
"name": "Online Yoga Eğitimi",
"description": "8 haftalık canlı yayın erişimi.",
"category": "ÖdeLink",
"price": 120000,
"unit": "C62",
"vat_rate": 20,
"accommodation_tax": false,
"stock_tracked": false,
"stock": 0,
"attributes": [],
"is_active": true
}'Cevaptaki id değerini saklayın:
export PRODUCT_ID="<urun-id>"curl -X POST "$API_URL/api/v1/payment-links" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO" \
-H "Content-Type: application/json" \
-d '{
"title": "Online Yoga Eğitimi",
"description": "8 haftalık canlı yayın erişimi.",
"amount_mode": "line_items",
"currency": "TRY",
"items": [
{ "product_id": "'"$PRODUCT_ID"'", "quantity_adjustable": false, "max_quantity": 1 }
],
"installments_disabled": true,
"payment_mode": "three_d_secure",
"allow_pre_auth": false,
"collect_email": true,
"collect_phone": true,
"collect_billing_address": false,
"collect_shipping_address": false,
"collect_invoice_details": true,
"require_terms_acceptance": true,
"allow_promotion_codes": false,
"metadata": {
"magaza.page": "storefront",
"magaza.product_type": "digital",
"magaza.display_name": "Örnek İşletme",
"magaza.collect_buyer_details": "true",
"magaza.external_id": "EGITIM-42"
}
}'
