Pembayaran kripto di WooCommerce

WooCommerce punya titik ekstensi yang rapi untuk metode pembayaran, dan Qvard hanya membutuhkan dua hal darinya: panggilan yang membuat pembayaran saat pelanggan membayar, dan endpoint yang menyelesaikan pesanan saat pembayaran selesai. Belum ada plugin Qvard siap pakai, jadi panduan ini menunjukkan kode kustomnya, bagian demi bagian, beserta detail WooCommerce yang biasanya bermasalah.

Sebelum memulai

Anda membutuhkan akun Qvard dengan proyek, kunci API, dan callback URL yang tersimpan di proyek. Di sisi WooCommerce Anda perlu cara menambahkan kode, idealnya plugin kustom kecil atau plugin code-snippets, bukan file tema yang hilang pada pembaruan tema berikutnya.

Dua keputusan di awal:

Mata uang. Qvard menetapkan harga pembayaran dalam dolar AS. Gateway di panduan ini menerima pesanan dalam USD dan menolak mata uang lain, yang merupakan default aman. Jika toko Anda menjual dalam mata uang lain, konversikan total pesanan ke dolar sebelum membuat pembayaran dan sampaikan di checkout.
Di mana kunci disimpan. Definisikan kunci API sebagai konstanta di wp-config.php (define( 'QVARD_API_KEY', '...' );), bukan di pengaturan database tempat ekspor dan plugin lain bisa membacanya.

Jika Anda hanya butuh gagasan dasarnya tanpa kelas WooCommerce, mulailah dengan pembayaran kripto di WordPress.

Bagian-bagiannya dan cara pesanan bergerak

Tiga bagian membentuk integrasi:

Kelas gateway pembayaran yang muncul di checkout WooCommerce sebagai «Bayar dengan kripto».
Panggilan ke Qvard di dalam gateway, yang membuat pembayaran untuk pesanan dan mengembalikan alamat halaman pembayaran yang dihosting.
Endpoint webhook yang dipanggil Qvard saat pembayaran selesai.

Pesanan bergerak seperti ini: pelanggan memilih metode dan menekan bayar; gateway membuat pembayaran Qvard, menempatkan pesanan ditahan dan mengarahkan pelanggan ke halaman pembayaran; pelanggan membayar dari dompet; Qvard memanggil endpoint Anda; endpoint menyelesaikan pesanan dan WooCommerce mengirim email biasa lalu memajukannya. id pembayaran yang Anda kirim ke Qvard adalah nomor pesanan WooCommerce, dan begitulah webhook menemukan pesanan kembali.

Kelas gateway

Kelas ini memperluas WC_Payment_Gateway. Konstruktornya menetapkan id dan judul metode serta memuat pengaturan, dan process_payment mengerjakan tugasnya. Ia menolak pesanan non-USD, lalu mengirim satu POST ke https://api.qvard.com/api/v1/payment dengan kunci Anda di header Authorization: Bearer dan JSON: id (nomor pesanan sebagai string) dan price (total dalam dolar AS). Respons 201 membawa redirectUrl.

Jika berhasil, gateway menyimpan id pembayaran Qvard pada pesanan, mengatur status on-hold («menunggu pembayaran»), mengosongkan keranjang, dan mengembalikan redirectUrl sebagai pengalihan. Jika gagal, ia menambahkan pemberitahuan error dan mengembalikan failure, sehingga pelanggan tetap di halaman checkout dan bisa memilih metode lain.

Mengirim id yang sama untuk metode pembayaran yang sama mengembalikan pembayaran yang ada, jadi pelanggan yang menekan tombol dua kali tidak membuat dua pembayaran.

PHPqvard-gateway.php

<?php
// A minimal WooCommerce payment method that sends the customer to the Qvard payment page.
add_filter( 'woocommerce_payment_gateways', function ( $gateways ) {
    $gateways[] = 'WC_Gateway_Qvard';
    return $gateways;
} );

