wc-payment-gateway

WooCommerce payment gateway

A provider response is not automatically a paid order. Model captured, authorization-only, asynchronous pending, failed, refunded, and duplicate callback states explicitly.

Register the gateway

add_filter( 'woocommerce_payment_gateways', static function ( array $gateways ): array {
    $gateways[] = MyPlugin\Payment\Gateway::class;
    return $gateways;
} );

Register a class name so WooCommerce controls instantiation.

Minimal gateway class

namespace MyPlugin\Payment;

final class Gateway extends \WC_Payment_Gateway {
    public function __construct() {
        $this->id                 = 'myplugin_gateway';
        $this->method_title       = __( 'My Provider', 'myplugin' );
        $this->method_description = __( 'Accept payments through My Provider.', 'myplugin' );
        $this->has_fields         = false;
        $this->supports           = array( 'products', 'refunds' );

        $this->init_form_fields();
        $this->init_settings();

        $this->enabled     = $this->get_option( 'enabled', 'no' );
        $this->title       = $this->get_option( 'title', __( 'Card payment', 'myplugin' ) );
        $this->description = $this->get_option( 'description', '' );

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

    public function init_form_fields(): void {
        $this->form_fields = array(
            'enabled' => array(
                'title'   => __( 'Enable', 'myplugin' ),
                'type'    => 'checkbox',
                'label'   => __( 'Enable this payment method', 'myplugin' ),
                'default' => 'no',
            ),
            'title' => array(
                'title'   => __( 'Title', 'myplugin' ),
                'type'    => 'text',
                'default' => __( 'Card payment', 'myplugin' ),
            ),
            'api_key' => array(
                'title' => __( 'API key', 'myplugin' ),
                'type'  => 'password',
            ),
        );
    }

    public function process_payment( $order_id ) {
        $order = wc_get_order( $order_id );
        if ( ! $order instanceof \WC_Order ) {
            return array( 'result' => 'failure' );
        }

        try {
            $payment = $this->provider()->create_payment( array(
                'amount'          => wc_add_number_precision( $order->get_total(), false ),
                'currency'        => $order->get_currency(),
                'idempotency_key' => 'wc-' . $order->get_order_key(),
                'metadata'        => array( 'order_id' => $order->get_id() ),
            ) );
        } catch ( \Throwable $error ) {
            wc_get_logger()->error(
                'Payment provider request failed.',
                array(
                    'source'          => 'myplugin-gateway',
                    'order_id'        => $order->get_id(),
                    'exception_class' => get_class( $error ),
                )
            );
            wc_add_notice( __( 'The payment could not be processed. Please try again.', 'myplugin' ), 'error' );
            return array( 'result' => 'failure' );
        }

        $order->update_meta_data( '_myplugin_provider_payment_id', $payment->id );

        if ( 'captured' === $payment->status ) {
            if ( ! $order->payment_complete( $payment->transaction_id ) ) {
                return array( 'result' => 'failure' );
            }
        } elseif ( 'authorized' === $payment->status ) {
            // Authorization reserves funds; it is not necessarily a capture.
            $order->set_transaction_id( $payment->transaction_id );
            $order->update_status( 'on-hold', __( 'Payment authorized; capture pending.', 'myplugin' ) );
        } elseif ( 'pending' === $payment->status ) {
            $order->update_status( 'on-hold', __( 'Awaiting provider confirmation.', 'myplugin' ) );
        } else {
            $order->update_status( 'failed', __( 'The provider declined the payment.', 'myplugin' ) );
            wc_add_notice( __( 'The payment was declined. Try another payment method.', 'myplugin' ), 'error' );
            return array( 'result' => 'failure' );
        }

        if ( WC()->cart ) {
            WC()->cart->empty_cart();
        }

        return array(
            'result'   => 'success',
            'redirect' => $this->get_return_url( $order ),
        );
    }
}