Pembayaran kripto di WordPress

WordPress tidak punya cara bawaan untuk menerima kripto, dan Qvard belum punya plugin WordPress siap pakai. Yang ada adalah API sederhana, dan WordPress sangat mampu berkomunikasi dengan API semacam itu. Panduan ini menunjukkan cara menghubungkan toko WooCommerce ke Qvard dengan dua potongan kode kecil, dan apa yang perlu diperiksa saat tidak berfungsi.

Plugin atau kode sendiri: pilihan yang jujur

Di WordPress, hal pertama yang dicari orang adalah plugin, dan itu naluri yang wajar: pasang, tempel kunci, selesai. Begini situasinya sekarang.

Qvard belum punya plugin WordPress atau WooCommerce. Integrasi lewat API. Kami lebih memilih mengatakannya daripada menyuruh Anda berburu plugin yang tidak ada.
Plugin pihak ketiga untuk gateway kripto lain tidak akan terhubung ke Qvard. Setiap plugin berbicara dengan API gateway-nya sendiri.
Menulis kode sendiri tidak besar. Satu permintaan membuat pembayaran dan satu endpoint menerima hasilnya. Developer WordPress bisa menulisnya dalam satu atau dua jam, dan Anda mengendalikan persis apa yang terjadi pada pesanan.

Jika Anda ingin pengaturan tanpa kode, Qvard belum sampai di sana. Jika Anda punya developer, atau bisa membayar satu jam kerja, lanjutkan membaca.

Cara kerja integrasi

Alur untuk satu pesanan WooCommerce:

Saat checkout, pelanggan memilih «Bayar dengan kripto». Kode Anda membuat pembayaran lewat API Qvard, memakai nomor pesanan WooCommerce sebagai id pembayaran.
Qvard mengembalikan redirectUrl. Anda mengarahkan pelanggan ke halaman yang dihosting itu, tempat ia memilih aset dan jaringan dan membayar dari dompetnya sendiri.
Saat pembayaran selesai, Qvard memanggil sebuah endpoint di situs Anda.
Endpoint menemukan pesanan lewat id dan menandainya dibayar, sehingga WooCommerce mengirim email standarnya dan memindahkan pesanan ke pemrosesan.

Situs WordPress Anda tidak pernah membuat alamat atau memantau blockchain. Dua potongan yang Anda tulis adalah panggilan yang membuat pembayaran dan endpoint yang menerima hasilnya.

Potongan 1: membuat pembayaran

Di WordPress, gunakan wp_remote_post untuk memanggil https://api.qvard.com/api/v1/payment dengan kunci API Anda di header Authorization: Bearer dan JSON: id (nomor pesanan sebagai string) dan price (jumlah dalam dolar AS). Panggilan yang berhasil mengembalikan HTTP 201 dengan redirectUrl.

Contoh di bawah melakukan persis itu untuk pesanan WooCommerce. Simpan kunci di wp-config.php sebagai konstanta, bukan di tema dan bukan di opsi database tempat plugin dan ekspor bisa membocorkannya.

Dua detail WooCommerce yang penting:

Mata uang. Harga dikirim dalam dolar AS. Jika toko Anda memakai mata uang lain, konversikan total pesanan ke dolar sebelum panggilan, atau pelanggan akan ditagih jumlah yang salah.
Percobaan ulang. Mengirim id yang sama untuk metode pembayaran yang sama mengembalikan pembayaran yang ada, jadi klik ganda atau permintaan yang diulang tidak membuat pembayaran kedua.

Hubungkan ini ke metode pembayaran kustom, atau ke langkah checkout yang menangani pilihan «Bayar dengan kripto», lalu arahkan pelanggan ke URL yang dikembalikan.

PHPqvard-create-payment.php

<?php
// Create a Qvard payment for a WooCommerce order and return the page to send the customer to.
// QVARD_API_KEY is defined in wp-config.php, never in a theme or a public repository.
function qvard_create_payment( WC_Order $order ) {
    $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(),   // matched again in the webhook
            'price' => (float) $order->get_total(), // US dollars
        ) ),
    ) );

    if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
        return null;
    }

    $data = json_decode( wp_remote_retrieve_body( $response ), true );
    return isset( $data['redirectUrl'] ) ? $data['redirectUrl'] : null;
}

Potongan 2: menerima webhook

Daftarkan rute REST di WordPress dan simpan alamatnya di proyek Qvard Anda sebagai callback URL, misalnya https://your-site.com/wp-json/qvard/v1/webhook. Saat pembayaran selesai, Qvard mengirim POST dengan id yang Anda berikan dan status pembayaran, ditandatangani di header X-Qvard-Signature.

Tiga aturan untuk endpoint:

