create-order

POST /api/{team}/gateway/create-order

Bir sipariş açar; çekim yapılmaz. Sipariş, yanıttaki order.checkout_url adresindeki ödeme sayfasında 3D Secure ile ödenir. Tutar gönderilmez: kalemlerden ve müşterinin seçtiği gönderim yönteminden hesaplanır. Akış: Sipariş Ödemesi rehberi.

Aynı referansla tekrar çağırmak

Her create-order çağrısı yeni bir sipariş ve yeni bir order.token açar; aynı reference daha önce gönderilmiş olsa da. Aynı referanslı önceki siparişler değiştirilmez; önceki sipariş ödenmiş olsa ya da üzerinde bekleyen bir ödeme bulunsa da istek 422 dönmez. Ödeme tamamlanmadıysa aynı sipariş numarasıyla yeni sipariş açıp ödeyeni yeni checkout_url adresine yönlendirebilirsiniz; var olan siparişi değiştirmek için update-order kullanılır. Yanıttaki order.token değerini saklayın: webhook'lar siparişi yalnızca token'la anar. Ayrıntılar: Aynı referansla tekrarlanan create-* istekleri.

Ön koşullar

Çalışma alanının planı siparişleri kapsamalı ve Siparişler modülü açık olmalıdır; değilse 403.
Siparişin ödeneceği hesap (gönderilen payment_provider_token ya da varsayılan hesap) 3D ödeme almalıdır; almıyorsa 422.

Kimlik doğrulama

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

İstek

{
  "order": {
    "reference": "SIP-10233",
    "success_url": "https://magazam.com/odeme/donus",
    "cancel_url": "https://magazam.com/sepet",
    "requires_shipping": true,
    "items": [
      { "reference": "SKU-1", "name": "Kulaklık", "quantity": 1, "unit_amount": "1200.00", "tax_rate": "20" }
    ]
  },
  "customer": {
    "reference": "musteri-88",
    "billing_address": {
      "firstname": "Ahmet",
      "lastname": "Yılmaz",
      "email": "[email protected]"
    }
  }
}

`order`

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

Alan	Tip	Zorunlu	Açıklama
`reference`	string	evet	Siparişin sizin sisteminizdeki referansı. En çok 255 karakter, en az bir rakam. Tekil değildir: aynı referansla her çağrı yeni sipariş açar, önceki siparişler olduğu gibi kalır (ayrıntı).
`success_url`	string	evet	Ödeme başarılı olunca dönüş POST'unun gönderileceği adres. `https` ile başlayan, herkese açık bir adres; en çok 2048 karakter. Sandbox'ta `http` ve `localhost` da kabul edilir.
`cancel_url`	string	hayır	Ödeme sayfasında geri dönüş bağlantısı olarak gösterilir. `success_url` ile aynı kurallar.
`description`	string	hayır	Açıklama. En çok 255 karakter.
`currency`	string	hayır	`TRY`, `USD`, `EUR`, `GBP`. Gönderilmezse `TRY`.
`payment_provider_token`	string (UUID)	hayır	Siparişin ödeneceği hesap. Gönderilmezse ödeme anında ödeme hesabı seçimi uygulanır.
`requires_shipping`	boolean	hayır	`true` ise ödeme sayfası gönderim adresi ister ve ödeyene, panelde Gönderim sayfasında tanımladığınız yöntemlerden o adrese gönderenleri sunar; seçilen yöntemin ücreti tutara eklenir. Gönderilmezse `false`.
`locks_customer`	boolean	hayır	`true` ise ödeme sayfası müşteri bilgisi sormaz; gönderdiğiniz bilgileri değiştirilemez şekilde gösterir ve ödemeyi onlarla yapar. Bu durumda `customer.billing_address` eksiksiz gönderilmelidir; `requires_shipping` `true` ise `customer.shipping_address` de eksiksiz olmalıdır (gönderilmezse fatura adresi kullanılır). Eksik alan varsa `422` döner. Gönderilmezse `false`.
`emails_customer`	boolean	hayır	`true` ise ödeme tamamlanınca müşteriye, fatura adresindeki e-postaya bilgilendirme e-postası gönderilir (E-postalar). Gönderilmezse `false`.
`items`	array	evet	1–100 kalem. Alanlar: Kalemler.

Kalemlerin toplamı en fazla 10000000.00 olabilir.

`customer`

İsteğe bağlı; reference, billing_address ve shipping_address alanlarının her biri de isteğe bağlıdır. Gönderilen adresler ödeme sayfasındaki formu önceden doldurur, eksikler ödeme sayfasında alınır. reference gönderildiyse sipariş ödendiğinde ödeyen, çalışma alanınızda bu referansla müşteri olarak kaydedilir ya da mevcut müşteri güncellenir; gönderilmezse müşteri kaydı açılmaz. Alanlar: customer nesnesi.

SDK örnekleri

not

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

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Request\{Address, CreateOrder, Customer, Item};

$created = $client->createOrder(new CreateOrder(
    reference: 'SIP-10233',
    successUrl: 'https://magazam.com/odeme/donus',
    items: [
        new Item(name: 'Kulaklık', unitAmount: '1200.00', quantity: 1, taxRate: '20', reference: 'SKU-1'),
    ],
    customer: new Customer(
        reference: 'musteri-88',
        billingAddress: new Address(firstname: 'Ahmet', lastname: 'Yılmaz', email: '[email protected]'),
    ),
    cancelUrl: 'https://magazam.com/sepet',
    requiresShipping: true,
));

