API Dokümantasyonu

Giriş

AuroraSky Payments API'si, Türkiye'den yurt dışına dijital ürün satan geliştiricilerin ödeme altyapısına erişmesini sağlar. API, REST mimarisine uygun tasarlanmıştır ve JSON formatında veri alıp verir.

Hızlı Başlangıç

1. Hesap oluşturun — Dashboard üzerinden kayıt olun ve KYC doğrulamasını tamamlayın.
2. API anahtarınızı alın — Dashboard → Ayarlar → API Anahtarları.
3. İlk sipariş oluşturun — POST /orders ile Stripe Checkout oturumu başlatın.
4. Webhook dinleyin — payment_intent.succeeded olayını işleyin.

Kimlik Doğrulama

Tüm sipariş endpoint'leri Authorization başlığında bir API anahtarı bekler. Anahtarı Dashboard → Ayarlar → API Anahtarları bölümünden oluşturursunuz. Anahtar yalnızca oluşturulduğu anda bir kez gösterilir; sunucumuzda yalnızca SHA-256 özeti saklanır, bu yüzden kaybedilen anahtar geri getirilemez — yenisini oluşturmanız gerekir.

Satıcı kimliği anahtardan çözülür. İsteklerinizde ayrıca merchant_id göndermenize gerek yoktur; gönderirseniz anahtarın sahibiyle eşleşmek zorundadır, aksi halde 403 alırsınız.

Authorization: Bearer sk_live_••••••••mP7z
Content-Type: application/json

Idempotency

Para hareketi içeren tüm endpoint'ler Idempotency-Key başlığı zorunludur. Aynı key ile yapılan tekrar istekler aynı sonucu döner — ağ hatası nedeniyle çift ödeme oluşmaz.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

POST /orders

Yeni bir sipariş başlatır ve Stripe Checkout oturumu oluşturur. Alıcıyı dönen checkout_url adresine yönlendirmeniz gerekir.

İstek Gövdesi

Başlıklar

curl -X POST https://api.auroraskypayments.com/orders \
  -H "Authorization: Bearer sk_live_••••mP7z" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Pro Lisans — Yıllık",
    "amount_minor": 4900,
    "currency": "USD",
    "success_url": "https://siteniz.com/odeme/tamamlandi",
    "cancel_url": "https://siteniz.com/odeme/iptal",
    "merchant_order_ref": "SIP-2026-0417"
  }'

{
  "checkout_session_id": "cs_test_a1b2c3d4e5f6...",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3...",
  "pricing": {
    "seller_price_minor": 4900,
    "processing_fee_minor": 334,
    "buyer_total_minor": 5234,
    "platform_fee_minor": 295,
    "seller_payout_minor": 4605,
    "currency": "USD"
  }
}

Fiyatlandırma Alanları

GET /orders/:id

Belirli bir siparişin detaylarını döner.

curl https://api.auroraskypayments.com/orders/d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a \
  -H "Authorization: Bearer sk_live_••••mP7z"

{
  "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
  "merchant_id": "8f2ac41b-3e7d-4f12-9c8a-1b2d3e4f5a6b",
  "buyer_email": "alici@example.com",
  "amount_minor": 4900,
  "platform_fee_minor": 295,
  "processor_fee_minor": 177,
  "currency": "USD",
  "processor_type": "stripe",
  "status": "captured",
  "merchant_order_ref": "SIP-2026-0417",
  "payout_id": null,
  "created_at": "2026-09-03T14:22:00.000Z",
  "updated_at": "2026-09-03T14:22:01.000Z"
}

Sipariş Durumları

GET /orders

API anahtarınızın sahibi olan satıcının siparişlerini listeler. Sayfalama ve durum filtreleme destekler. merchant_id query parametresi kabul edilmez — satıcı kimliği her zaman anahtardan çözülür, böylece başka bir satıcının siparişleri sorgulanamaz.

Query Parametreleri

