Başsız Ödemeler: Tek Çağrılı Yatırma Tabanlı Checkout

Kendi checkout’unu kuruyorsan — mobil uygulama, ortak platform, özel mağaza — barındırılan /pay/{id} sayfası her zaman uygun değildir. Zaten bir cüzdan akışın var. Müşterinin hangi zincirde ve hangi token ile ödeyeceğini zaten biliyorsun. Aslında istediğin şey, bir yatırma adresi ve gönderilecek tam miktarı döndüren tek bir API çağrısı.

İşte POST /api/payments/headless tam da bunun için.

Çağrının şekli

Tek giriş. Tek çıkış.

curl -X POST https://mutopay.com/api/payments/headless \
  -H "X-API-Key: ep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "description": "Sipariş #1042",
    "external_id": "order_1042",

    "src_token_symbol": "USDT",
    "src_token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "src_chain_id": "137",
    "src_decimals": 6,
    "src_address": "0xCustomerWallet..."
  }'

{
  "id": "pay_abc123...",
  "status": "awaiting_payment",
  "route_type": "bridge",
  "protocol": "rubic",
  "deposit": {
    "address": "0xRubicDepositAddress...",
    "chain_id": "137",
    "chain_type": "evm",
    "token_symbol": "USDT",
    "token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "token_decimals": 6,
    "amount_raw": "25100000",
    "amount_human": "25.10",
    "payment_uri": "ethereum:0x...@137?value=25100000"
  },
  "bridge": {
    "name": "Across",
    "estimated_time_ms": 60000,
    "src_usd": "25.10",
    "bridge_fee_usd": "0.10"
  },
  "order_id": "rubic_exchange_id...",
  "expires_at": "2026-04-14T15:30:00Z"
}

Uygulaman artık ihtiyaç duyduğu her şeye sahip: müşteriye amount_raw kadar kaynak token’ı tam olarak address adresine göndermesini söyle. İstersen payment_uri değerinden bir QR çiz. GET /api/payments/{id}/status’ü son duruma ulaşana kadar yokla.

İki rota türü, tek bir şekil

Direkt — aynı token, aynı zincir (müşteri Polygon’da USDT öder, sen Polygon’da USDT tahsil edersin). Yatırma adresi senin cüzdanın. Köprü ücreti yok, bekleme yok.
Swap / bridge yatırma — müşterinin tek bir işlem ile bir giriş adresine gönderdiği ve tahsilat token’ının cüzdanına ulaştığı tokenler-arası veya zincirler-arası rota. Herhangi bir sipariş imzası yok.

Müşterinin tipli bir sipariş imzalamasını veya on-chain swap işlemi yayınlamasını gerektiren rotalar bu uç noktada desteklenmez — mevcut tek rota bu ise 422 alırsın. O durumlar için barındırılan /pay/{id} sayfasını veya daha düşük seviyeli /quotes + /build-order + /submit-order üçlüsünü kullan.

Hâlâ yapman gerekenler

İki şey:

1. Tx hash’i alabiliyorsan al. Swap/bridge yatırmalarında hiçbir şey yapmana gerek yok — arka plandaki izleyici yatırmayı otomatik olarak yakalar ve ödemeyi tamamlandı olarak işaretler. Direkt rotalarda izleyici yalnızca tx hash varsa doğrulama yapar, bu yüzden müşteri işlemi yayınladıktan sonra POST /api/payments/{id}/confirm çağır ve { "tx_hash": "0x..." } gönder. Cüzdan UI’n sana hash’i veriyorsa (çoğu verir), bu tek satırlık bir iştir.

2. Durumu yokla. GET /api/payments/{id}/status mevcut durumu ve ödeme tamamlandığında tx hash’i döndürür. Kanalında yapılandırdığın webhook aynı olayları (payment.completed, payment.failed, vb.) tetikler — mimarine hangisi uyuyorsa onu kullan.

Hangisini ne zaman kullanmalı

Neyi inşa ediyorsun	Kullan
Yönlendirmeli WooCommerce / Shopify tarzı entegrasyon	`POST /api/payments` → `/pay/{id}`
Cüzdan akışını senin kontrol ettiğin özel checkout	`POST /api/payments/headless`
Birden fazla swap rotası sunup kullanıcıya seçim bırakmak	`POST /api/payments` + `/quotes` + `/build-order`

Headless uç noktası tasarım gereği daha dar. En iyi yatırma tabanlı rotayı otomatik seçer, ona bağlanır ve sana bir yatırma adresi döndürür. Daha fazla kontrol lazımsa — hız ile fiyat arasında denge, birden çok rota seçeneği, imzalı sipariş akışları — ayrıntılı uç noktalar hâlâ duruyor.

Tam referans API dokümanlarında. Sorular beklenir.