API reference

Hızlı Başlangıç

Bu kılavuz, bir sandbox API anahtarından ilk kartlı ödemenize yaklaşık beş dakikada ulaşmanızı sağlar. Aşağıdaki tüm istekler kurulumunuzun /v1 temel yoluna gönderilir. Örneklerde https://pay.example.com/v1 kullanılır; ana makine adını size verilenle değiştirin.

1. Sandbox anahtarı alın

Üye işyeri paneline giriş yapın, Geliştiriciler → API anahtarları bölümünü açın ve bir gizli anahtar oluşturun. Sandbox (test ortamı) kurulumunda anahtar sk_sandbox_ ile, canlı kurulumda sk_live_ ile başlar. sk_test_ anahtarı yoktur: sandbox ve canlı ayrı kurulumlardır ve bir anahtar yalnızca onu üreten kurulumda çalışır.

Gizli anahtar yalnızca bir kez gösterilir. Anahtarı sunucunuzun gizli bilgi deposunda saklayın; tarayıcıda veya mobil uygulamada asla tutmayın.

Her istekte bearer token olarak gönderin:

curl https://pay.example.com/v1/balance \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

200 yanıtı ile bakiyenizin dönmesi anahtarın çalıştığı anlamına gelir. Her yanıt Request-Id: req_… başlığını taşır; destek ekibiyle iletişime geçerken bu değeri iletin ve isteği daha sonra Geliştiriciler → İstek kayıtları altında bulun.

2. Ödeme oluşturun ve onaylayın

Tutarlar her zaman en küçük para birimi cinsinden bir tam sayıdır: try para biriminde 12500, 125,00 TRY demektir. Kartı ve confirm: true değerini göndererek ödemeyi tek çağrıda oluşturup onaylayın.

Ödemeyi onaylamak için fatura bilgileri zorunludur (müşteriler kılavuzuna bakın). 3-D Secure gerekebiliyorsa return_url değeri Ayarlar → Web siteleri ve geri dönüş adresleri altında kayıtlı olmalıdır (3-D Secure kılavuzuna bakın).

{
  "amount": 12500,
  "currency": "try",
  "capture_method": "automatic",
  "confirm": true,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4109090000000011",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "123",
      "holder_name": "Test Customer"
    },
    "billing_details": {
      "name": "Test Customer",
      "email": "test@example.com",
      "address": {
        "line1": "Bagdat Caddesi 1",
        "city": "Kadikoy",
        "state": "Istanbul",
        "postal_code": "34710",
        "country": "TR"
      }
    }
  },
  "return_url": "https://shop.example.com/pay/return",
  "description": "Order 1001",
  "metadata": {"order_id": "1001"}
}

Ağ hatasından sonra yapılan bir yeniden denemenin iki kez tahsilat yapmaması için isteği benzersiz bir Idempotency-Key ile gönderin:

curl -X POST https://pay.example.com/v1/payment_intents \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d @payment.json

4109090000000011 sandbox kartı (son kullanma 12/2030, CVC 123) onaylanan yerli bir kredi kartıdır. Diğer test kartları sandbox kılavuzunda listelenir. Kart numaraları yalnızca payment_method_data[card] içinde kabul edilir; platform, herhangi bir şey saklanmadan veya loglanmadan önce bunları bir vault token'ı ile değiştirir ve numaralar asla geri döndürülmez.

3. Sonucu okuyun

Kart için 3-D Secure adımı gerekmiyorsa ödeme zaten succeeded durumundadır:

{
  "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A",
  "object": "payment_intent",
  "amount": 12500,
  "amount_charged": 12500,
  "surcharge": 0,
  "amount_received": 12500,
  "captured_minor": 12500,
  "refunded_minor": 0,
  "amount_refundable": 12500,
  "currency": "try",
  "status": "succeeded",
  "capture_method": "automatic",
  "installments": 1,
  "payment_method_type": "card",
  "card": {
    "brand": "visa",
    "bin": "410909",
    "last4": "0011",
    "masked": "410909******0011",
    "exp_month": 12,
    "exp_year": 2030,
    "card_type": "credit",
    "domestic": true
  },
  "next_action": null,
  "last_payment_error": null,
  "description": "Order 1001",
  "metadata": {"order_id": "1001"},
  "created": 1790000000,
  "livemode": false
}

Kartı veren banka müşteriden doğrulama isterse ödeme requires_action durumuna geçer ve next_action müşteriyi nereye yönlendireceğinizi söyler. Her iki sonucu da 3-D Secure kılavuzunda anlatıldığı gibi ele alın:

{
  "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5B",
  "object": "payment_intent",
  "amount": 12500,
  "currency": "try",
  "status": "requires_action",
  "capture_method": "automatic",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://pay.example.com/3ds/start/att_01J9ZQ4V8K2M3N5P7R9T1W3Y5C",
      "return_url": "https://shop.example.com/pay/return"
    }
  },
  "created": 1790000000,
  "livemode": false
}

Siparişi yalnızca yönlendirmeye bakarak ödenmiş olarak işaretlemeyin. Doğruluk kaynağı olarak payment_intent.succeeded olayını (bir webhook, webhook kılavuzuna bakın) veya succeeded döndüren bir GET /v1/payment_intents/{id} çağrısını kullanın.

curl https://pay.example.com/v1/payment_intents/pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

4. Sonraki adımlar