{
  "orders": [
    {
      "id": "d4e5f6a7-...",
      "merchant_id": "8f2ac41b-...",
      "buyer_email": "alici@example.com",
      "amount_minor": 4900,
      "platform_fee_minor": 295,
      "processor_fee_minor": 177,
      "currency": "USD",
      "status": "captured",
      "merchant_order_ref": "SIP-2026-0417",
      "payout_id": null,
      "created_at": "2026-09-03T14:22:00.000Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

POST /orders/:id/refund

Tahsil edilmiş bir siparişi iade eder. Tam veya kısmi iade desteklenir. Aynı sipariş için birden fazla kısmi iade yapılabilir; toplam iade tutarı sipariş tutarını aşamaz.

İstek Gövdesi

curl -X POST https://api.auroraskypayments.com/orders/d4e5f6a7-.../refund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 2500,
    "reason": "requested_by_customer"
  }'

{
  "refund_id": "8a2b1c4d-...",
  "processor_refund_id": "re_3Nk2...",
  "amount_minor": 2500,
  "currency": "USD",
  "platform_fee_refunded_minor": 137,
  "processor_fee_refunded_minor": 82,
  "order_refunded_total_minor": 2500,
  "order_status": "captured",
  "fully_refunded": false
}

Komisyon iadesi

Kısmi iadede komisyon da orantılı geri verilir. $100'lık siparişten $25 iade ederseniz komisyonun dörtte biri de iade edilir. Aksi halde tam iade sonrası platform kâr etmiş olurdu — bu muhasebeyi bozar. Yuvarlama farkı her zaman satıcı lehine çözülür.

Durum kodları

Hesap Endpoint'leri

Bu endpoint'ler Dashboard'un kullandığı hesap işlemleridir. Sipariş endpoint'lerinden farklı olarak API anahtarı değil, oturum token'ı beklerler (/auth/login yanıtındaki access_token).

curl -X POST https://api.auroraskypayments.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "siz@sirketiniz.com",
    "password": "***"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "v1.MRq...",
  "expires_in": 3600,
  "user": {
    "id": "8f2ac41b-3e7d-4f12-9c8a-1b2d3e4f5a6b",
    "email": "siz@sirketiniz.com",
    "name": "Acme Ltd.",
    "kyc_status": "verified",
    "reserve_percentage": 10
  }
}

API Anahtarları

Sipariş endpoint'lerinde kullanacağınız anahtarları bu endpoint'lerle yönetirsiniz. Hepsi oturum token'ı ister.

curl -X POST https://api.auroraskypayments.com/auth/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Üretim sunucusu", "environment": "live" }'

{
  "id": "3f1c8e2a-...",
  "name": "Üretim sunucusu",
  "key_prefix": "sk_live_a1b2",
  "environment": "live",
  "created_at": "2026-09-03T19:00:00Z",
  "api_key": "sk_live_a1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6",
  "warning": "Bu anahtar yalnızca bir kez gösterilir. Güvenli bir yere kaydedin."
}

KYC Belgeleri

Sipariş oluşturabilmeniz için kimlik doğrulamasının tamamlanmış olması gerekir. Bu, Merchant of Record modelinin yasal zorunluluğudur — sizin adınıza tahsilat yapabilmemiz için kim olduğunuzu doğrulamamız gerekiyor.

Belge türleri

Dosya kuralları

• İzinli türler: PDF, JPEG, PNG, WebP
• Boyut sınırı: 10 MB
• Dosyanın gerçek türü içeriğinden doğrulanır. Uzantısı veya Content-Type başlığı yanlış olan dosya reddedilir.

curl -X POST https://api.auroraskypayments.com/kyc/documents/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "document_type=government_id" \
  -F "file=@kimlik.pdf"

{
  "id": "doc_01HXYZ...",
  "document_type": "government_id",
  "status": "pending",
  "size_bytes": 284736,
  "content_type": "application/pdf",
  "created_at": "2026-09-06T02:14:00Z"
}

Webhook Kurulumu

Ödeme tamamlandığında, iade yapıldığında veya itiraz açıldığında AuroraSky belirlediğiniz URL'e HTTP POST isteği gönderir.

1. Dashboard → Ayarlar → Webhook URL alanına sunucunuzun adresini girin.
2. Webhook Secret'ınızı not edin — gelen isteklerin imzasını doğrulamak için kullanacaksınız.
3. Sunucunuz 200 döndüğünde olay teslim edilmiş sayılır. Başka bir yanıt alınırsa exponential backoff ile tekrar denenir.

İmza Doğrulama

Her webhook isteğinde Stripe-Signature başlığı bulunur. İmza HMAC-SHA256 ile hesaplanır.

Stripe-Signature: t=1614556800,v1=5257a869e7ecebeda3...

Doğrulama Adımları

1. t değerini (unix timestamp) ve v1 değerini (imza) ayırın
2. {t}.{ham_gövde} string'ini webhook secret ile HMAC-SHA256 ile imzalayın
3. Hesapladığınız hex digest'i v1 değeriyle sabit zamanlı karşılaştırma ile kontrol edin
4. Timestamp'in 5 dakikadan (300 sn) eski olmadığını doğrulayın (replay koruması)

import crypto from 'crypto';

function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const signature = parts.find(p => p.startsWith('v1=')).slice(3);

  // Replay koruması: 5 dakikadan eski olayları reddet
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Webhook Olay Türleri

Desteklenen Para Birimleri

Tüm tutarlar minor unit (kuruş/sent) cinsinden tam sayı olarak gönderilir. Sıfır ondalıklı para birimlerinde (JPY) tutar doğrudan birim cinsindendir.

Hata Kodları

API hataları standart HTTP durum kodları ile döner. Yanıt gövdesinde error alanı her zaman bulunur.

{
  "error": "Satıcı KYC doğrulaması tamamlanmamış",
  "kyc_status": "pending"
}

Doğrulama Hataları (400)

Birden fazla alan geçersizse tüm hatalar details dizisinde döner:

{
  "error": "Geçersiz istek",
  "details": [
    "amount_minor pozitif tam sayı olmalı (kuruş/sent cinsinden)",
    "product_name zorunlu",
    "success_url zorunlu"
  ]
}

Fiyatlandırma Modeli

Rate Limits

API istekleri, kötüye kullanımı önlemek için sınırlandırılmıştır.

Limit aşıldığında 429 Too Many Requests döner. Retry-After başlığında kaç saniye beklemeniz gerektiği belirtilir.

Limitler API anahtarı başına uygulanır; kimliksiz isteklerde IP esas alınır. Sayaç sabit pencere (fixed window) yöntemiyle tutulur. Her yanıtta RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset başlıkları bulunur — kotanızı istek göndermeden takip edebilirsiniz.