CardV Merchant API

#Dokümanlar

#Ortamlar

Sandbox, CardV'nin test parasıyla çalışan ayrı bir test kopyasıdır. API anahtarları, bakiyeler, siparişler ve ürün numaraları iki ortamda birbirinden farklıdır.

#Hızlı başlangıç

1. Başvurun. Portal'dan üye işyeri hesabı için başvurun ve e-posta adresinizi doğrulayın.

2. Onayı bekleyin. CardV işletmenizi inceler. Ardından size bir Merchant ID (üye işyeri numarası) verilir, örneğin M00000001.

3. Sandbox'ı açın. Portal'a giriş yapın ve üst menüden Sandbox'ı seçin. Hesabınıza 1.000 USD test parası tanımlanır.

4. API anahtarı oluşturun. Portal'da Integrations → API keys bölümüne gidin. Bir anahtar oluşturun. Portal, anahtar kimliğini ve imzalama sırrını yalnızca bir kez gösterir. Sırrı gizli bilgi deponuza kaydedin.

5. Bakiyenizi kontrol edin:

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

6. Bir ürün bulun:

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

   "availability": "available" olan bir ürün seçin ve sku_id değerini not edin.

7. Fiyatı öğrenin:

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

   merchant_price değerini not edin. Bu, adet başına ödeyeceğiniz tutardır.

8. Siparişi verin. Her istek gibi bunu da imzalayın. Kimlik doğrulama sayfasındaki örneklerden birini şu gövdeyle kullanın:

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.25"}
     ]
   }

   Yanıt olarak HTTP 201 ve O-00001234 gibi bir CardV sipariş numarası alırsınız.

9. Kodları alın. Durum succeeded olana kadar GET/api/v1/orders/O-00001234 isteğini tekrarlayın. Kodlar items[].deliveries[] içindedir: card_number, pin_code ve redeem_url. Sipariş tamamlandığında bir Webhook bildirimi de alabilirsiniz.

10. Canlıya geçin. Önce Sandbox kontrol listesini tamamlayın.

Yukarıdaki numaralar ve fiyatlar örnektir. Kendi kataloğunuzda dönen değerleri kullanın.

#Kısaca API

Toplam on altı uç nokta vardır. Tüm yollar /api/v1 ile başlar.

Başka bir uç noktayı API anahtarıyla çağırırsanız HTTP 403 alırsınız:

{"detail": "This operation is only available in the Merchant Portal."}

Mobil hat yükleme, Mobil hat yükleme sayfasında anlatılıyor.

#Numaralar

Numaraları metin olarak saklayın. İçlerini ayrıştırmaya çalışmayın. Bkz. Genel kurallar.

#Portal'dan yapılanlar

• Cüzdana bakiye yükleme ve düşük bakiye e-posta uyarısı
• Sipariş geçmişi, arama ve CSV dışa aktarma
• Sipariş faturaları
• Cüzdan hareketleri ve mutabakat
• Webhook kurulumu, gönderim geçmişi ve yeniden gönderme
• API anahtarları
• IP izin listesi
• Ekip üyeleri ve roller
• Denetim kaydı
• İki adımlı doğrulama (2FA)
• Live ile Sandbox arasında geçiş

#Uyumluluk ve destek

Yanıtlara önceden haber vermeden yeni alanlar ve yeni durum değerleri ekleyebiliriz. Tanımadığınız alanları yok sayın. Bilinmeyen bir sipariş durumunu "henüz tamamlanmadı" olarak değerlendirin. Hata mesajlarının metnine güvenmeyin.

Destek için [email protected] adresine yazın. Merchant ID'nizi, ortamı, sipariş numaralarını, saati (UTC) ve HTTP durum kodunu ekleyin. API anahtarlarını, imzaları, Webhook sırlarını veya kart kodlarını asla göndermeyin.