Ödeme API'si

Ödeme API'si, ödeme oturumları oluşturmanıza, müşterileri hosted checkout'a yönlendirmenize ve ödeme durumunu takip etmenize olanak tanır.

Ödeme oluştur

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Hosted checkout, H2H ve tam kripto miktarları

Aynı uç nokta üç farklı invoice şekli destekler. Birini kasıtlı olarak seçin; miktar anlamlarını karıştırmayın.

Ödeyen seçeneğiyle Hosted checkout

amount, currency, order_id ve url_callback gönderin, ancak to_currency ve network’yi atlayın. Yanıt result.url içerir; address, qr ve bazen ödeyen alanları, ödeyen barındırılan sayfada bir yön seçeneği belirleyene kadar null olarak kalır.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Doğrudan adres H2H invoice

Hem to_currency hem network gönderin. 2328.io, API call sırasında blok zincirinde invoice oluşturur, böylece başarılı bir yanıtı müşteriyi yeniden yönlendirmeden ödeme sayfanız içinde görüntüleyebilirsiniz.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Bu değerleri tam olarak döndüğü şekilde render edin:

• payer_amount ve payer_currency — ödeme talimatı;
• network ve address — bu invoice için tek hedef;
• qr — aynı adres için bir veri URI’si;
• expires_at — invoice son tarihi;
• url — özel ödeme sayfası tamamlanamadığında yararlı bir barındırılan fallback

Tam kripto miktarı için fatura

invoice kendisi kripto para cinsindeyse kriptoyu currency’ya koyun:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

İstenen kripto değeri payer_currency / payer_amount içinde korunur. Hizmet ayrıca muhasebe ve oran alanları için içsel olarak USD değerini tutabilir; kesin kripto talimatını bu değerle değiştirmeyin. Döndürülen ondalık dizeleri, son hassasiyet dahil, koruyun.

Yalnızca bir desteklenen ağı olan kripto para için ağ otomatik olarak seçilebilir. Belirli bir entegrasyon için network’yı açıkça sağlamak yine de önerilir. Stabilcoinler gibi çok ağlı varlıklar için, her zaman gönderin.

Idempotency ve retries

order_id, kimliği doğrulanmış merchant projesine ait olarak kapsamlanmıştır ve oluşturma idempotency anahtarı olarak işlev görür. Eğer bir ödeme zaten mevcutsa, API o oturumu state: 0 ile döndürür.

Önerilen oluşturma algoritması:

1. Yerel ödeme denemenizi ve benzersiz order_id tek bir veritabanı işlemini ekleyin.
2. İmzalanmış API isteği gönderin.
3. Geri dönen uuid ve tam yanıtı ısrarla ver.
4. HTTP sonucu kaybolursa, retry aynı istek veya sorgu /v1/payment/info tarafından order_id tarafından gönderilir.
5. Sadece yukarı akış isteği zaman dolması nedeniyle ikinci yerel sipariş oluşturma.

Ödeme uç durumları

Tarayıcı dönüş URL’si yalnızca gezinme içindir. Bir müşteri ödemeden açabilir, ödedikten sonra kapatabilir veya daha sonra tekrar oynatabilir. Yalnızca doğrulanmış bir API/webhook durumu merchant siparişini sonuçlandırabilir.

Ödeme bilgisi

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Ödeme listesi

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"