Mobil hat yükleme

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

#Nasıl çalışır

GET  /recharge/countries            yükleme yapılabilen ülkeler
GET  /recharge/operators?country=US  operatörler, yükleme türleri ve tutarlar
POST /recharge/quote                fiyatınız ve 300 sn geçerli bir quote_token
POST /recharge/orders               cüzdanınızdan ödenen siparişi verin
GET  /recharge/orders/{order_id}    durumu sorgulayın veya Webhook bekleyin

• Tüm yollar /api/v1 ile başlar. Her istekte gönderdiğiniz başlıkları gönderin.
• İki POST isteği imzalı olmalıdır. Onları POST/orders ile aynı şekilde imzalayın, ancak kendi yollarını kullanın, örneğin /api/v1/recharge/quote.
• Yükleme siparişleri hediye kartı siparişlerinden ayrıdır. Onları okumak için /recharge uç noktalarını kullanın.
• Yalnızca doğrudan yükleme sunulur. PIN ürünleri (müşterinin kendisinin girdiği bir kod) sunulmaz.

#Ülkeler

GET/api/v1/recharge/countries, şu anda yükleme yapabileceğiniz ülkeleri listeler.

{
  "count": 2,
  "results": [
    {"code": "MX", "name": "Mexico", "currency_codes": ["MXN"], "operator_count": 4, "offer_count": 37},
    {"code": "US", "name": "United States", "currency_codes": ["USD"], "operator_count": 6, "offer_count": 52}
  ]
}

• code, ISO 3166-1 alpha-2 ülke kodudur. Sonraki isteklerde bunu country olarak gönderin.
• currency_codes, bu ülkedeki operatörlerin satış yaptığı yerel para birimleridir.
• Liste, operatörler eklendikçe veya kullanılamaz hale geldikçe değişir. Birkaç saatte bir yeniden yükleyin.

#Operatörler

GET/api/v1/recharge/operators?country=US, bir ülkedeki operatörleri listeler. Operatör adına göre filtrelemek için search=att ekleyin.

{
  "count": 1,
  "results": [
    {
      "operator_key": "us-att",
      "name": "AT&T",
      "country": "US",
      "country_name": "United States",
      "logo_url": "https://b2b.cardv.net/api/v1/catalog-assets/3f5c...a1.png",
      "subtypes": ["airtime", "data"],
      "amount_model": "range",
      "currency_codes": ["USD"],
      "amounts": [
        {"min": "5.0000", "max": "100.0000", "currency": "USD", "subtype": "airtime", "label": "5.0000-100.0000 USD"},
        {"min": "15.0000", "max": "15.0000", "currency": "USD", "subtype": "data", "label": "15.0000 USD"}
      ],
      "offer_count": 3
    }
  ]
}

• Tutarlar yerel tutarlardır: telefon hattına yerel para biriminde yüklenecek miktar.
• Bilinmeyen veya hatalı biçimli bir country HTTP 400 döner.

#Fiyat sorgusu

POST/api/v1/recharge/quote, tek bir yükleme için fiyatınızı verir. Bu istek imzalı olmalıdır.

{
  "country": "US",
  "operator_key": "us-att",
  "amount": "10.00",
  "local_currency": "USD",
  "subtype": "airtime"
}

Yanıt:

{
  "country": "US",
  "country_name": "United States",
  "operator": {"operator_key": "us-att", "name": "AT&T", "logo_url": ""},
  "subtype": "airtime",
  "local_amount": "10.0000",
  "local_currency": "USD",
  "merchant_price": "9.6200",
  "merchant_currency": "USD",
  "expires_at": "2026-09-30T08:20:30.123456+00:00",
  "quote_token": "eyJ2ZXJzaW9uIjox...:1uXyZa:8c1f..."
}

• merchant_price, cüzdanınızdan merchant_currency para biriminde ödenecek tutardır.
• quote_token, bu fiyatı expires_at zamanına kadar, yani 300 saniye boyunca sabitler. Siparişle birlikte değiştirmeden gönderin.
• Token hesabınıza ve bu ülke, operatör, tür ve tutara bağlıdır.
• Sipariş vermeden önce local_currency değerinin beklediğiniz para birimi olduğunu kontrol edin.
• Fiyat sorgusu para ayırmaz. İstediğiniz zaman yeni bir fiyat sorgulayabilirsiniz.

#Yükleme siparişi verme

POST/api/v1/recharge/orders, telefona yükleme yapar ve ödemeyi cüzdanınızdan alır. Bu istek imzalı olmalıdır.

{
  "external_order_id": "SHOP-RC-20260930-0001",
  "country": "US",
  "operator_key": "us-att",
  "amount": "10.00",
  "local_currency": "USD",
  "subtype": "airtime",
  "account": "12125550100",
  "quote_token": "eyJ2ZXJzaW9uIjox...:1uXyZa:8c1f..."
}

Telefon numarası örnekleri: 12125550100 (ABD), 525512345678 (Meksika). Numaranın seçilen operatöre ait olduğunu kontrol edin. Yanlış numaraya yapılan yükleme geri alınamaz.

CardV fiyat sorgusunu kontrol eder, merchant_price tutarını hemen cüzdanınızdan alır ve yüklemeyi arka planda başlatır. Yeni bir sipariş HTTP 201 döner:

