Ürünler ve siparişler

İlgili: Kimlik doğrulama · Genel kurallar · Webhook'lar

#Hesap ve bakiye

#Hesap

GET/api/v1/account, şirket bilgilerinizi ve API erişiminizin açık olup olmadığını gösterir.

{
  "merchant_id": "M00000001",
  "name": "Acme Shop",
  "legal_name": "Acme Shop Ltd",
  "billing_email": "[email protected]",
  "status": "active",
  "kyb_status": "approved",
  "api_access_enabled": true,
  "default_currency": "USD",
  "purchase_limits": {
    "currency": "USD",
    "verified": true,
    "max_order_amount": "1000.00",
    "daily_order_amount_limit": "10000.00",
    "daily_order_count_limit": 1000,
    "used_today_amount": "120.50",
    "used_today_count": 3,
    "day_resets_at": "2026-10-01T00:00:00+00:00"
  }
}

• default_currency, cüzdanınızın para birimidir. Ödediğiniz tüm fiyatlar bu para birimindedir.
• api_access_enabled, CardV işletmenizi onayladığında true olur.

#Bakiye

GET/api/v1/balance, harcayabileceğiniz tutarı gösterir.

{
  "currency": "USD",
  "balance": "1520.40",
  "reserved_amount": "0.00",
  "available_balance": "1520.40",
  "low_balance_threshold": "200.00",
  "low_balance_notified_at": null,
  "is_active": true
}

• available_balance, şu anda harcayabileceğiniz tutardır: balance eksi reserved_amount.
• Tutarı available_balance değerini aşan bir sipariş reddedilir ve hiçbir ücret alınmaz.
• low_balance_threshold, düşük bakiye e-postasının gönderileceği seviyedir. Bu değeri Portal'dan ayarlarsınız.
• Bakiye yüklemek için Portal'ı kullanın.

#Döviz kuru

GET/api/v1/fx-rates?quote=EUR, USD'den başka bir para birimine kuru verir.

Mağazanız USD dışında bir para birimiyle satış yapıyorsa bunu kullanın. CardV cüzdanınızdan her zaman USD olarak tahsil eder. Kur yalnızca kendi fiyatlarınızı belirlemenize yardımcı olur.

{
  "base": "USD",
  "quote": "EUR",
  "rate": "0.9234",
  "as_of": "2026-10-11T07:05:00Z"
}

• quote bir ISO 4217 para birimi kodudur; örneğin EUR, GBP veya JPY.
• base isteğe bağlıdır. Yalnızca USD desteklenir.
• rate, 1 USD karşılığında kaç birim quote aldığınızı gösterir. Ondalık bir metindir; float olarak okumayın.
• as_of, CardV'nin bu kuru en son güncellediği zamandır. Kurlar her saat güncellenir.
• quote=USD, "rate": "1" döndürür.
• Kuru kendi tarafınızda saklayın. Günde birkaç sorgu yeterlidir.

Bu isteği de diğerleri gibi imzalayın. İmzalanan yol sorgu dizesini içerir; örneğin /api/v1/fx-rates?quote=EUR.

#Ürünler (SKU'lar)

SKU, satın alabileceğiniz tek bir üründür, örneğin "Steam Wallet 10 USD". Numarası S000456 gibi görünür. Fiyat sorgusu ve sipariş SKU üzerinden yapılır.

#Ürün modelleri

Her SKU bu modellerden birine aittir. Ayırt etmek için denomination_type ve product_type alanlarına bakın.

• vertical ürün grubudur, model değildir. Doğrudan yüklemeler de vertical: "gift_card" olabilir.
• Sabit veya aralıklı tutarlı her SKU, kod yerine CardV kullanım bağlantısı olarak teslim edilebilir. Bu durumda SKU'da delivery_mode: "voucher" bulunur. Bir bağlantı alırsınız (delivery_type: "link", bağlantı redeem_url içindedir). Müşteriniz bağlantıyı açarak kodu alır. Bağlantıyı müşterinize bir kod gibi gönderin.