add_action( 'plugins_loaded', function () {
    if ( ! class_exists( 'WC_Payment_Gateway' ) ) {
        return;
    }

    class WC_Gateway_Qvard extends WC_Payment_Gateway {
        public function __construct() {
            $this->id                 = 'qvard';
            $this->method_title       = 'Qvard (crypto)';
            $this->method_description = 'Accept USDT and other crypto through Qvard.';
            $this->has_fields         = false;

            $this->init_form_fields();
            $this->init_settings();
            $this->title = $this->get_option( 'title', 'Pay with crypto' );

            add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
        }

        public function init_form_fields() {
            $this->form_fields = array(
                'enabled' => array( 'title' => 'Enable', 'type' => 'checkbox', 'default' => 'no' ),
                'title'   => array( 'title' => 'Title', 'type' => 'text', 'default' => 'Pay with crypto' ),
            );
        }

        public function process_payment( $order_id ) {
            $order = wc_get_order( $order_id );

            // Qvard prices payments in US dollars: refuse other shop currencies instead of charging a wrong amount.
            if ( 'USD' !== $order->get_currency() ) {
                wc_add_notice( 'Crypto payment is available for orders in USD only.', 'error' );
                return array( 'result' => 'failure' );
            }

            $response = wp_remote_post( 'https://api.qvard.com/api/v1/payment', array(
                'timeout' => 15,
                'headers' => array( 'Authorization' => 'Bearer ' . QVARD_API_KEY, 'Content-Type' => 'application/json' ),
                'body'    => wp_json_encode( array( 'id' => (string) $order->get_id(), 'price' => (float) $order->get_total() ) ),
            ) );

            if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
                wc_add_notice( 'Could not start the payment. Please try again.', 'error' );
                return array( 'result' => 'failure' );
            }

            $data = json_decode( wp_remote_retrieve_body( $response ), true );
            if ( empty( $data['redirectUrl'] ) ) {
                wc_add_notice( 'Could not start the payment. Please try again.', 'error' );
                return array( 'result' => 'failure' );
            }

            $order->update_meta_data( '_qvard_payment_id', sanitize_text_field( $data['id'] ?? '' ) );
            $order->update_status( 'on-hold', 'Waiting for the crypto payment.' );
            WC()->cart->empty_cart();

            return array( 'result' => 'success', 'redirect' => $data['redirectUrl'] );
        }
    }
} );

Webhook yang menyelesaikan pesanan

Daftarkan rute REST dan simpan alamatnya di proyek Qvard Anda sebagai callback URL. Saat pembayaran selesai, Qvard mengirim POST dengan id dan status, ditandatangani di header X-Qvard-Signature. Handler pada contoh:

memverifikasi tanda tangan (HMAC-SHA256 dengan kunci rahasia Anda) memakai SDK Qvard dan menjawab 401 jika tidak cocok;
menemukan pesanan lewat id dan mengabaikan pesanan yang tidak ada atau tidak dibayar dengan gateway ini, tetap menjawab 200 agar Qvard berhenti mengulang;
memanggil payment_complete() hanya pada status completed dan hanya jika pesanan belum dibayar, sehingga aman dijalankan dua kali;
menjawab tepat HTTP 200. Status lain, timeout, atau pengalihan dianggap pengiriman gagal dan diulang, lima percobaan dalam sekitar enam menit.

Izinkan rute itu di plugin keamanan atau firewall mana pun dan pastikan cache tidak menyentuh /wp-json/. Aturan yang lebih luas ada di cara mengamankan webhook pembayaran kripto.

PHPqvard-webhook.php

<?php
// Callback URL to save in the Qvard project: https://your-shop.com/wp-json/qvard/v1/webhook
add_action( 'rest_api_init', function () {
    register_rest_route( 'qvard/v1', '/webhook', array(
        'methods'             => 'POST',
        'permission_callback' => '__return_true', // authenticated below by the X-Qvard-Signature header
        'callback'            => function ( WP_REST_Request $request ) {
            try {
                $payload = ( new Qvard\Qvard( QVARD_API_KEY ) )->webhooks->constructEvent( $request->get_body(), $request->get_header( 'x-qvard-signature' ), QVARD_API_KEY );
            } catch ( \Exception $e ) {
                return new WP_REST_Response( null, 401 );
            }
            $order   = wc_get_order( (int) ( $payload['id'] ?? 0 ) );

            // Unknown order or not ours: nothing to retry, answer 200.
            if ( ! $order || 'qvard' !== $order->get_payment_method() ) {
                return new WP_REST_Response( null, 200 );
            }

            if ( 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete( (string) $order->get_meta( '_qvard_payment_id' ) );
                $order->add_order_note( 'Qvard: payment completed.' );
            }

            return new WP_REST_Response( null, 200 ); // must be exactly 200
        },
    ) );
} );

