# Ödeme API'si

> 2328.io Ödeme API'si ile kripto para ödeme oturumları oluşturun ve yönetin.

Ö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

Bir ödeme oturumu oluşturur ve müşterinin ödeme yapması için bir URL döner.

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama | Değerler |
|------|-----|---------|----------|----------|
| `amount` | decimal | evet | Para biriminde ödeme tutarı, örn. `100.00` |  |
| `currency` | string | evet | Fiat para birimi (USD, EUR, RUB, …) veya kripto para (USDT, TRX, BTC, …) | `USD`, `EUR`, `RUB`, `KZT`, `UAH`, `UZS`, `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `order_id` | string | evet | Sipariş ID'niz, örn. `ORDER-12345` (en fazla 128 karakter) |  |
| `to_currency` | string | hayır | Önceden seçilmiş kripto para | `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `network` | string | hayır\* | Ağ kodu (`to_currency` ayarlandığında veya `currency` bir kripto para olduğunda gereklidir) | `TRX-TRC20`, `ETH-ERC20`, `BASE`, `BSC-BEP20`, `AVAX-C`, `POL-MATIC`, `TON`, `SOL`, `BTC`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `url_return` | string | hayır | Ödemeden sonra yönlendirme URL'si, örn. `https://your-site.com/return` |  |
| `url_success` | string | hayır | `url_return` için alternatif |  |
| `url_callback` | string | evet | Webhook bildirimleri için URL, örn. `https://your-site.com/webhook` |  |
| `invite_code` | string | hayır | Yönlendiren kodu |  |
| `fee_split` | decimal | hayır | Ödeyene aktarılan merchant ücreti payı, 0–100 (%). 0 = merchant tamamen öder, 100 = ödeyen tamamen öder. Proje düzeyindeki ayarı geçersiz kılar. **Örnek: `30`** (ödeyen ücretin %30'unu karşılar). |  |
| `price_markup` | decimal | hayır | Fatura tutarı üzerinde markup veya iskonto, −99 ile 100 (%) arası. Proje düzeyindeki ayarı geçersiz kılar. **Örnek: `5`** (+%5) veya `-10` (%10 indirim). |  |
| `description` | string | hayır | İsteğe bağlı fatura açıklaması (en fazla 200 karakter). Ödeme sayfasında ödeyene gösterilir. **Örnek: `Premium plan — Order #12345`**. |  |
| `ttl_seconds` | int | hayır | Faturanın saniye cinsinden geçerlilik süresi, `300` (5 dakika) ile `86400` (24 saat) arasında. Bu sürenin sonunda fatura sona erer ve artık ödenemez. Varsayılan: `3600` (1 saat). **Örnek: `3600`**. |  |

### Yanıt

```json
{
  "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..."
  }
}
```

- Müşteriyi ödemeyi tamamlamak için `result.url` adresine yönlendirin.
- `tg_deeplink` — Telegram MiniApp üzerinden ödeme için Telegram bot deeplink'i.
- `qr` — yatırma adresinin Base64 ile encode edilmiş QR kodu (data URI). Bir adres zaten atandığında mevcuttur (`network`, `to_currency` ile birlikte ayarlandığında veya `currency` bir kripto para olduğunda); aksi takdirde `null`.
- `txid`, `payment_amount` — müşteri ödeme yapana kadar `null`'dur. İşlem zincir üzerinde tespit edildiğinde doldurulur. Bunun ne zaman olacağını öğrenmek için `payment_status: paid` webhook'unu dinleyin.
- `exchange_rate` — dönüştürme henüz uygulanabilir değilse `null` (örn. fiat → kripto kuru henüz kilitlenmedi). Bir ödeyen para birimi seçildiğinde doldurulur.

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/payment`
  - `amount` (decimal, required)
  - `currency` (enum, required): USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `order_id` (string, required)
  - `to_currency` (enum): USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `network` (enum): TRX-TRC20,ETH-ERC20,BASE,BSC-BEP20,AVAX-C,POL-MATIC,TON,SOL,BTC,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `url_return` (string)
  - `url_success` (string)
  - `url_callback` (string, required)
  - `invite_code` (string)
  - `fee_split` (decimal)
  - `price_markup` (decimal)
  - `description` (string)
  - `ttl_seconds` (integer)

## 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.

```json
{
  "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.

```json
{
  "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

> **DANGER:** Hiçbir zaman bir adres oluşturmayın veya ikame etmeyin, başka bir invoice’den adres tekrar kullanmayın veya `payer_amount`’yı halka açık fiyat üzerinden hesaplamayın. API yanıtı otoritatiftir.

### Tam kripto miktarı için fatura

invoice kendisi kripto para cinsindeyse kriptoyu `currency`’ya koyun:

```json
{
  "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.

> **WARNING:** Aynı `order_id` ile bir retry "bu invoice'i güncelle**" anlamına** gelmez. Değişen miktar, para birimi, geri çağrı, işaretleme, TTL veya yön alanları mevcut oturum geri döndüğü için göz ardı edilebilir. İlk talebi ısrarla devam ettirin ve kendi uygulamanızda çelişkili retries sorunu reddedin.

Ö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ı

| Durum | Doğru yol tutuşu |
|-----------|------------------|
| `address` / `qr` `null` | Ödeme yönlendirmesi henüz başlatılmadı. `url`'a yönlendirin veya yeni bir doğru belirtilmiş H2H invoice ile yeni bir `order_id` oluşturun. |
| HTTP `400` doğrulama hatası | Alan düzeyinde `errors`'yi okuyun; retry değişmemiş girdi. |
| HTTP `429` | Retry ile titrek üstel geri çekilme ve aynı `order_id` devam eder. |
| HTTP `503` / `direction_disabled` | Yenile `/v1/directions`; yönü geçici olarak veya retry sonra gizleyin. |
| Müşteri talebi timeout | Sonucu bilinmeyen gibi ele alın. Başka bir şey oluşturmadan önce `order_id` tarafından sorgulayın. |
| `underpaid_check` | Kısmi etkinliği saklayıp bir güncelleme veya daha sonraki bir durum bekleyin. Daha fazla mesaj geldiğinde iki kez kredi vermeyin. |
| `underpaid` | Son eksik ödeme durumu. Yapılandırılmış yerine getirme/manuel inceleme politikanızı gerçek kredili tutara uygulayın. |
| `overpaid` | Fazla parayla başarılı bir ödeme. reconciliation/iade politikası için gerçek tutarları aynı şekilde yerine getirin ve saklayın. |
| `aml_lock` | Fonları otomatik olarak yerine getirmeyin veya serbest bırakmayın; uyumluluk/destek iş akışına yönlendirin. |
| `cancel` | Invoice süresi doldu veya iptal edildi. Bir zincir üzerindeki gecikmiş transferin imkansız olduğunu varsaymayın; herhangi bir sonraki olayı destek ile uzlaştırın. |

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

Mevcut ödeme durumunu `uuid` veya `order_id` ile alın.

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama | Değerler |
|------|-----|---------|----------|----------|
| `uuid` | string | evet\* | Ödeme UUID (oluşturmadaki `result.uuid`'den) |  |
| `order_id` | string | evet\* | Sipariş ID'niz |  |

> **INFO:** `uuid` veya `order_id`'den en az biri gereklidir.

#### Interactive request: `POST /v1/payment/info`
  - `uuid` (string)
  - `order_id` (string)

## Ödeme listesi

Filtreleme ve sayfalama ile tüm ödemelerin bir listesini alın.

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama | Değerler |
|------|-----|---------|----------|----------|
| `status` | string | hayır | Ödeme durumuna göre filtre (bkz. [References](/docs/references)) | `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid`, `cancel` |
| `date_from` | date | hayır | Başlangıç tarihi (YYYY-MM-DD), örn. `2026-01-01` |  |
| `date_to` | date | hayır | Bitiş tarihi (YYYY-MM-DD), örn. `2026-01-31` |  |
| `page` | int | hayır | Sayfa numarası, varsayılan `1` |  |
| `per_page` | int | hayır | Sayfa başına öğe, varsayılan `15`, en fazla `5000` |  |

#### Interactive request: `POST /v1/payment/list`
  - `status` (enum): pending,check,paid,underpaid_check,underpaid,overpaid,cancel
  - `date_from` (string)
  - `date_to` (string)
  - `page` (integer)
  - `per_page` (integer)