Kartla ödeme alın, USDC teslim alın — hesapla veya hesapsız

Bir ödeme nasıl işler

Akış her modda aynıdır. Yalnızca paranın gittiği yer ve etrafındaki araçlar değişir.

Tüm API çağrıları için temel URL: https://api.utopay.app. İstekler ve yanıtlar JSON'dır (content-type: application/json). Tutarlar siparişin para birimindeki sayılardır; zamanlar Unix milisaniyedir.

Hızlı başlangıç

Tek istekte gerçek bir ödeme — kayıt gerekmez. Alıcı doğrudan PayPal'a gönderilir; PayPal bu ödemeyi kabul edemezse diğer yöntemlerle ödeme sayfamız açılır.

curl -X POST https://api.utopay.app/v1/pay \
  -H "content-type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "payout_wallet": "0xYourPolygonWalletAddress000000000000000000",
    "provider": "paypal",
    "success_url": "https://yoursite.com/thanks"
  }'
# → { "id": "ord_…", "checkout_url": "https://api.utopay.app/pay/ord_…/go?provider=paypal", … }

Alıcıyı checkout_url adresine yönlendirin. Ödemeden sonra cüzdanınıza yaklaşık 95.5 USDC gelir. Hesapla bunun yerine API anahtarıyla POST /v1/payments çağırırsınız — aynı alanlar, artı geçmiş, webhook'lar ve bakiye.

Modları karşılaştırın

Hesapsız

POST /v1/pay

Authorization başlığı yok. Para her zaman doğrudan payout_wallet adresine gider — Polygon üzerinde USDC alabilen bir EVM adresi. Gövde POST /v1/payments ile aynıdır, ek olarak:

• Her zaman direct: "settlement": "custody" 400 döndürür — hesap olmadan yatırılacak bakiye yoktur.
• Sabit %4.5 ücret, ortaklık programı yok, webhook yok (callback_url kaydedilir ama çağrılmaz), test modu yok, standart ödeme sayfası tasarımı.
• Takip: herkese açık GET /api/checkout/:id/status endpoint'ini sorgulayın (anahtarsız) veya cüzdanınızı izleyin.

Hesap ve API anahtarları

Bir hesapta en fazla 20 proje olabilir (site başına bir). Her birinin kendi anahtarları, webhook'ları, cüzdanı, markası, fon modu ve istatistikleri vardır; bakiye tüm hesapta ortaktır.

Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx

Anahtar yalnızca bir kez gösterilir; yalnızca hash'ini saklarız. Gizli anahtarı asla tarayıcı veya mobil koda koymayın.

Ödeme oluşturma

POST /v1/payments Bearer sk

curl -X POST https://api.utopay.app/v1/payments \
  -H "Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "amount": 250,
    "currency": "EUR",
    "email": "[email protected]",
    "description": "Invoice #118",
    "provider": "revolut",
    "success_url": "https://yoursite.com/thanks"
  }'

{
  "id": "ord_Kd83mQp0aVxY",
  "status": "pending",
  "amount": 250, "currency": "EUR",
  "checkout_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY/go?provider=revolut",
  "payment_page_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY",
  "provider": "revolut",
  "routing": { "mode": "direct_to_provider", "requested_provider": "revolut", "reason": null },
  "settlement": "direct",
  "payout_coin": "USDC", "payout_network": "polygon",
  …  full list in Order object
}

Alıcıyı her zaman checkout_url adresine yönlendirin. "Başka yöntem seç" bağlantısı istiyorsanız payment_page_url değerini saklayın — her zaman sayfamızı açar.

Alıcıyı doğrudan bir ödeme yöntemine gönderme

Her modda çalışır — API anahtarıyla, hesapsız, panel ödeme bağlantılarında ve /payment-links sayfasındaki kodsuz formda. provider belirtin, alıcı ödeme formumuzu görmeden doğrudan o sağlayıcıya (ör. PayPal) gider.

Yanıttaki routing ne olduğunu söyler: mode direct_to_provider veya payment_page; reason null, provider_offline, provider_below_minimum, provider_currency, provider_disabled veya project_routing (projenizin tercih edilen sağlayıcılarından seçildi).

GET /v1/providers?amount=&currency= herkese açık

Bu tutar ve para birimi için şu an kullanılabilen yöntemler: id, name, region, status, minimum_amount ve minimum_currency ile. Liste değişir — koda sabitlemek yerine sorgulayın.