GET/api/v1/skus, satın alabileceğiniz SKU'ları listeler. Örnek:

GET /api/v1/skus?search=steam&region=US&limit=50&offset=0

Filtreler (hepsi isteğe bağlı):

Sayfalama: limit (varsayılan 100, en fazla 500) ve offset gönderin. offset değerini artırarak, count değerine ulaşana kadar sorgulamaya devam edin.

{
  "count": 7,
  "limit": 2,
  "results": [
    {
      "sku_id": "S000456",
      "product_id": "P000123",
      "name": "Steam Wallet 10 USD",
      "product_name": "Steam Wallet US",
      "brand": "Steam",
      "region": "US",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "fixed",
      "denomination_value": "10",
      "face_currency": "USD",
      "merchant_price": "9.25",
      "merchant_price_min": "9.25",
      "merchant_price_max": "9.25",
      "settlement_currency": "USD",
      "availability": "available",
      "min_quantity": 1,
      "max_quantity": 100,
      "required_input_schema": [],
      "...": "more fields"
    },
    {
      "sku_id": "S006126",
      "product_id": "P002210",
      "name": "Apple ES",
      "product_name": "Apple ES",
      "brand": "Apple",
      "region": "ES",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "range",
      "denomination_value": "0",
      "min_face_value": "2",
      "max_face_value": "250",
      "amount_step": null,
      "face_currency": "EUR",
      "merchant_price": "2.28",
      "merchant_price_min": "2.28",
      "merchant_price_max": "284.15",
      "price_label": "From 2.28 USD",
      "settlement_currency": "USD",
      "availability": "available",
      "...": "more fields"
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/skus/{sku_id}, aynı alanlarla tek bir SKU döner.

En çok işinize yarayacak alanlar:

İpuçları:

• Yalnızca aktif olan ve hesabınıza açık SKU'ları görürsünüz. Diğer SKU'lar 404 döner.
• SKU listesini 5–15 dakikada bir güncelleyin. Sipariş vermeden hemen önce mutlaka güncel fiyatı sorgulayın.
• Müşterilerinize senkronize ettiğiniz listedeki fiyatları gösterin. Her sayfa görüntülemesinde veya her ziyaretçi için fiyat sorgusu uç noktasını çağırmayın.
• Aralıklı tutarlı SKU fiyatları tedarikçi maliyetini izler ve gün içinde birkaç kez değişebilir. merchant_price_min ve merchant_price_max değerlerini SKU senkronizasyonunuzla birlikte yenileyin.
• filter_options, filtrelemede kullanabileceğiniz markaları, bölgeleri ve ürün gruplarını listeler.

#Ürün bazında senkronizasyon

Mağazanız her ürün için tutar seçicili tek bir sayfa gösteriyorsa SKU yerine ürünleri senkronize edin. GET/api/v1/products ürünleri listeler. Her ürün, içinde satın alabileceğiniz tüm SKU'ları taşır.

GET /api/v1/products?brand=Steam&region=GB&limit=50&offset=0

GET/api/v1/skus ile aynı filtreleri ve sayfalamayı kullanır. count ürün sayısını, sku_count bu ürünlerin SKU sayısını verir.

{
  "count": 1,
  "sku_count": 4,
  "limit": 50,
  "results": [
    {
      "product_id": "P000123",
      "product_name": "Steam Wallet UK",
      "brand": "Steam",
      "category": "Gaming",
      "region": "GB",
      "product_type": "pin_code",
      "image_url": "https://b2b.cardv.net/api/v1/catalog-assets/steam.png",
      "required_input_schema": [],
      "skus": [
        {
          "sku_id": "S000456",
          "name": "Steam Wallet 5 GBP",
          "label": "5 GBP",
          "denomination_type": "fixed",
          "denomination_value": "5",
          "face_currency": "GBP",
          "merchant_price": "7.61",
          "settlement_currency": "USD",
          "availability": "available",
          "min_quantity": 1,
          "max_quantity": 100,
          "...": "more fields"
        }
      ]
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/products/{product_id} tek bir ürünü SKU'larıyla birlikte, ayrıca description, redemption_instructions, terms ve disclaimer alanlarıyla döndürür.

• skus içindeki her SKU, GET/api/v1/skus ile aynı alanlara ve değerlere sahiptir. Fiyat teklifi ve sipariş her zamanki gibi sku_id ile yapılır.
• Seçenek metni olarak label kullanın, örneğin 5 GBP veya Tinder Plus 1 Month. Bazı ürünler tutar değil, pakettir.
• Bir ürünün tek bir nominal para birimi ve tek bir tutar türü vardır. Aralıklı tutarlı SKU her zaman ayrı bir üründür.
• Liste uzun metinleri içermez. Bunları her ürün için bir kez GET/api/v1/products/{product_id} ile okuyun.

#Sabit ve aralıklı tutarlar

SKU'ların çoğunun sabit bir yüz değeri vardır, örneğin 10 USD. Bazı SKU'lar ise aralıklıdır: tutarı müşteriniz seçer, örneğin 5 ile 500 USD arası.

Aralıklı bir SKU'da amount, min_face_value ile max_face_value arasında olmalıdır. Tutar face_currency para birimindedir.

Aralıklı tutarlı SKU fiyatı. SKU ve ürün listelerinde merchant_price ve price_label yalnızca min_face_value tutarının fiyatıdır. merchant_price_min ve merchant_price_max en düşük ve en yüksek tutarın fiyatını verir. Aradaki bir tutarın fiyatı bunların hiçbirinin basit bir katı değildir. Satış fiyatınızı belirlemeden veya sipariş vermeden önce tam amount ile fiyat teklifi alın ve o teklifin merchant_price değerini expected_unit_price olarak gönderin.

Bazı aralıklı SKU'larda ayrıca amount_step bulunur. null değilse amount bunun katı olmalıdır. Örneğin "amount_step": "1" ile 25 gönderebilirsiniz ama 25.50 gönderemezsiniz. Adıma uymayan bir tutarla yapılan fiyat teklifi veya sipariş HTTP 400 döner ve hiçbir ücret alınmaz.

#Doğrudan yüklemeler

Bazı ürünler, müşterinizin hesabına (örneğin bir oyun hesabına) doğrudan yükleme yapar. Bunun için CardV'nin hesap bilgilerine ihtiyacı vardır. Gereken bilgiler SKU'da listelenir:

"required_input_schema": [
  {"key": "player_id", "label": "Player ID", "type": "text", "required": true},
  {"key": "server", "label": "Server", "type": "text", "required": false}
]

Değerleri, her birinin key adını kullanarak sipariş satırının inputs alanında gönderin:

"inputs": {"player_id": "123456789", "server": "EU"}

• "required": false yazmıyorsa alan zorunludur. type, form alanınız için bir ipucudur, örneğin text.
• Zorunlu bir değer eksikse sipariş items hatasıyla reddedilir.
• Bu değerler müşterinizin kişisel verileridir. Onları koruyun (bkz. Güvenlik).

#Fiyat sorgusu

Fiyat sorgusu, belirli bir adet için güncel fiyatı söyler.

GET /api/v1/skus/S000456/quote?quantity=2
GET /api/v1/skus/S000789/quote?quantity=1&amount=25.00

{
  "sku_id": "S000456",
  "settlement_currency": "USD",
  "merchant_price": "9.25",
  "quantity": 2,
  "total_price": "18.50",
  "min_quantity": 1,
  "max_quantity": 100,
  "availability": "available"
}

• Fiyat sorgusu fiyatı sabitlemez. Fiyatlar her an değişebilir.
• Fiyatı yalnızca bir kez, müşteriniz ödeme adımına geçtiğinde, örneğin 5 saniye gibi kısa bir zaman aşımıyla sorgulayın. Sorgu zaman aşımına uğrarsa senkronize fiyatınızı göstermeye devam edin ve yeniden deneyin; bir sorgu yavaş kaldı diye asla hata sayfası göstermeyin.
• Kendinizi korumak için sipariş verirken merchant_price değerini expected_unit_price olarak gönderin. Kendi hesapladığınız bir fiyatı değil, fiyat sorgusundan gelen fiyatı gönderin: kuruşu kuruşuna tam olarak eşleşmelidir. Fiyat değiştiyse CardV siparişi reddeder ve hiçbir ücret almaz.
• Aralık dışındaki bir adet veya tutar ya da amount_step değerinin katı olmayan bir tutar, quantity ya da amount hatasıyla HTTP 400 döner.

#Sipariş verme

POST/api/v1/orders, bir veya daha fazla SKU satın alır ve ödemeyi cüzdanınızdan yapar. Her istek gibi bu istek de imzalı olmalıdır.

{
  "external_order_id": "SHOP-20260929-10001",
  "items": [
    {"sku_id": "S000456", "quantity": 2, "expected_unit_price": "9.25"},
    {"sku_id": "S000789", "amount": "25.00", "expected_unit_price": "23.75"},
    {
      "sku_id": "S000900",
      "expected_unit_price": "4.90",
      "inputs": {"player_id": "123456789"}
    }
  ]
}

CardV siparişi kabul ettiği anda toplam tutarın tamamını cüzdanınızdan düşer. Teslimat ardından arka planda başlar.

Yanıt HTTP 201 olur:

{
  "idempotent_replay": false,
  "order": {
    "order_id": "O-00001234",
    "external_order_id": "SHOP-20260929-10001",
    "status": "accepted",
    "total_amount": "46.20",
    "...": "more fields"
  }
}

order.order_id değerini saklayın. Bu yanıtta hiçbir zaman kod bulunmaz. Kodları daha sonra alırsınız (Siparişi okuma).

#Reddedilen siparişler

Reddedilen bir sipariş HTTP 400 döner ve hiçbir ücret alınmaz. Nedeni hata anahtarından anlaşılır:

Fiyat değişikliği örneği:

{
  "items": "SKU S000456 price changed from 9.25 to 9.41 USD; refresh quote and confirm again."
}

Hesabınızın tek bir sipariş tutarı, günlük harcama ve günlük sipariş sayısı için limitleri vardır. GET/api/v1/account bunları, bugün kullandığınız miktarla birlikte purchase_limits içinde gösterir. 0 limit olmadığı anlamına gelir. Günlük limitler 00:00 UTC'de sıfırlanır.

#Güvenli yeniden deneme

Kendi sipariş numaranız (external_order_id), aynı şeyi iki kez satın almanızı önler. Aynı siparişi aynı sipariş numarasıyla tekrar gönderirseniz CardV sizden tekrar ücret almaz. Bunun yerine mevcut siparişi döner.

"Aynı sipariş", aynı satırların aynı sırayla ve aynı SKU, adet, tutar ve hesap bilgileriyle gönderilmesi demektir. expected_unit_price gönderiyorsanız ilk siparişteki fiyatla aynı olmalıdır.

Tekrarlanan sipariş, bakiye ve fiyat kontrollerinden önce tanınır. Bu yüzden fiyat o arada değişmiş olsa bile her zaman ilk sipariş döner.

#Güvenli yeniden deneme akışı

Net bir yanıt alamazsanız aynı siparişi yeniden göndermeniz yeterlidir.

R sipariş numarasıyla POST /orders
 ├─ 201 veya 200 → order_id'yi saklayın. İşlem tamam.
 ├─ 400 items / balance / risk → sipariş oluşmadı.
 │      Nedeni düzeltip tekrar gönderin. R'yi yeniden kullanabilirsiniz.
 ├─ 400 external_order_id → R başka bir siparişe ait. Durun ve kontrol edin.
 ├─ 403 imza hatası → yeniden imzalayıp aynı gövdeyi gönderin.
 ├─ 429 → Retry-After kadar bekleyin, yeniden imzalayıp aynı gövdeyi gönderin.
 └─ zaman aşımı, 5xx veya kopan bağlantı
        → aynı gövdeyi aynı R ile tekrar gönderin.
          201 alırsanız ilk istek ulaşmamıştır, 200 alırsanız ulaşmıştır.

Kurallar:

• Yanıt kayboldu diye asla yeni sipariş numarası üretmeyin. İlk istek aslında ulaştıysa, yeni numara her şeyi iki kez satın almanıza yol açar.
• Her yeniden gönderimde yeni zaman damgası, nonce ve imza gerekir. Gövde aynı kalır.

#Siparişi okuma

GET/api/v1/orders/{order_id}, siparişi, durumunu ve kodlarını döner.

{
  "order_id": "O-00001234",
  "external_order_id": "SHOP-20260929-10001",
  "status": "succeeded",
  "currency": "USD",
  "total_amount": "18.50",
  "created_at": "2026-09-29T08:15:30.123456Z",
  "updated_at": "2026-09-29T08:15:41.004211Z",
  "items": [
    {
      "sku_id": "S000456",
      "product_name": "Steam Wallet US",
      "quantity": 2,
      "unit_price": "9.25",
      "total_price": "18.50",
      "delivery_count": 2,
      "deliveries": [{"...": "see Codes below"}]
    }
  ],
  "...": "more fields"
}

• total_amount, sipariş kabul edildiğinde sizden alınan tutardır.
• items[].unit_price, bu sipariş için sabitlenen fiyattır.
• items[].deliveries, kodların tamamını içerir. Bu yanıtı gizli bilgi gibi koruyun.
• invoice_url ve delivery_file_url, faturanın ve kodları içeren CSV dosyasının yollarıdır. İkisi de yalnızca Portal'da çalışır. API anahtarıyla çağrıldığında HTTP 403 döner.
• Yanıtta ayrıca şunlar da bulunur: id (eski bir numara, kullanmayın), events (yalnızca görüntüleme amaçlı geçmiş) ve satır bazında teslimat ilerlemesi. Bunları yok sayabilirsiniz.
• Bilinmeyen bir sipariş numarası HTTP 404 döner.

#Sipariş durumu ve kodlar

#Durum

accepted ──► processing ──► succeeded
                  │
                  ├──► partially_succeeded   (bazı satırlar teslim edildi, bazıları edilmedi)
                  │
                  └──► failed ──► refunded   (para cüzdanınıza iade edildi)

Webhook kullanmıyorsanız siparişi şu aralıklarla sorgulayın: 5 saniye sonra, ardından 10 sn, 30 sn, 60 sn, sonra 5 dakikada bir. İstek limitini aşmayın. Siparişlerin çoğu birkaç saniyede tamamlanır. Bazıları elle kontrol gerektirir ve saatler sürebilir.

#Kodlar

Teslim edilen her adet, items[].deliveries içinde bir nesnedir:

{
  "status": "stored",
  "delivery_type": "card_pin",
  "card_number": "X1234",
  "pin_code": "9876",
  "redeem_url": "",
  "expiry_date": "2027-09-29",
  "instructions": "Redeem at ..."
}

• Boş olmayan her alanı müşterinize verin: card_number, pin_code, redeem_url, expiry_date ve instructions.
• delivery_type ne aldığınızı söyler: code, card_pin, link, code_link veya qr.
• redeem_url değerini bir kod gibi gizli tutun.
• expiry_date boş olduğu için bir kodu asla silmeyin, gizlemeyin veya geçersiz kılmayın. Son kullanma tarihini müşterinize yalnızca boş değilse gösterin.
• status değeri voided olan bir adedi müşterinize asla vermeyin.
• Doğrudan yükleme ürünlerinde genellikle teslimat nesnesi olmaz. succeeded, hesaba yüklemenin yapıldığı anlamına gelir.
• Webhook'lar hiçbir zaman kod içermez. Webhook geldikten sonra siparişi okuyun.