Payment Gateway Integration

WB Ad Manager Pro ships with four built-in payment gateways (Stripe, PayPal, Razorpay, and WooCommerce) plus manual/bank transfer support. This guide covers how to work with the Payment Manager, build custom gateways, and understand the wallet’s idempotency protections that prevent duplicate charges.

Payment Manager

The Payment_Manager handles all payment processing through a unified interface:

use WBAM_Pro\Modules\Payments\Payment_Manager;

$manager = Payment_Manager::get_instance();

// Get available gateways
$gateways = $manager->get_gateways();

// Create payment
$payment_id = $manager->create_payment( array(
    'advertiser_id' => $advertiser_id,
    'amount'        => 100.00,
    'currency'      => 'USD',
    'gateway'       => 'stripe',
    'description'   => 'Wallet credit',
) );

// Process payment
$result = $manager->process( $payment_id, $gateway_data );

// Verify payment
$verified = $manager->verify_payment( $gateway_id, $payment_id, $verification_data );

Creating a Custom Gateway

Implement the Payment_Gateway_Interface to add your own payment provider:

use WBAM_Pro\Modules\Payments\Payment_Gateway_Interface;

class My_Gateway implements Payment_Gateway_Interface {

    public function get_id() {
        return 'my_gateway';
    }

    public function get_label() {
        return __( 'My Payment Gateway', 'my-plugin' );
    }

    public function is_available() {
        // Check if gateway is configured
        return ! empty( get_option( 'my_gateway_api_key' ) );
    }

    public function create_checkout( $amount, $data ) {
        // Create checkout session
        return array(
            'checkout_url' => 'https://gateway.com/checkout/xxx',
            'session_id'   => 'sess_xxx',
        );
    }

    public function verify_payment( $payment_id ) {
        // Verify payment status
        return true; // or false
    }

    public function process_webhook( $event ) {
        // Handle webhook event
        return array(
            'success' => true,
            'payment_id' => $payment_id,
        );
    }

    public function render_settings() {
        // Render admin settings fields
    }
}

// Register gateway
add_filter( 'wbam_pro_payment_gateways', function( $gateways ) {
    $gateways['my_gateway'] = new My_Gateway();
    return $gateways;
} );

Wallet API

The wallet system uses atomic database operations with START TRANSACTION and SELECT ... FOR UPDATE row locking for balance consistency.

Transaction Types

The following transaction types are supported: payment, refund, campaign, package, adjustment, campaign_reserve, campaign_refund, campaign_adjust, and classified.

New types must be added to the Transaction::TYPES constant, or get_valid_type() will silently fall back to 'credit'.

Wallet Filters

// Filter minimum deposit amount
$amount = apply_filters( 'wbam_pro_minimum_deposit', 5.00 );

// Filter available wallet payment methods
$methods = apply_filters( 'wbam_wallet_payment_methods', $methods );

Idempotency Protections

The wallet system includes built-in idempotency to prevent duplicate credits and debits. Both credit() and debit() accept an idempotency_key argument, and the wbam_transactions table enforces a UNIQUE constraint on this column.

Built-in Idempotency Keys

Using Idempotency in Custom Code

$wallet = Wallet_Manager::get_instance();

// Credit with idempotency key
$wallet->credit( $advertiser_id, 50.00, array(
    'type'            => 'payment',
    'note'            => 'Custom gateway payment',
    'idempotency_key' => 'my_gateway_payment_' . $external_id,
) );

Code Example: Custom Payment Notification

add_action( 'wbam_pro_payment_verified', function( $verified, $gateway_id, $payment_id, $data ) {
    if ( ! $verified || 'my_gateway' !== $gateway_id ) {
        return;
    }

    // Send custom notification
    $payment = wbam_pro_get_payment( $payment_id );
    $advertiser = wbam_pro_get_advertiser( $payment['advertiser_id'] );

    wp_mail(
        $advertiser['email'],
        'Payment Received',
        sprintf( 'Your payment of $%s has been processed.', $payment['amount'] )
    );
}, 10, 4 );