WooCommerce'e Kripto Ödeme Ekleme: USDT ve TRX Rehberi (PHP)
WooCommerce kripto ödeme nasıl eklenir? mercanpay-php ile kendi ödeme yönteminizi yazın: fatura oluşturma, webhook, sipariş durumu ve kontrol listesi.
WooCommerce kripto ödeme eklemek, WordPress tabanlı mağazaların sık sorduğu bir konudur. En kolay yol hazır eklentimizdir: MercanPay WooCommerce eklentisini ücretsiz indirip WordPress panelinden birkaç dakikada kurabilirsiniz. Ödeme akışını kendiniz kontrol etmek ya da özel bir mağaza yapısına uyarlamak istiyorsanız, resmî mercanpay/mercanpay-php kütüphanesiyle küçük bir özel ödeme yöntemi yazmak da oldukça kolaydır. Bu rehberde bu yöntemin iskeletini adım adım kuruyoruz.
WooCommerce kripto ödeme akışı nasıl çalışacak?
Kuracağımız akış, MercanPay'in genel ödeme mantığıyla aynıdır:
- Müşteri ödeme sayfasında "Kripto (USDT / TRX)" yöntemini seçer.
- WooCommerce siparişi oluşturur, bizim ödeme yöntemimiz MercanPay'de bir fatura açar.
- Müşteri MercanPay ödeme sayfasına yönlendirilir, coinini seçer ve öder.
- Ödeme 20 blok onayıyla kesinleşince imzalı bir webhook mağazanıza gelir.
- Webhook doğrulanır ve sipariş "İşleniyor" durumuna geçer.
Siparişi tarayıcı yönlendirmesiyle değil, doğrulanmış webhook ile onaylayacağız. Bu, entegrasyonun en önemli kuralıdır.
Gereksinimler
- WooCommerce kurulu bir WordPress sitesi, PHP 8 veya üzeri
- Sunucuda Composer erişimi (ya da kütüphaneyi yerelde kurup eklenti klasörüyle yüklemek)
- Onaylanmış bir MercanPay satıcı hesabı ve
invoicesyetkili bir API anahtarı - Paneldeki Ayarlar sayfasında bulunan webhook imza sırrı (
whsec_…)
Hesabınız yoksa önce satıcı başvurusu yapın. Kütüphanenin temellerini PHP ile kripto ödeme entegrasyonu rehberimizde ayrıntılı anlattık.
1. Eklenti klasörünü hazırlayın
wp-content/plugins/mercanpay-gateway/ adında bir klasör oluşturun ve içinde kütüphaneyi kurun:
cd wp-content/plugins/mercanpay-gateway
composer require mercanpay/mercanpay-php
API anahtarını ve imza sırrını koda yazmayın. wp-config.php içinde sabit olarak tanımlamak basit ve güvenli bir yoldur:
define('MERCANPAY_API_KEY', 'mp_...');
define('MERCANPAY_WEBHOOK_SECRET', 'whsec_...');
2. Ödeme yöntemi sınıfını yazın
WooCommerce'de her ödeme yöntemi WC_Payment_Gateway sınıfından türetilir. Aşağıdaki iskelet, işin özünü gösterir:
<?php
/*
* Plugin Name: MercanPay Crypto Gateway (custom)
*/
require __DIR__ . '/vendor/autoload.php';
use MercanPay\MercanPay;
use MercanPay\MercanPayException;
add_action('plugins_loaded', function () {
class WC_Gateway_MercanPay extends WC_Payment_Gateway
{
public function __construct()
{
$this->id = 'mercanpay';
$this->method_title = 'MercanPay (USDT / TRX)';
$this->title = 'Kripto ile öde (USDT / TRX · TRC20)';
$this->description = 'Ödeme sayfasında TRX ya da USDT seçebilirsiniz.';
$this->has_fields = false;
$this->init_form_fields();
$this->init_settings();
}
public function process_payment($order_id)
{
$order = wc_get_order($order_id);
$attempt = (int) $order->get_meta('_mercanpay_attempt') + 1;
$zp = new MercanPay('https://mercanpay.com', MERCANPAY_API_KEY);
try {
$invoice = $zp->createUsdInvoice(wc_format_decimal($order->get_total(), 2), [
'order_id' => 'wc-' . $order->get_id() . '-' . $attempt,
'description' => 'Sipariş #' . $order->get_order_number(),
'success_url' => $this->get_return_url($order),
'return_url' => wc_get_checkout_url(),
'callback_url' => WC()->api_request_url('mercanpay'),
'metadata' => ['wc_order' => $order->get_id()],
]);
} catch (MercanPayException $e) {
wc_add_notice('Ödeme sayfası açılamadı, lütfen tekrar deneyin.', 'error');
return ['result' => 'failure'];
}
$order->update_meta_data('_mercanpay_attempt', $attempt);
$order->update_meta_data('_mercanpay_invoice', $invoice['id']);
$order->update_status('pending', 'MercanPay faturası oluşturuldu.');
$order->save();
return ['result' => 'success', 'redirect' => $invoice['payment_url']];
}
}
add_filter('woocommerce_payment_gateways', function ($methods) {
$methods[] = 'WC_Gateway_MercanPay';
return $methods;
});
});
Bu kodda dikkat edilmesi gereken birkaç nokta var:
- Tutar metin olarak gider.
wc_format_decimalile iki ondalıklı bir metin üretiyoruz; float kullanmayın. - Mağaza para birimi.
createUsdInvoicetutarı USD olarak kabul eder. Mağazanız farklı bir para biriminde fiyatlıyorsa, fatura oluşturmadan önce tutarı kendi belirlediğiniz kurla USD'ye çevirmeniz gerekir. - Deneme numarası. Aynı
order_idile yapılan istek mevcut faturayı döndürür, süresi dolmuş olsa bile. Müşteri süre dolduktan sonra tekrar "Öde" derse yeni bir fatura gerekir; bu yüzden order_id'ye bir deneme eki (-1,-2) koyuyoruz. Mantığını order_id ile fatura sipariş eşleştirme yazımızda anlattık. - Minimum tutar. Minimum fatura 10 $'dır. Daha düşük sepetlerde bu yöntemi gizlemek için
is_available()metodunu geçersiz kılabilirsiniz.
process_payment içinde adım adım neler oluyor?
Kod kısa ama her satırın bir görevi var:
- Deneme sayacı artırılır. Siparişe kaydedilen
_mercanpay_attemptdeğeri bir artırılır. Böylece aynı sipariş için yapılan her yeni ödeme girişimi kendi faturasını alır. - Fatura oluşturulur.
createUsdInvoiceçağrısı sepet tutarını USD olarak gönderir. Müşteri ödeme sayfasında TRX ya da USDT seçer ve kur o anda kilitlenir. - Yönlendirme adresleri verilir.
success_urlWooCommerce'in teşekkür sayfasıdır; müşteri ödemeden sonra buraya döner.return_urlise ödeme sayfasındaki "Mağazaya dön" butonunun hedefidir, burada müşteriyi mağazanızın ödeme (checkout) adımına geri götürür. - Webhook adresi faturaya bağlanır.
callback_url, bu faturanın olaylarının paneldeki Webhook URL'ine ek olarak bu adrese de gönderilmesini sağlar. - Fatura kimliği siparişe yazılır.
_mercanpay_invoicealanı, webhook geldiğinde olayın doğru faturaya ait olup olmadığını kontrol etmek için kullanılır. - Müşteri yönlendirilir. WooCommerce, dönen
payment_urladresine yönlendirme yapar.
Fatura oluşturma başarısız olursa MercanPayException yakalanır ve müşteriye sade bir hata mesajı gösterilir. Hatanın ayrıntısını (getErrorCode() ve getMessage()) kendi günlüğünüze yazmanız, sorunu sonradan anlamanızı kolaylaştırır.
3. Webhook uç noktasını ekleyin
callback_url olarak verdiğimiz WC()->api_request_url('mercanpay') adresi, WooCommerce'in woocommerce_api_mercanpay kancasını tetikler. Webhook'u burada karşılıyoruz:
add_action('woocommerce_api_mercanpay', function () {
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_MERCANPAY_SIGNATURE'] ?? '';
if (!MercanPay::verifyWebhook(MERCANPAY_WEBHOOK_SECRET, $body, $header)) {
status_header(401);
exit;
}
$event = json_decode($body, true);
$invoice = $event['data']['invoice'] ?? [];
$order = wc_get_order((int) ($invoice['metadata']['wc_order'] ?? 0));
if ($order && $order->get_meta('_mercanpay_invoice') === ($invoice['id'] ?? '')) {
switch ($event['type']) {
case 'invoice.paid':
case 'invoice.overpaid':
if (!$order->is_paid()) {
$order->payment_complete($invoice['id']);
$order->add_order_note('MercanPay: ' . $invoice['paid_amount'] . ' ' . $invoice['token'] . ' alındı.');
}
break;
case 'invoice.partial':
$order->update_status('on-hold', 'MercanPay: eksik ödeme, kalan ' . $invoice['remaining_amount']);
break;
case 'invoice.expired':
$order->add_order_note('MercanPay: fatura süresi doldu.');
break;
}
}
status_header(200);
exit;
});
Önemli ayrıntılar:
- Ham gövdeyi doğrulayın. İmza, JSON çözümlenmeden önceki ham gövde üzerinden hesaplanır. Ayrıntılar webhook imzası doğrulama yazımızda.
- Faturayı eşleştirin. Olaydaki fatura kimliğinin siparişe kayıtlı son fatura olduğunu kontrol ediyoruz. Böylece eski bir denemenin olayı yeni siparişi yanlış etkilemez.
- İdempotent olun.
is_paid()kontrolü sayesinde aynı olay iki kez gelse bile sipariş bir kez işlenir. - Hızlı yanıt verin. 10 saniye içinde 2xx dönmezseniz webhook yeniden denenir. E-posta gönderimi gibi ağır işleri arka plana bırakın.
Süresi dolmuş bir faturaya sonradan gelen ödeme de bakiyenize yazılır ve invoice.paid olayında data.payment.late alanı true olur. Bu durumda siparişi nasıl ele alacağınız sizin iş kuralınızdır. Ayrıntılar eksik, fazla ve geç ödemeler yazısında.
4. Test edin
Ayrı bir test ortamı yoktur; bu yüzden kontrollü bir canlı test yapın:
- Panelde Webhook'lar sayfasındaki "Test gönder" butonuyla
test.pingolayını gönderin ve uç noktanızın 200 döndüğünü teslimat geçmişinde görün. (Bu olayda sipariş bilgisi yoktur; kodunuz onu sessizce atlamalıdır.) - Minimum tutarda (10 $) gerçek bir test siparişi verip USDT ile ödeyin.
- Siparişin "İşleniyor" durumuna geçtiğini ve sipariş notunu kontrol edin.
Sık yapılan hatalar
- Siparişi teşekkür sayfasında onaylamak:
success_urladresine eklenen parametreler taklit edilebilir. Sipariş durumu yalnızca webhook ile değişmeli. - Ham gövde yerine çözümlenmiş veriyi doğrulamak: İmza,
php://inputile okunan ham gövde üzerinden hesaplanır. Veriyi önce çözümleyip yeniden kodlarsanız imza tutmaz. - Her denemede aynı order_id'yi kullanmak: Süresi dolmuş fatura geri döner ve müşteri ödeme yapamaz. Deneme ekini unutmayın.
- Webhook'ta yavaş işler yapmak: Stok senkronizasyonu ya da e-posta gönderimi 10 saniyeyi aşarsa olay yeniden denenir. Bu işleri arka plana alın.
- Önbellek ve güvenlik eklentileri: Bazı eklentiler dışarıdan gelen POST isteklerini engelleyebilir. Webhook adresinizin erişilebilir olduğunu teslimat geçmişinden kontrol edin.
Canlıya geçmeden önce kontrol listesi
- API anahtarı ve imza sırrı kodda değil,
wp-config.phpya da ortam değişkeninde. - Webhook adresi HTTPS ve imza doğrulaması açık.
- Siparişler yalnızca webhook ile "ödendi" oluyor, teşekkür sayfası ile değil.
invoice.partialveinvoice.overpaidele alınıyor.- Mağaza para birimi USD değilse çevrim doğru yapılıyor.
- Uçtan uca küçük bir gerçek ödemeyle test edildi.
Sık sorulan sorular
Hazır bir WooCommerce eklentisi var mı?
Evet. MercanPay WooCommerce eklentisi ücretsizdir; indirip WordPress panelinden yükleyebilir, API anahtarınızı girip hemen kullanmaya başlayabilirsiniz. Bu rehberdeki yapı, akışı kendiniz özelleştirmek istediğinizde işinize yarar.
Müşteri ödeme sayfasında hangi coinleri görür?
Varsayılan olarak TRX ve USDT (TRC20). Yalnızca USDT kabul etmek için fatura seçeneklerine 'tokens' => ['USDT'] ekleyin.
Laravel ya da başka bir PHP çatısı kullanıyorum.
Mantık aynıdır. Laravel için Laravel kripto ödeme entegrasyonu yazımıza bakabilirsiniz.
İade yapabilir miyim?
Kripto ödemelerde otomatik iade yoktur. İade, bakiyenizden müşterinin bildirdiği adrese yaptığınız bir çekimdir. Ayrıntılar kripto ödeme iadesi nasıl yapılır yazısında.
MercanPay ile başlayın
WooCommerce kripto ödeme yönteminizi birkaç dosyayla kurabilirsiniz. Satıcı hesabınızı açın, API anahtarınızı alın ve tüm alanlar için dokümantasyonu inceleyin.