Detail WooCommerce yang menggigit

Stok. WooCommerce mengurangi stok saat pesanan masuk ke diproses atau ditahan, jadi pesanan kripto yang belum dibayar dapat menahan stok. Batalkan pesanan ditahan yang kedaluwarsa setelah periode pilihan Anda dengan tugas terjadwal sendiri (pengaturan tahan stok WooCommerce berlaku untuk pesanan menunggu pembayaran, bukan yang ditahan); jika tidak, stok tetap tercadangkan.
Pembayaran sebagian. Jika yang tiba kurang dari jumlah penuh, status pembayaran partial dan webhook penyelesaian tidak dikirim. Pesanan tetap ditahan; tambahkan catatan, minta sisanya dari pelanggan, atau batalkan dan kembalikan dana.
Pengembalian dana. Pembayaran kripto tidak bisa ditarik kembali. Buat catatan pengembalian di WooCommerce untuk pembukuan, tetapi kirim uangnya sendiri ke alamat yang diberikan pelanggan.
Email pesanan. Email «ditahan» keluar saat pesanan dibuat; pastikan teksnya memberi tahu pelanggan bahwa pembayaran masih menunggu dan di mana membayar.
Kembali ke situs. URL kembali setelah pembayaran belum tersedia, jadi pelanggan kembali ke toko Anda sendiri. Halaman pesanan standar menampilkan status sebenarnya, yang sudah benar.
Checkout blok. Checkout berbasis blok WooCommerce juga memerlukan gateway yang terdaftar untuk blok; uji metode ini di checkout yang benar-benar Anda gunakan.

Uji sebelum meluncur

Buka faktur demo untuk melihat halaman pembayaran yang akan diterima pelanggan Anda.
Buat pesanan uji dengan metode kripto dan periksa bahwa Anda dialihkan ke halaman pembayaran dan pesanan berstatus ditahan.
Bayar sejumlah kecil uang sungguhan dan pastikan webhook tiba dan pesanan menjadi diproses.
Buat endpoint gagal sekali, pastikan Qvard mengulang dan pesanan tidak diselesaikan dua kali.
Tarik sejumlah kecil dari saldo Anda ke dompet agar tahu seluruh jalurnya berfungsi.

Belum ada sandbox terpisah, jadi gunakan jumlah kecil yang nyata.

Biayanya dan apa yang siap

Tidak ada biaya langganan untuk gateway. Komisi bersifat individual untuk proyek Anda dan menurut halaman harga dimulai dari 1% serta bisa turun hingga 0,1%. Dana berada di saldo Qvard Anda dan Anda menariknya ke dompet sendiri dengan biaya jaringan; penarikan ke rekening bank dalam fiat tidak tersedia.

Qvard bekerja lewat API, jadi integrasi membutuhkan developer dan pengujian; belum ada plugin WooCommerce siap pakai, dan tautan pembayaran serta sandbox terpisah masih dalam pengembangan. API-nya dijelaskan di API pembayaran kripto untuk developer dan sisi toko di pembayaran kripto untuk e-commerce.

FAQ

Apakah ada plugin Qvard untuk WooCommerce?

Belum. Integrasinya lewat API: kelas gateway yang membuat pembayaran dan webhook yang menyelesaikan pesanan. Kode di panduan ini adalah titik awal untuk developer.

Toko saya memakai euro. Apakah pelanggan tetap bisa membayar dengan kripto?

Qvard menetapkan harga pembayaran dalam dolar AS. Konversikan total pesanan ke dolar sebelum membuat pembayaran dan beri tahu pelanggan jumlah dalam dolar di checkout; gateway pada contoh menolak pesanan non-USD sebagai default aman.

Kapan pesanan menjadi dibayar?

Saat webhook tiba dengan status completed. Pelanggan yang kembali ke toko bukan bukti pembayaran, dan status partial berarti yang tiba kurang dari yang diminta.

Bagaimana jika situs saya mati saat pembayaran selesai?

Notifikasi diulang lima kali dalam sekitar enam menit. Setelah itu, kirim ulang untuk pembayaran itu dari panel Qvard; handler aman bila dijalankan dua kali.