Ödeme sayfası oluştur. Ödemeyi doğrula.

1. Kimlikleri ve erişimi hazırla

Etkin mağaza ve test edilmiş ödeme yöntemleriyle başla. Şu bölümde: Ayarlar → API erişimiyalnızca gerekli projeyle sınırlı okuma/yazma kimlik bilgisi oluştur. Token'ı arka ucunda tut; tarayıcı koduna veya herkese açık depoya asla koyma.

Şunu kopyala: Proje API kimliği ve Mağaza API kimliği mağazanın şu bölümünden: Temel → API kimlikleri kutusu. Bunlar okunabilir proje tanımlayıcısı veya sipariş numaran değil, UUID'lerdir. Kendi API ana makine adını kullan.

Şurada: Mağaza → IPNbölümünde, şunu sağlamadan önce imzalama sırrı oluştur: ipn_url. HTTPS alıcına satıcı VPS'sinden erişilebilmelidir.

2. Fatura oluştur

Yer tutucuları değiştir ve isteği arka ucundan gönder. Tutarlar kayan nokta hesaplamaları değil, ondalık dizelerdir.

curl --fail-with-body --request POST \
  'https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices' \
  --header 'Authorization: Bearer YOUR_MERCHANT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --data '{
  "amount": "10.00",
  "currency": "EUR",
  "order_id": "order-1042",
  "description": "Example order",
  "ipn_url": "https://shop.example.com/payments/wholly-ipn",
  "metadata": {
    "cart_id": "cart-1042"
  }
}'

Kaydet: data.invoice_id siparişinle birlikte; ardından müşteriyi şuraya yönlendir: links.checkout. Yeni ödeme denemesi için benzersiz idempotency anahtarı kullan. Zaman aşımında şunlarla yeniden dene: aynı kimlik bilgisi, anahtar ve birebir aynı gövde baytları.

Şunu atlamak: payment_methods mağazanın kabul edilen yöntemlerini kullanır. Fatura başına zincir slug'ları ve sembollerle daraltabilirsin; bu hiçbir zaman kabul edilmeyen varlığı etkinleştirmez. Tüm istek alanları ve yanıt örnekleri →

3. IPN, webhook veya ikisini seç

IPN fatura yaşam döngüsünü izler. Mağazanın varsayılan IPN URL'sini ayarla veya şu alanla değiştir: ipn_url ilgili fatura için. Webhook'lar uç noktayı seçili olaylara abone eder, örneğin invoice.settled.

Aynı imza biçimini kullanırlar ancak sırları farklıdır: IPN mağazanın IPN sırrını kullanır; her webhook uç noktasının kendi sırrı vardır. Hiçbiri imzalama için API bearer token'ını kullanmaz.

İkisi de uygulamana teslim ediyorsa çakışan bildirimler bekle. Siparişi iki kez alacaklandırma.

4. Bildirimi doğrula ve kaydet

1. JSON ayrıştırmadan önce ham istek gövdesini birebir oku. Şunu doğrula: Wholly-Signature eşleşen sır ve zaman damgası/tekrar oynatma kontrolleriyle. Resmi SDK'lar doğrulayıcı sağlar.
2. İmzalı gövdenin proje, mağaza, fatura ve olay kimliğini doğrula. İmzasız teslimat başlıkları kimlik doğrulama kaynağı değildir.
3. Olayı benzersiz şu değerle kalıcı kaydet: event_id, ardından hemen HTTP 2xx döndür. Siparişleri arka plan işçisinde işle.
4. Güncel faturayı, istekte verilen keyfî ana makineden değil, yapılandırdığın API ana makinesinden getir. Kayıtlı proje, mağaza, tutar, para birimi ve sipariş referansınla karşılaştır.

PHP · Python · JavaScript / TypeScript · İmza belirtimi ve alıcı örnekleri

5. Ödeme tamamlandığında bir kez karşıla

Bir olay tabanlı alıcı için şunu işle: event_type = invoice.settled, ardından güncel şu değeri doğrula: status = settled ve istisna politikanı kontrol et. Veritabanı işlemi/benzersiz sipariş kısıtı altında yalnızca bir kez karşıla.

Olay yinelemelerini şu değere göre ayıkla: event_id; yalnızca sıraya göre değil: farklı olay türleri aynı sıra değerini paylaşabilir. Durum tabanlı SDK işleyicileri ise fatura revizyonlarını birleştirir ve olay türünden bağımsız durumu kontrol eder. Bu birleştirmeyi olay türü filtresiyle karıştırma. İki yaklaşım da yine sipariş düzeyinde yineleme koruması gerektirir.

Şunu incele: requires_review ve siparişi karşılamadan önce manuel çözümleri kontrol et. amount_status = paid tek başına onayı kanıtlamaz. Üst düzey ödenen varlık alanları ödeme tamamlanmasını özetler; payment_info ayrıntılı ödeme alımlarını ve fiyat verilerini tutar. Tüm durumlar, olaylar ve istisna kuralları →

6. Yeniden denemeleri ve kurtarmayı test et

Küçük ödemeyi, yinelenen teslimatı, süresi dolmuş faturayı ve geçici kullanılamayan alıcıyı test et. Olayı tekrar oynatmak ikinci sipariş alacağı oluşturmamalıdır. Sıra dışı gelen olayları daha yeni durumun üzerine yazmadan işle.

Şunu incele: Mağaza → IPN / Webhook'lar → Geçmiş → Ayrıntılarveya Fatura Ayrıntıları'ndaki teslimat bölümleri. Yeniden gönderme yeni ödeme tamamlanmasını değil, kayıtlı olayı yeniden kullanır.

Düşük işlem kredisi, ödemeler devam ederken IPN/webhook'ları duraklatır. Açık siparişleri API üzerinden uzlaştır ve düzelme sonrası saklanan teslimatları işle. Tarayıcı yönlendirmesi veya müşteri ekran görüntüsüne dayanarak siparişi asla karşılama.