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

> Müşterinin hangi token ve zinciri kullanacağını zaten bilen geliştiriciler için yeni bir API uç noktası, ödemeyi oluştur ve kullanıma hazır bir yatırma adresini tek gidiş-dönüşte al, barındırılan UI'a gerek yok.

Source: https://mutopay.com/tr/blog/headless-payment-api/
Language: tr
Date: 2026-04-14

---

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ış.

```bash
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..."
  }'
```

```json
{
  "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](/api/docs). Sorular beklenir.