* Minimumlar ve kullanılabilirlik ödeme ağından gelir ve değişir; karşılaştırmadan önce tutar minimumun para birimine çevrilir. Bazı sağlayıcılar alıcıdan hızlı, tek seferlik bir kimlik doğrulaması isteyebilir.

Para birimleri ve ne alırsınız

currency, alıcının ödediği para birimidir. Hangisi olursa olsun para sağlayıcı tarafından çevrilir ve Polygon üzerinde USDC olarak aktarılır.

GET /v1/currencies herkese açık

Diğer kodlar 400 döndürür. Sağlayıcı alıcıya fiyatı kendi para biriminde gösterebilir (ör. Revolut'ta EUR) — alıcı yine tutarınızın karşılığını öder. Bazı yöntemler yalnızca belirli para birimlerini kabul eder; bunlar /v1/providers?currency=… sonuçlarında yer almaz.

Ne nereye gelir

Gelen USDC'nin tam miktarı ödemeden sonra siparişin received_amount alanındadır; kuru sağlayıcı belirlediği için tahminden biraz farklı olabilir. Saklanan bakiyeler para birimleri arasında bozdurulabilir ve USDC, USDT, BTC, ETH ve diğerleri olarak çekilebilir — bkz. UTOPAY'de saklanır.

Ödeme durumu

GET /v1/payments/:id Bearer sk

Sipariş aynı yapıda. paid olmadığı sürece canlı durumu sağlayıcıda da kontrol ederiz, bu yüzden bir callback gecikse bile sorgulama güvenilirdir — bakiye yatırma ve webhook'unuz her durumda tam bir kez gerçekleşir. Yalnızca anahtarın kendi projesi görünür (aksi halde 404).

GET /v1/payments?limit=&offset=&status= Bearer sk

Projenin siparişleri, en yeniler önce. limit 1–500 (varsayılan 50), status = pending | paid | failed.

GET /api/checkout/:id/status herkese açık

Anahtarsız: { "id", "status", "amount", "currency", "updated_at" }. Hesapsız oluşturulan siparişler için kullanın. success_url ziyaretini ödeme kanıtı saymayın — durumu kontrol edin.

Kripto ödeme geçidi

Alıcı doğrudan kriptoyla öder — USDT, USDC, ETH, BTC ve diğerleri — siparişe özel benzersiz bir adrese. Gelen her şey zincir üstünde anında sizin cüzdanınıza aktarılır — veya settlement: "custody" ile UTOPAY bakiyenize yatırılır (cüzdan gerekmez). Ücret %1.5, alınan tutardan düşülür; blokzincir ücreti ayrıdır.

GET /v1/crypto/coins herkese açık

Her coin/ağ: ticker (coin olarak ilettiğiniz değer, ör. polygon/usdc, bep20/usdt, erc20/usdt, base/usdc, eth, btc, trc20/usdt), network, family (adres türü), minimum ve available ile. EVM ağları, Tron, Bitcoin, Solana, TON ve diğerleri çalışıyor; available: false ağın geçici olarak kullanılamadığı anlamına gelir.

POST /v1/crypto/payments Bearer sk · POST /v1/crypto/pay hesapsız

curl -X POST https://api.utopay.app/v1/crypto/pay \
  -H "content-type: application/json" \
  -d '{ "coin": "bep20/usdt", "amount": 100, "currency": "USD",
        "payout_address": "0xYourWallet0000000000000000000000000000000" }'
# → { "id": "ord_…", "kind": "crypto", "checkout_url": "https://api.utopay.app/pay/ord_…",
#     "crypto": { "coin": "bep20/usdt", "network": "BNB Smart Chain (BEP-20)", "symbol": "USDT",
#                 "address": "0x…", "amount_coin": 100.02, "minimum": 1.66, "detected": false, "underpaid": false } }