header('Location: '.$created->order->checkoutUrl);

const created = await client.createOrder({
    reference: 'SIP-10233',
    successUrl: 'https://magazam.com/odeme/donus',
    items: [
        { name: 'Kulaklık', unitAmount: '1200.00', quantity: 1, taxRate: '20', reference: 'SKU-1' },
    ],
    customer: {
        reference: 'musteri-88',
        billingAddress: { firstname: 'Ahmet', lastname: 'Yılmaz', email: '[email protected]' },
    },
    cancelUrl: 'https://magazam.com/sepet',
    requiresShipping: true,
});

res.redirect(created.order.checkoutUrl!);

from odemehub.request import Address, CreateOrder, Customer, Item

created = client.create_order(CreateOrder(
    reference="SIP-10233",
    success_url="https://magazam.com/odeme/donus",
    items=[
        Item(name="Kulaklık", unit_amount="1200.00", quantity=1, tax_rate="20", reference="SKU-1"),
    ],
    customer=Customer(
        reference="musteri-88",
        billing_address=Address(firstname="Ahmet", lastname="Yılmaz", email="[email protected]"),
    ),
    cancel_url="https://magazam.com/sepet",
    requires_shipping=True,
))

return redirect(created.order.checkout_url)

import com.odemehub.request.Address;
import com.odemehub.request.CreateOrder;
import com.odemehub.request.Customer;
import com.odemehub.request.Item;
import java.util.List;

var created = client.createOrder(CreateOrder.builder()
    .reference("SIP-10233")
    .successUrl("https://magazam.com/odeme/donus")
    .items(List.of(
        Item.builder().name("Kulaklık").unitAmount("1200.00").quantity(1).taxRate("20").reference("SKU-1").build()
    ))
    .customer(Customer.builder()
        .reference("musteri-88")
        .billingAddress(Address.builder().firstname("Ahmet").lastname("Yılmaz").email("[email protected]").build())
        .build())
    .cancelUrl("https://magazam.com/sepet")
    .requiresShipping(true)
    .build());

return "redirect:" + created.getOrder().getCheckoutUrl();

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/create-order"
BODY='{"order":{"reference":"SIP-10233","success_url":"https://magazam.com/odeme/donus","cancel_url":"https://magazam.com/sepet","requires_shipping":true,"items":[{"reference":"SKU-1","name":"Kulaklık","quantity":1,"unit_amount":"1200.00","tax_rate":"20"}]},"customer":{"reference":"musteri-88","billing_address":{"firstname":"Ahmet","lastname":"Yılmaz","email":"[email protected]"}}}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

{
  "result": { "successful": true, "message": null },
  "order": {
    "token": "3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21",
    "reference": "SIP-10233",
    "description": null,
    "payment_provider_token": null,
    "status": "open",
    "items": [
      { "reference": "SKU-1", "name": "Kulaklık", "image": null, "quantity": 1, "unit_amount": "1200.00", "tax_rate": "20.00" }
    ],
    "shipping_method": null,
    "discount": null,
    "subtotal": "1000.00",
    "shipping_amount": "0.00",
    "tax_amount": "200.00",
    "amount": "1200.00",
    "currency": "TRY",
    "is_test": null,
    "created_at": "2026-10-02T09:12:44.000000Z",
    "checkout_url": "https://sandbox.odemehub.com/checkout/order/3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21",
    "transaction": null
  },
  "customer": {
    "reference": "musteri-88",
    "billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" },
    "shipping_address": null
  }
}

Alanlar: Sipariş nesnesi ve yanıttaki customer. Müşteri gönderilmediyse ve ödeme sayfasında henüz kimse bilgi girmediyse customer null'dır.

discount yeni açılan siparişte null'dır; kupon ödeme sayfasında uygulanır ve retrieve-orders yanıtında görünür. Kupon uygulanınca subtotal, tax_amount ve amount indirim düşülmüş değerlerdir; gönderim ücretinden indirim düşülmez. Bkz. Kupon ve discount.

HTTP durum kodları

Kod	Durum
`200`	Sipariş açıldı.
`401`	API anahtarı ya da imza geçersiz.
`403`	Çalışma alanı işlem yapamıyor, planı siparişleri kapsamıyor ya da Siparişler modülü kapalı.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.

Hatalar

Alan	Mesaj
`order.reference`	`Referans en az bir rakam içermelidir (ör. SIP1); bankaya giden sipariş numarası bu rakamlarla kurulur.`
`order.success_url`	`Başarı adresi zorunludur; ödeme sonrası müşteri oraya yönlendirilir.`
`order.success_url`, `order.cancel_url`	`Adres https ile başlayan geçerli bir adres olmalı.` / `Adres herkese açık bir adres olmalı.`
`order.payment_provider_token`	`Bu ödeme hesabı 3D ödeme almıyor.` / `Çalışma alanınızın varsayılan ödeme hesabı 3D ödeme almıyor.` / `Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.`
`order.items`	`En az bir kalem gönderilmelidir.` / `Kalemlerin toplamı en fazla 10.000.000,00 olabilir.`
`order.items.*.unit_amount`	`… en fazla 10.000.000,00 olabilir.`

Aynı referansla tekrar çağırmak​

Ön koşullar​

Kimlik doğrulama​

İstek​

order​

customer​

SDK örnekleri​

Yanıt​

HTTP durum kodları​

Hatalar​