{
  "idempotent_replay": false,
  "order": {
    "order_id": "O-00005678",
    "external_order_id": "SHOP-RC-20260930-0001",
    "status": "accepted",
    "status_title": "Recharge accepted",
    "poll_after_seconds": 12,
    "account": "12***00",
    "local_amount": "10.0000",
    "local_currency": "USD",
    "merchant_price": "9.6200",
    "merchant_currency": "USD",
    "...": "more fields"
  }
}

• order.order_id değerini saklayın.
• Telefon numarası maskelenmiş olarak döner, hiçbir zaman tamamı gösterilmez.

#Güvenli yeniden deneme

external_order_id, iki kez yükleme yapmanızı önler.

"Aynı yükleme", aynı ülke, operatör, tür, tutar ve telefon numarası demektir. Tekrarlanan sipariş, fiyat sorgusu kontrolünden önce tanınır. Bu yüzden süresi dolmuş bir quote_token ile bile ilk sipariş döner.

• Zaman aşımı, 5xx veya kopan bağlantıdan sonra aynı gövdeyi aynı sipariş numarasıyla gönderin. Yeni bir zaman damgası ve nonce ile yeniden imzalayın.
• Yanıt kayboldu diye asla yeni sipariş numarası üretmeyin. Bu, telefona iki kez yükleme yapılmasına yol açabilir.

#Yükleme siparişlerini okuma

GET/api/v1/recharge/orders/{order_id} tek bir sipariş döner. CardV sipariş numarasını (O-00005678) kullanabilirsiniz.

{
  "order_id": "O-00005678",
  "external_order_id": "SHOP-RC-20260930-0001",
  "status": "processing",
  "order_status": "processing",
  "status_title": "Recharge processing",
  "status_message": "The recharge request is being processed. Delivery is not confirmed yet.",
  "next_step": "Keep this order open and wait for confirmation before placing another recharge.",
  "poll_after_seconds": 12,
  "country": "US",
  "operator": {"operator_key": "us-att", "name": "AT&T", "logo_url": ""},
  "subtype": "airtime",
  "account": "12***00",
  "local_amount": "10.0000",
  "local_currency": "USD",
  "merchant_price": "9.6200",
  "merchant_currency": "USD",
  "attempts": [{"attempt_no": 1, "status": "processing", "error_message": "", "submitted_at": "2026-09-30T08:16:02.511201Z", "completed_at": null}],
  "created_at": "2026-09-30T08:16:01.004211Z",
  "updated_at": "2026-09-30T08:16:02.611978Z",
  "...": "more fields"
}

• Bilinmeyen bir sipariş numarası veya başka bir hesaba ait sipariş HTTP 404 döner.
• status_title, status_message ve next_step, ekibinize gösterebileceğiniz İngilizce metinlerdir.
• poll_after_seconds, bir sonraki kontrolden önce ne kadar bekleneceğidir. 0, siparişin tamamlandığı anlamına gelir.

#Yükleme siparişlerini listeleme

GET/api/v1/recharge/orders, yükleme siparişlerinizi en yeniden eskiye doğru listeler.

GET /api/v1/recharge/orders?status=processing&limit=50&offset=0

{"count": 3, "limit": 50, "results": ["..."]}

• Filtreler: status ve search (CardV sipariş numarası, kendi sipariş numaranız veya operatör adı).
• limit varsayılan olarak 20'dir, en fazla 100 olabilir. Daha büyük değerler 100'e düşürülür.
• Negatif ya da sayı olmayan bir limit veya offset HTTP 400 döner.

#Durum

accepted ──► processing ──► succeeded
                  │
                  ├──► manual_review ──► succeeded veya refunded
                  │
                  └──► failed ──► refunded   (para cüzdanınıza iade edildi)

• poll_after_seconds sonra sorgulayın, ardından aralığı uzatın: 30 sn, 60 sn, sonra 5 dakikada bir. İstek limitini aşmayın.
• Bilinmeyen bir durumu "henüz tamamlanmadı" olarak değerlendirin.
• Bir sipariş tamamlanmadan aynı numaraya yeni bir sipariş numarasıyla başka bir yükleme göndermeyin. İlki de başarılı olursa telefona iki kez yükleme yapılır.

#Webhook'lar ve iadeler

Yükleme siparişleri, diğer siparişlerle aynı Webhook'ları gönderir: order.succeeded, order.failed ve order.refunded. Webhook'ta CardV sipariş numarası, kendi sipariş numaranız ve boş bir items listesi bulunur. Webhook geldikten sonra siparişi GET/api/v1/recharge/orders/{order_id} ile okuyun.

İadeler otomatiktir. Operatör başarısızlığı onayladığında CardV merchant_price tutarının tamamını cüzdanınıza iade eder ve sipariş refunded olur. İadeyi Portal'daki hesap hareketleri sayfasında görebilirsiniz. Başarılı bir yükleme iade veya iptal edilemez.

#Hatalar

Hatalar Genel kurallar sayfasındaki yapıyı izler. Reddedilen bir fiyat sorgusu veya sipariş HTTP 400 döner ve hiçbir ücret alınmaz.

quote_token hataları bir code ile gelir:

{"code": "quote_expired", "quote_token": "This quote expired. Refresh the price and confirm again."}

HTTP 403, kimlik bilgileri, imza, IP veya onay sorunu demektir. Bkz. Kimlik doğrulama.