• Alıcıyı checkout_url adresine yönlendirin (tutar, ağ, adres, QR, canlı durum) — veya crypto.address ve crypto.amount_coin değerlerini kendi sayfanızda gösterin.
• Durumlar: pending (transfer görülür görülmez, onaylardan önce crypto.detected: true ile) → paid. İstenenden az gelirse (%1'den fazla eksik) durum underpaid, olay payment.underpaid olur — para zaten cüzdanınızdadır, kararı siz verin.
• Webhook'lar, GET /v1/payments/:id ve test anahtarları kart ödemelerindeki gibi çalışır. minimum altındaki veya başka coin/ağdaki transferler işlenmez — ödeme sayfası alıcıyı uyarır.

Entegrasyon örnekleri

Siparişi sunucunuzda oluşturun (tarayıcıda asla gizli anahtarla değil), alıcıyı checkout_url adresine yönlendirin ve siparişi webhook ile ödendi olarak işaretleyin. Adım adım kılavuz: web sitesinde kripto kabul etme; Tether için ağlar ve ticker'lar: USDT kabul etme.

const res = await fetch('https://api.utopay.app/v1/crypto/payments', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.UTOPAY_SK}`, 'content-type': 'application/json' },
  body: JSON.stringify({ coin: 'bep20/usdt', amount: 49.9, currency: 'EUR', description: 'Order #1042',
    success_url: 'https://shop.example/thanks', cancel_url: 'https://shop.example/cart' })
});
const order = await res.json();
if (!res.ok) throw new Error(order.error);
// save order.id with your order, then redirect the buyer
reply.redirect(order.checkout_url);

import os, requests

r = requests.post('https://api.utopay.app/v1/crypto/payments',
    headers={'Authorization': f'Bearer {os.environ["UTOPAY_SK"]}'},
    json={'coin': 'erc20/usdt', 'amount': 120, 'currency': 'USD', 'description': 'Invoice 77'},
    timeout=20)
order = r.json()
r.raise_for_status()
print(order['id'], order['checkout_url'], order['crypto']['address'], order['crypto']['amount_coin'])

$ch = curl_init('https://api.utopay.app/v1/crypto/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UTOPAY_SK'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['coin' => 'polygon/usdt', 'amount' => 25, 'currency' => 'USD']),
]);
$order = json_decode(curl_exec($ch), true);
header('Location: ' . $order['checkout_url']);

Doğrudan aktarım

Para asla bizde beklemez: her ödeme, USDC geldiği anda zincir üstünde bölünür.

• Etkinleştirme: panel → proje → Fonlar ve ödemeler → Doğrudan cüzdana, bir USDC (Polygon) adresi yapıştırın. Veya istek başına: "settlement": "direct".
• Her ödemede USDC alırsınız; üstüne geçmiş, istatistikler, webhook'lar ve Telegram bildirimleri. Çekilecek bir şey yok.
• Proje başına bir cüzdan — birden fazla cüzdan gerekiyorsa birden fazla proje oluşturun.

UTOPAY'de saklanır

USDC, UTOPAY platform cüzdanına gelir. paid olduğunda payınız dahili bakiyeye yatırılır — sonra tutar, bozdurur, takas eder veya çekersiniz.

• Etkinleştirme: Fonlar ve ödemeler → UTOPAY'de saklanır (cüzdan gerekmez), veya istek başına "settlement": "custody".
• Yatırılan: siparişin para biriminde amount × 95.5% (USD, EUR, GBP, CAD, INR, SEK); diğer para birimleri güncel kurla USD olarak. Tam bir kez yatırılır.
• Hesap başına tek bakiye: bu moddaki tüm projeler toplanır; hesap dökümü kaynak projeyi gösterir.

Çekim ağları: USDC_POLYGON, USDT_POLYGON, USDT_TRC20, USDT_ERC20, ETH, BTC, BNB, TRX. Tutar hemen ayrılır (pending); transferi UTOPAY ekibi gönderir, genellikle bir iş günü içinde (txid ile done). Reddedilen talepler iade edilir. Çekimler API anahtarıyla başlatılamaz.

Ödeme bağlantıları

Kod gerekmez: bir bağlantı oluşturun, sohbette veya e-postada gönderin, ödeme alın. Panel → proje → Ödeme bağlantıları → + Bağlantı.

• Tutar sabit veya boş — alıcı girer. Para birimi — listeden herhangi biri.
• Yöntem (isteğe bağlı): bir sağlayıcı sabitleyin. Sabit tutarda bağlantı alıcıyı doğrudan ona gönderir; serbest tutarda alıcı yalnızca tutar alanını ve "PayPal ile öde" düğmesini görür. Yöntem kullanılamıyorsa normal yöntem seçici gösterilir.
• Dönüş URL'si — ödemeden sonra alıcının gittiği yer. Tek kullanımlık bağlantılar ilk siparişten sonra used olur (yeniden açmak o siparişe götürür); tekrar kullanılabilir bağlantılar arşivlenene kadar çalışır.
• Fonlar projenin fon modunu izler. Bağlantı siparişleri geçmişte görünür ve API siparişleri gibi webhook tetikler.

Herkese açık bağlantı https://api.utopay.app/i/lnk_… şeklindedir. Hesap olmadan /payment-links sayfasındaki formu kullanın — aynı yöntem seçimiyle bir /v1/pay siparişi oluşturur.

Webhook'lar ve bildirimler

Hesapla. Bir siparişin durumu değiştiğinde UTOPAY onu HMAC-SHA256 ile imzalayarak projenin her endpoint'ine POST eder.

Kayıt: panel → Webhook'lar → + Endpoint, veya { "url": "https://you.com/hooks/utopay" } ile POST /api/merchants/:id/webhooks. whsec_… gizli anahtarı panelde gösterilir.

POST https://you.com/hooks/utopay
content-type: application/json
x-utopay-event: payment.succeeded
x-utopay-signature: t=1759660123,v1=<hex hmac-sha256>
user-agent: UTOPAY-Webhooks/1.0

{
  "event": "payment.succeeded",
  "created_at": 1759660123456,
  "data": { /* the Order object */ }
}

import crypto from 'node:crypto';
// use the RAW body, not re-serialised JSON
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const a = Buffer.from(v1 || ''), b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// raw body + x-utopay-signature header + your whsec_… secret
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_UTOPAY_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('UTOPAY_WHSEC'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'payment.succeeded') { /* mark $event['data']['id'] as paid */ }
http_response_code(200);

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t', ''), parts.get('v1', '')
    expected = hmac.new(secret.encode(), f'{t}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = t.isdigit() and abs(time.time() - int(t)) < 300
    return fresh and hmac.compare_digest(expected, v1)

• 10 sn içinde herhangi bir 2xx ile yanıt verin. Yeniden denemeler 30 sn, 2 dk, 15 dk, 1 sa, 6 sa sonra — 6 deneme. Teslimatlar panelde görünür.
• İdempotent olun — tekrarları data.id ile ayıklayın.
• Telegram: ödenen siparişler tutar, açıklama ve id ile sohbetinize gelir (Bildirimler).

Test modu

1. Bir test gizli anahtarı (utopay_sk_test_…) oluşturun ve POST /v1/payments çağrısını her zamanki gibi yapın — tüm doğrulamalar (para birimi, sağlayıcı) aynıdır.
2. checkout_url bir sandbox sayfasına (/sandbox/ord_test_…) yönlendirir. Simulate payment veya Simulate failure'a basın.
3. Webhook'lar ve Telegram, canlı ortamdaki gibi "is_test": true ile tetiklenir. Para hareket etmez, bakiye yatırılmaz.

Ekip, marka, yönlendirme

Ekip: e-postayla davet edin (Ekip). Roller admin, developer, finance, viewer; oluşturan owner'dır.

Marka: Ayarlar'da ad, logo, arka plan ve düğme rengi — ödeme sayfasına, bağlantı sayfalarına ve ödeme tamamlandı ekranına uygulanır.

Proje yönlendirmesi: Yönlendirme'de tercih edilen sağlayıcıları önceliğe göre sıralayın. provider olmadan yapılan API ödemelerinde çevrimiçi olan ve tutara ve para birimine uyan ilki kullanılır (routing.reason = "project_routing"); hiçbiri uymazsa alıcı sayfamızda seçer. Açıkça belirtilen provider her zaman önceliklidir.

Sipariş nesnesi

create/get/list tarafından ve webhook'ların içinde döndürülür.

Tüm herkese açık endpoint'ler

Ücretler

• %95.5 alırsınız — hesapla da hesapsız da, doğrudan ve saklanan modlarda, her para birimi ve yöntem için aynı. Kurulum veya aylık ücret yok.
• Büyük işletmeler bireysel oran alabilir — bize ulaşın. Her siparişin tam bölüşümü fees alanındadır.

Ortaklık programı

• 1. seviye: davet ettiğiniz işletmelerden ücretimizin %25'i; 2. seviye: onların davet ettiği işletmelerden %10.
• Her ödemede zincir üstünde Ortaklık'ta belirtilen ortaklık cüzdanına ödenir. Ücretimizden karşılanır — davet edilenler ekstra bir şey ödemez.

Hatalar

Her hata, uygun HTTP durumuyla birlikte { "error": "message" } şeklindedir.