Verifikasi tanda tangan. Periksa X-Qvard-Signature (HMAC-SHA256 dengan kunci rahasia Anda) memakai SDK dan tolak yang tidak cocok.
Tandai pesanan dibayar hanya saat statusnya completed. Pelanggan yang kembali ke situs Anda bukan bukti pembayaran, dan status partial berarti ia mengirim kurang dari yang diminta.
Balas persis dengan HTTP 200. Qvard menganggap status lain sebagai kegagalan dan mencoba lagi (lima percobaan dalam sekitar enam menit), dan tidak mengikuti pengalihan. Karena percobaan ulang, handler harus aman bila dijalankan dua kali; is_paid() pada contoh mencegah penyelesaian ganda.

Lebih lanjut soal keamanan di cara mengamankan webhook pembayaran kripto.

PHPqvard-webhook.php

<?php
// Webhook endpoint: https://your-site.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 ) );

            if ( $order && 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete();
            }

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

Apa yang biasanya rusak di WordPress

Sebagian besar integrasi yang gagal di WordPress berasal dari lingkungan, bukan kode:

Webhook tidak pernah tiba. Plugin keamanan, firewall, atau halaman «segera hadir» memblokir permintaan POST yang tidak dikenal. Izinkan rute itu dan uji dari luar jaringan Anda.
Rute mengembalikan 404. Permalink cantik dimatikan atau file plugin tidak dimuat. Buka rute di browser; 401 atau 405 berarti rute ada, 404 berarti tidak.
Cache halaman. Pastikan plugin cache dan CDN Anda tidak men-cache atau menulis ulang permintaan /wp-json/.
Pesanan dibayar dua kali. Handler tidak idempoten. Periksa is_paid() sebelum menyelesaikan.
Jumlah salah. Mata uang toko bukan dolar AS dan tidak ada konversi.
Respons lambat. Plugin berat yang terkait penyelesaian pesanan bisa menunda jawaban Anda. Balas 200 dengan cepat dan lakukan pekerjaan lambat sesudahnya.

Setelah membayar, pelanggan kembali ke situs Anda dengan sendirinya karena URL pengembalian belum tersedia. Beri mereka halaman pesanan yang menampilkan status sebenarnya, bukan halaman terima kasih yang mengasumsikan sukses.

Uji sebelum meluncur

Buka faktur demo untuk melihat halaman pembayaran yang akan diterima pelanggan Anda. Lalu:

Buat pembayaran dari pesanan uji dan periksa bahwa Anda menerima redirectUrl.
Bayar sejumlah kecil uang sungguhan dan pastikan webhook tiba dan pesanan berstatus dibayar.
Buat endpoint gagal sekali, periksa bahwa Qvard mencoba lagi, dan pesanan tidak diselesaikan dua kali.
Tarik sejumlah kecil dari saldo Anda ke dompet.

Belum ada sandbox terpisah, jadi gunakan jumlah kecil sungguhan. Endpoint dan field ada di dokumentasi developer, dan ikhtisar integrasi menunjukkan apa lagi yang terhubung hari ini.

Berapa biaya menjalankannya

Tidak ada biaya langganan. Per pembayaran, komisi bersifat individual untuk proyek Anda dan menurut halaman harga dimulai dari 1% serta bisa turun hingga 0,1%; lihat harga untuk ketentuan terkini. Penarikan ke dompet Anda sendiri hanya dikenai biaya jaringan. Penarikan ke rekening bank dalam fiat tidak tersedia.

Satu-satunya biaya yang perlu direncanakan adalah waktu pengembangan: sedikit sekali, dan sedikit pemeliharaan saat WordPress atau WooCommerce mengubah cara metode pembayaran didaftarkan.

FAQ

Apakah ada plugin Qvard untuk WordPress atau WooCommerce?

Belum. Saat ini integrasi lewat API: satu permintaan membuat pembayaran dan satu webhook menerima hasilnya. Developer WordPress bisa menambahkan keduanya ke toko dalam satu atau dua jam.

Bisakah saya memakai plugin kripto yang dibuat untuk gateway lain?

Tidak. Setiap plugin berbicara dengan gateway-nya sendiri dan tidak bisa terhubung ke Qvard. Anda memerlukan kode sendiri yang memanggil API Qvard.

Harga di toko saya bukan dalam dolar AS. Apa yang harus dilakukan?

Harga dikirim ke Qvard dalam dolar AS, jadi konversikan total pesanan sebelum membuat pembayaran. Pelanggan kemudian membayar setaranya dalam aset yang dipilih, dengan kurs yang dikunci selama satu jam.

Webhook tidak sampai ke situs saya. Mengapa?

Biasanya plugin keamanan, firewall, atau halaman pemeliharaan memblokir permintaan, atau rute REST belum terdaftar. Periksa bahwa rute menjawab dari luar jaringan Anda dan mengembalikan tepat HTTP 200 untuk permintaan yang valid.