Getir

API anahtarı: Payment

Bir faturanın güncel durumunu döndürür. Fatura oluşturma ile aynı yanıt sözleşmesini kullanır; payment nesnesi token ve ağ seçildikten sonra görünür.

Yanıt (200 OK)

{
  "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "status": "paid",
  "is_final": true,
  "is_test": false,
  "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
  "order": {
    "external_id": "order-12345",
    "client_id": "customer-67890",
    "amount": "50.00",
    "currency": "USDT",
    "network": "TRC20"
  },
  "payment": {
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "expected": "50.00",
    "address": "TLfGqSVPbET2KFczh3xb12Ja2RKfMCBPgp",
    "exchange_rate": "1.000000",
    "paid": "50.00",
    "remaining": "0",
    "fee": "0.50",
    "net": "49.50",
    "transfers": [
      {
        "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "amount": "50.00",
        "status": "confirmed",
        "created_at": 1739280712,
        "confirmed_at": 1739280912,
        "required_confirmations": 19,
        "estimated_confirmation_at": 1739280772,
        "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  },
  "created_at": 1739280600,
  "updated_at": 1739280912,
  "expires_at": 1739284200,
  "completed_at": 1739280912
}

Ödeme alanları

payment mevcut olduğunda şunları içerir:

Alan	Tip	Açıklama
payment.currency	string	Ödeme için seçilen kripto varlık sembolü (ör. USDT, USDC)
payment.network	string	Blockchain ağ kodu (ör. ERC20, TRC20, BEP20, POLYGON, BASE, TON, SOL)
payment.chain_id	integer	EIP-155 / TRON / TON kurallarına uyan sayısal zincir kimliği (ör. Ethereum mainnet için 1, Tron için 728126428)
payment.contract_address	string?	Token'ın zincir üzerindeki kimliği — EVM ve Tron'da kontrat adresi, TON'da jetton master, Solana'da SPL mint. Şemada isteğe bağlıdır, çünkü yerel bir coin'in böyle bir kimliği olmaz; kabul edilen varlıklar arasında yerel coin bulunmadığından gerçek bir faturada alan her zaman doludur. Kendi contract_address alanı için aynı kuralı GET /v1/payment-channel-deposits/:id belirtir
payment.expected	string	Müşterinin göndermesi gereken beklenen kripto tutarı
payment.address	string?	Müşterinin ödeme yaptığı yatırma adresi. Fatura awaiting_client durumundayken payment nesnesinin tamamı yanıtta bulunmadığından, bu alan bekleyen bir faturada asla null olarak görünmez — henüz okunacak bir payment yoktur
payment.exchange_rate	string?	expected değerini üreten fiat-kripto döviz kuru
payment.paid	string?	Onaylanan gelen transferlerin toplamı
payment.remaining	string?	Müşterinin hâlâ göndermesi gereken kalan tutar (expected - paid, asla negatif değil). Yalnızca en az bir transfer onaylandıktan sonra mevcuttur
payment.fee	string?	paid üzerinden alınan platform komisyonu tutarı
payment.net	string?	Satıcının alacağı tutar (paid - fee)
payment.transfers	array?	Transfer bazında ayrıntılar — en az bir zincir üstü transfer algılandıktan sonra mevcuttur. Aşağıya bakın.

Transfer Alanları

payment.transfers[] içindeki her kayıt:

Alan	Tip	Açıklama
tx_hash	string	Zincir üstü işlem hash'i (ağa özgü biçim)
amount	string	Transfer edilen kripto tutarı
status	string	confirming (onaylar bekleniyor) veya confirmed
created_at	unix timestamp	Pipeline'ımızın transferi işlenen bir blokta ilk gözlemlediği an. Sunucumuzun duvar saati, zincir üstü blok zaman damgası değil — pipeline geride kaldıysa farklılık gösterir. Aşağıdaki "kalan saniye" formülü için bunu kullanın (üst düzey fatura created_at değerini değil).
confirmed_at	unix timestamp?	Transferin gerekli onay sayısına ulaştığı an. Beklemedeyken null
required_confirmations	integer?	Bu transferin USD değer kademesi için confirmed durumuna ulaşmakta gereken onay sayısı. Blok sayısı yerine zincirin kendi finalized commitment'ı ile kapanan her ağda null — bugün BNB Smart Chain, Polygon, Solana, Avalanche ve Plasma. Ağ listesine değil null değerine dallanın: hangi zincirlerin kesinlikle onayladığı operasyoneldir ve değişebilir
estimated_confirmation_at	unix timestamp?	Transferin tahsile ulaşmasının beklendiği an. Blok sayan ağlarda gözlem anında transfer.created_at + required_confirmations × network_block_time olarak hesaplanır; blok sayısı olmayan kesinlik ağlarında ise transfer.created_at üzerine o zincirin tipik kesinlik süresi eklenir, böylece bekleme yine gösterilebilir. Statiktir — istekler arasında değişmez; transfer onaylanana (veya USD kademesi değişene) kadar her sorguda aynı değeri verir. "Kalan saniye" için istemcide hesaplayın: max(0, estimated_confirmation_at − now).
explorer_url	string?	Bu işlemin ağın blok gezginindeki doğrudan bağlantısı (Tronscan / Etherscan / Tonviewer vb.). Ağın yapılandırılmış herkese açık bir gezgini yoksa null. Olduğu gibi tıklanabilir bağlantı olarak göstermek güvenlidir — dönüşüm gerekmez.

Fatura durumları

Her fatura bir status dizesi bildirir. Aynı değer; satıcı API yanıtını, SSE ödeme akışını ve webhook yükünü yönetir — tek bir doğruluk kaynağı vardır. Aşağıdaki tablo durum bazlı referanstır: değerin ne zaman göründüğü, nihai olup olmadığı ve arkasındaki kesin koşul. Geçiş diyagramı ve iki oluşturma akışı için bkz. Ödeme akışı.

Nihai bir durum kesindir: fatura orada sonuçlanır ve bir daha asla hareket etmez. Beş durum nihai'dir — paid, paid_over, underpaid, expired, cancelled.

Durum	Nihai	Ne zaman geçerli
awaiting_client	Hayır	Her faturanın açılış durumu. Henüz token veya ağ seçilmediği için yatırma adresi yoktur. İptal yalnızca burada mümkündür
awaiting_payment	Hayır	Token, ağ ve yatırma adresi sabitlendi. Paymos, gelen transfer için adresi izliyor
confirming	Hayır	Bir transfer zincire düştü ve tutar kademesinin gerektirdiği onayları biriktiriyor
underpaid_waiting	Hayır	Beklenenden az tutar onaylandı ve fatura kalan için açık kalıyor. Yalnızca allow_multiple_payments true olduğunda ulaşılır
paid	Evet	Beklenen tutar tam olarak onaylandı (veya projenin eksik ödeme toleransı içinde)
paid_over	Evet	Beklenenden fazla tutar onaylandı; transferin tamamı hesaba geçer
underpaid	Evet	Fatura eksik kapandı — ya beklenen tutarın altında süresi doldu ya da allow_multiple_payments false iken tek ödeme eksik kaldı
expired	Evet	Hiçbir şey alınmadan süre doldu veya fiat akışında token seçim penceresi token seçilmeden kapandı
cancelled	Evet	Satıcı, fatura hâlâ awaiting_client durumundayken iptal etti

Hatalar

Tam katalog için bkz. Hata Kodları. Her hata yanıtındaki type URI'si ilgili satıra doğrudan bağlanır.