WalletPlug Merchant API

Integrate WalletPlug payment gateway into your application with our comprehensive RESTful API. Accept payments from wallets, cards, and multiple payment methods with enterprise-grade security.

Authentication

WalletPlug API uses API keys to authenticate requests. You can obtain your credentials from your merchant dashboard.

Required Credentials

Quick Start

Get up and running with WalletPlug API in just a few steps:

Initiate Payment

Create a new payment request and get a secure checkout URL for your customer. This endpoint works in both sandbox and production environments based on your X-Environment header.

Request Headers

Request Parameters

Code Examples

• cURL
• PHP/Laravel
• Python

curl -X POST "https://walletplug.com/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "X-Environment: {environment}" \
  -H "X-Merchant-Key: {merchant_key}" \
  -H "X-API-Key: {api_key}" \
  -d '{"payment_amount": 250.00, "currency_code": "USD", "ref_trx": "ORDER_12345", "description": "Premium Subscription", "success_redirect": "https://yoursite.com/payment/success", "failure_url": "https://yoursite.com/payment/failed", "cancel_redirect": "https://yoursite.com/payment/cancelled", "ipn_url": "https://yoursite.com/api/webhooks/WalletPlug", "allow_payment_methods": "card,bank_transfer"}'

<?php

use App\Enums\EnvironmentMode;
use Illuminate\Support\Facades\Http;

class WalletPlugPaymentInitiator
{
    private $environment;
    private $merchantKey;
    private $apiKey;
    private $baseUrl = 'https://walletplug.com/api/v1';

    public function __construct(EnvironmentMode $environment, $merchantKey, $apiKey)
    {
        $this->environment = $environment;
        $this->merchantKey = $merchantKey;
        $this->apiKey = $apiKey;
    }

    // Factory methods for easy configuration
    public static function sandbox($testMerchantKey, $testApiKey): self
    {
        return new self(EnvironmentMode::SANDBOX, $testMerchantKey, $testApiKey);
    }

    public static function production($merchantKey, $apiKey): self
    {
        return new self(EnvironmentMode::PRODUCTION, $merchantKey, $apiKey);
    }

    public function initiatePayment($paymentData)
    {
        try {
            $response = Http::withHeaders([
                'Content-Type' => 'application/json',
                'X-Environment' => $this->environment->value,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->post("{$this->baseUrl}/initiate-payment", $paymentData);

            if ($response->successful()) {
                $data = $response->json();
                
                if ($data['success']) {
                    return ['success' => true, 'data' => $data];
                }
                
                return ['success' => false, 'status' => $data['status'], 'message' => $data['message'] ?? 'Payment initiation failed'];
            }

            return ['success' => false, 'error' => 'API request failed'];
        } catch (Exception $e) {
            return ['success' => false, 'error' => $e->getMessage()];
        }
    }
}

// Usage: Choose appropriate factory method based on your environment
$initiator = WalletPlugPaymentInitiator::sandbox('test_merchant_key', 'test_api_key'); // For testing
// $initiator = WalletPlugPaymentInitiator::production('merchant_key', 'api_key'); // For production

$paymentData = [
    'payment_amount' => 250.00,
    'currency_code' => 'USD',
    'ref_trx' => 'ORDER_12345',
    'description' => 'Premium Subscription',
    'success_redirect' => 'https://yoursite.com/payment/success',
    'failure_url' => 'https://yoursite.com/payment/failed',
    'cancel_redirect' => 'https://yoursite.com/payment/cancelled',
    'ipn_url' => 'https://yoursite.com/api/webhooks/WalletPlug',
    // Optional: Limit methods shown on checkout by name (string or array)
    'allow_payment_methods' => ['card', 'bank_transfer'],
];

$result = $initiator->initiatePayment($paymentData);

const axios = require('axios');

const EnvironmentMode = {
    SANDBOX: 'sandbox',
    PRODUCTION: 'production'
};

class WalletPlugPaymentInitiator {
    constructor(environment, merchantKey, apiKey) {
        this.environment = environment;
        this.merchantKey = merchantKey;
        this.apiKey = apiKey;
        this.baseUrl = 'https://walletplug.com/api/v1';
    }

    // Factory methods
    static sandbox(testMerchantKey, testApiKey) {
        return new WalletPlugPaymentInitiator(EnvironmentMode.SANDBOX, testMerchantKey, testApiKey);
    }

    static production(merchantKey, apiKey) {
        return new WalletPlugPaymentInitiator(EnvironmentMode.PRODUCTION, merchantKey, apiKey);
    }

    async initiatePayment(paymentData) {
        try {
            const response = await axios.post(`${this.baseUrl}/initiate-payment`, paymentData, {
                headers: {
                    'Content-Type': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            const data = response.data;

            if (data.success) {
                return { success: true, data };
            }

            return { 
                success: false, 
                status: data.status, 
                message: data.message || 'Payment initiation failed' 
            };

        } catch (error) {
            if (error.response) {
                return { 
                    success: false, 
                    error: error.response.data.error || 'API request failed' 
                };
            }
            return { success: false, error: error.message };
        }
    }
}

// Usage: Choose appropriate factory method based on your environment
const initiator = WalletPlugPaymentInitiator.sandbox('test_merchant_key', 'test_api_key'); // For testing
// const initiator = WalletPlugPaymentInitiator.production('merchant_key', 'api_key'); // For production

const paymentData = {
    payment_amount: 250.00,
    currency_code: 'USD',
    ref_trx: 'ORDER_12345',
    description: 'Premium Subscription',
    success_redirect: 'https://yoursite.com/payment/success',
    failure_url: 'https://yoursite.com/payment/failed',
    cancel_redirect: 'https://yoursite.com/payment/cancelled',
    ipn_url: 'https://yoursite.com/api/webhooks/WalletPlug',
    // Optional: CSV/pipe/space string or array
    allow_payment_methods: ['card', 'bank_transfer'],
};

initiator.initiatePayment(paymentData)
    .then(result => console.log(result))
    .catch(error => console.error(error));

import requests
import logging
from enum import Enum

class EnvironmentMode(Enum):
    SANDBOX = 'sandbox'
    PRODUCTION = 'production'

class WalletPlugPaymentInitiator:
    def __init__(self, environment, merchant_key, api_key):
        self.environment = environment
        self.merchant_key = merchant_key
        self.api_key = api_key
        self.base_url = 'https://walletplug.com/api/v1'

    @classmethod
    def sandbox(cls, test_merchant_key, test_api_key):
        return cls(EnvironmentMode.SANDBOX, test_merchant_key, test_api_key)

    @classmethod
    def production(cls, merchant_key, api_key):
        return cls(EnvironmentMode.PRODUCTION, merchant_key, api_key)

    def initiate_payment(self, payment_data):
        try:
            headers = {
                'Content-Type': 'application/json',
                'X-Environment': self.environment.value,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.post(
                f"{self.base_url}/initiate-payment",
                headers=headers,
                json=payment_data,
                timeout=30
            )

            if response.status_code == 200:
                data = response.json()
                
                if data['success']:
                    return {'success': True, 'data': data}
                
                return {
                    'success': False, 
                    'status': data['status'], 
                    'message': data.get('message', 'Payment initiation failed')
                }

            return {'success': False, 'error': f'HTTP {response.status_code}'}

        except requests.RequestException as e:
            return {'success': False, 'error': str(e)}

# Usage: Choose appropriate factory method based on your environment
initiator = WalletPlugPaymentInitiator.sandbox('test_merchant_key', 'test_api_key')  # For testing
# initiator = WalletPlugPaymentInitiator.production('merchant_key', 'api_key')  # For production

payment_data = {
    'payment_amount': 250.00,
    'currency_code': 'USD',
    'ref_trx': 'ORDER_12345',
    'description': 'Premium Subscription',
    'success_redirect': 'https://yoursite.com/payment/success',
    'failure_url': 'https://yoursite.com/payment/failed',
    'cancel_redirect': 'https://yoursite.com/payment/cancelled',
    'ipn_url': 'https://yoursite.com/api/webhooks/WalletPlug',
    # Optional: string or list
    'allow_payment_methods': ['card', 'bank_transfer'],
}

result = initiator.initiate_payment(payment_data)
print(result)

Success Response

{
    "payment_url": "https://WalletPlug.test/payment/checkout?expires=1753724376&token=AmQvJdGIdGUVJUUMayJZZreBv2UcTyIHclk9Ps1s1pZhLpVlIqIBVPqGTRKQ3NUSehyM3qRUIf69IhLbNfJ1JqiMxlxNrnn22lNz1N01hZQn65r5VZnvhWmQPxQO8UX6rE4yfRUvT6bHdqLj7UDJhRPYRFSgCsG1b86sxSdKTZNOVJdWV5z8L6a5pNMZ2KlpG5e7bYa&signature=e9q7ea91456dcc167e7d498ea486f923570821957be8881566186655950f364",
    "info": {
        "ref_trx": "TXNT4AQFESTAG4F",
        "description": "Order #1234",
        "ipn_url": "https://webhook.site/5711b7d5-917a-4d94-bbb3-c28f4a37bea5",
        "cancel_redirect": "https://merchant.com/cancel",
        "success_redirect": "https://merchant.com/success",
        "merchant_id": 1,
        "merchant_name": "WalletPlug", 
        "amount": 200,
        "currency_code": "USD",
        "environment": "production",
        "is_sandbox": false
    }
}

Error Response

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "payment_amount": ["The payment amount field is required."],
    "currency_code": ["The currency code field is required."]
  }
}

Verify Payment

Verify the status of a payment using the WalletPlug transaction ID returned from the payment initiation.

Request Headers

Path Parameters

Code Examples

• cURL
• PHP/Laravel
• Python

curl -X GET "https://walletplug.com/api/v1/verify-payment/TXNQ5V8K2L9N3XM1" \
  -H "Accept: application/json" \
  -H "X-Environment: {environment}" \
  -H "X-Merchant-Key: {merchant_key}" \
  -H "X-API-Key: {api_key}"

<?php

use App\Enums\EnvironmentMode;
use Illuminate\Support\Facades\Http;

class WalletPlugPaymentVerifier
{
    private $environment;
    private $merchantKey;
    private $apiKey;
    private $baseUrl = 'https://walletplug.com/api/v1';

    public function __construct(EnvironmentMode $environment, $merchantKey, $apiKey)
    {
        $this->environment = $environment;
        $this->merchantKey = $merchantKey;
        $this->apiKey = $apiKey;
    }

    // Factory methods for easy configuration
    public static function sandbox($testMerchantKey, $testApiKey): self
    {
        return new self(EnvironmentMode::SANDBOX, $testMerchantKey, $testApiKey);
    }

    public static function production($merchantKey, $apiKey): self
    {
        return new self(EnvironmentMode::PRODUCTION, $merchantKey, $apiKey);
    }

    public function verifyPayment($trxId)
    {
        try {
            $response = Http::withHeaders([
                'Accept' => 'application/json',
                'X-Environment' => $this->environment->value,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->get("{$this->baseUrl}/verify-payment/{$trxId}");

            if ($response->successful()) {
                $data = $response->json();
                
                if ($data['status'] === 'completed') {
                    // Payment completed successfully
                    $this->fulfillOrder($data);
                    return ['success' => true, 'data' => $data];
                }
                
                return ['success' => false, 'status' => $data['status'], 'message' => $data['message'] ?? 'Payment not completed'];
            }

            return ['success' => false, 'error' => 'API request failed'];
        } catch (Exception $e) {
            return ['success' => false, 'error' => $e->getMessage()];
        }
    }

    private function fulfillOrder($paymentData)
    {
        // Your order fulfillment logic here
        logger('Payment verified successfully', $paymentData);
    }
}

// Usage: Choose appropriate factory method based on your environment
$verifier = WalletPlugPaymentVerifier::sandbox('test_merchant_key', 'test_api_key'); // For testing
// $verifier = WalletPlugPaymentVerifier::production('merchant_key', 'api_key'); // For production

$result = $verifier->verifyPayment('TXNQ5V8K2L9N3XM1');

const axios = require('axios');

const EnvironmentMode = {
    SANDBOX: 'sandbox',
    PRODUCTION: 'production'
};

class WalletPlugPaymentVerifier {
    constructor(environment, merchantKey, apiKey) {
        this.environment = environment;
        this.merchantKey = merchantKey;
        this.apiKey = apiKey;
        this.baseUrl = 'https://walletplug.com/api/v1';
    }

    // Factory methods
    static sandbox(testMerchantKey, testApiKey) {
        return new WalletPlugPaymentVerifier(EnvironmentMode.SANDBOX, testMerchantKey, testApiKey);
    }

    static production(merchantKey, apiKey) {
        return new WalletPlugPaymentVerifier(EnvironmentMode.PRODUCTION, merchantKey, apiKey);
    }

    async verifyPayment(trxId) {
        try {
            const response = await axios.get(`${this.baseUrl}/verify-payment/${trxId}`, {
                headers: {
                    'Accept': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            const data = response.data;

            if (data.status === 'completed') {
                // Payment completed successfully
                await this.fulfillOrder(data);
                return { success: true, data };
            }

            return { 
                success: false, 
                status: data.status, 
                message: data.message || 'Payment not completed' 
            };

        } catch (error) {
            if (error.response) {
                return { 
                    success: false, 
                    error: error.response.data.error || 'API request failed' 
                };
            }
            return { success: false, error: error.message };
        }
    }

    async fulfillOrder(paymentData) {
        // Your order fulfillment logic here
        console.log('Payment verified successfully:', paymentData);
    }
}

// Usage: Choose appropriate factory method based on your environment
const verifier = WalletPlugPaymentVerifier.sandbox('test_merchant_key', 'test_api_key'); // For testing
// const verifier = WalletPlugPaymentVerifier.production('merchant_key', 'api_key'); // For production

verifier.verifyPayment('TXNQ5V8K2L9N3XM1')
    .then(result => console.log(result))
    .catch(error => console.error(error));

import requests
import logging
from enum import Enum

class EnvironmentMode(Enum):
    SANDBOX = 'sandbox'
    PRODUCTION = 'production'

class WalletPlugPaymentVerifier:
    def __init__(self, environment, merchant_key, api_key):
        self.environment = environment
        self.merchant_key = merchant_key
        self.api_key = api_key
        self.base_url = 'https://walletplug.com/api/v1'

    @classmethod
    def sandbox(cls, test_merchant_key, test_api_key):
        return cls(EnvironmentMode.SANDBOX, test_merchant_key, test_api_key)

    @classmethod
    def production(cls, merchant_key, api_key):
        return cls(EnvironmentMode.PRODUCTION, merchant_key, api_key)

    def verify_payment(self, trx_id):
        try:
            headers = {
                'Accept': 'application/json',
                'X-Environment': self.environment.value,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.get(
                f"{self.base_url}/verify-payment/{trx_id}",
                headers=headers,
                timeout=30
            )

            if response.status_code == 200:
                data = response.json()
                
                if data['status'] == 'completed':
                    # Payment completed successfully
                    self.fulfill_order(data)
                    return {'success': True, 'data': data}
                
                return {
                    'success': False, 
                    'status': data['status'], 
                    'message': data.get('message', 'Payment not completed')
                }

            return {'success': False, 'error': f'HTTP {response.status_code}'}

        except requests.RequestException as e:
            return {'success': False, 'error': str(e)}

    def fulfill_order(self, payment_data):
        """Your order fulfillment logic here"""
        logging.info(f"Payment verified successfully: {payment_data}")

# Usage: Choose appropriate factory method based on your environment
verifier = WalletPlugPaymentVerifier.sandbox('test_merchant_key', 'test_api_key')  # For testing
# verifier = WalletPlugPaymentVerifier.production('merchant_key', 'api_key')  # For production

result = verifier.verify_payment('TXNQ5V8K2L9N3XM1')
print(result)

Success Response

{
    "status": "completed",
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "amount": 237.5,
    "fee": 12.5,
    "currency": "USD",
    "net_amount": 237.5,
    "customer": {
        "name": "John Doe",
        "email": "john@example.com"
    },
    "description": "Premium Subscription Payment",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:35:45.000000Z"
}

Failed/Canceled Transaction Response

{
    "status": "failed",
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "message": "Payment failed or canceled."
}

Pending Transaction Response

{
    "status": "pending",
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "message": "Payment is still pending."
}

Payment Status Values

Embedded Checkout (No Redirect)

Keep the entire payment on YOUR page. Instead of redirecting customers to the hosted checkout, drop our embeddable checkout into your own UI — the card form renders inline, fully white-labeled (no WalletPlug branding), while the sensitive card fields stay hosted and tokenized on our side. Your platform never touches raw card data, keeping you out of PCI scope (SAQ-A).

How it works

1. Call initiate-payment as usual, restricting the session to card with allow_payment_methods.
2. The response includes card_url — a signed, short-lived URL that renders ONLY the card form (no method selection, no branding).
3. Embed card_url in an iframe inside your checkout page.
4. On completion the frame navigates the top window to your success_redirect / failure_url / cancel_redirect.
5. Treat the signed IPN webhook as the source of truth, and/or confirm with verify-payment.

1. Create a card-only session

curl -X POST "https://walletplug.com/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "X-Environment: production" \
  -H "X-Merchant-Key: {merchant_key}" \
  -H "X-API-Key: {api_key}" \
  -d '{
    "payment_amount": 49.99,
    "currency_code": "USD",
    "ref_trx": "order_10021",
    "description": "Order #10021",
    "allow_payment_methods": ["card"],
    "success_redirect": "https://yourapp.com/pay/success",
    "failure_url": "https://yourapp.com/pay/failed",
    "cancel_redirect": "https://yourapp.com/checkout",
    "ipn_url": "https://yourapp.com/webhooks/walletplug"
  }'

2. Response

{
  "status": "success",
  "payment_url": "https://walletplug.com/payment/checkout?token=...",
  "card_url": "https://walletplug.com/payment/card?token=...&signature=...",
  "request_id": "req_8f2c1b"
}

3. Embed it on your page

<iframe
  src="{card_url from the API response}"
  style="width:100%; min-height:620px; border:0; border-radius:12px;"
  allow="payment"
  title="Secure card payment">
</iframe>

The card inputs inside the frame are hosted fields served by the card processor — card numbers are tokenized before they ever reach a server you or we control. When the customer completes (or cancels) payment, the page inside the frame navigates the TOP window to the corresponding URL you supplied at initiation, so your single-page flow resumes on your domain automatically. No JavaScript is required on your page for this to work.

4. Confirm the payment (server side)

Never fulfil on the redirect alone. Confirm using the signed IPN webhook (recommended) or the verify-payment endpoint:

// Node.js — verifying the IPN signature
const crypto = require('crypto');

app.post('/webhooks/walletplug', express.raw({ type: '*/*' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WALLETPLUG_CLIENT_SECRET)
    .update(req.body)                 // RAW body, exactly as received
    .digest('hex');

  if (req.get('X-Signature') !== expected) return res.status(401).end();

  const event = JSON.parse(req.body);
  if (event.status === 'completed') {
    // mark order event.data.ref_trx as paid — check amount & currency too
  }
  res.status(200).end();
});

Refunds

WalletPlug supports full and partial refunds on completed transactions. Refunds are processed back to the original payment method used by the customer.

curl -X POST "https://walletplug.com/api/v1/refund" \
  -H "Content-Type: application/json" \
  -H "X-Environment: production" \
  -H "X-Merchant-Key: your_merchant_key" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "amount": 50.00,
    "reason": "Customer requested refund — order cancelled",
    "ref_refund": "REFUND_ORDER_12345"
  }'

{
    "success": true,
    "refund_id": "RFD_9X2K7P1N4M3L8Q5",
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "amount": 50.00,
    "currency": "USD",
    "status": "processing",
    "reason": "Customer requested refund — order cancelled",
    "created_at": "2026-03-22T10:30:00.000000Z",
    "estimated_completion": "2026-03-25T00:00:00.000000Z"
}

{
    "success": false,
    "error_code": "REFUND_EXCEEDS_AMOUNT",
    "message": "Refund amount (150.00) exceeds original transaction amount (100.00)."
}

Refund Status Values

{
    "status": "completed",
    "event": "refund.completed",
    "data": {
        "refund_id": "RFD_9X2K7P1N4M3L8Q5",
        "trx_id": "TXNQ5V8K2L9N3XM1",
        "amount": 50.00,
        "currency": "USD",
        "reason": "Customer requested refund",
        "environment": "production",
        "is_sandbox": false
    },
    "timestamp": 1705747245
}

Webhooks (IPN)

WalletPlug sends real-time notifications to your specified IPN URL when payment status changes. This ensures you're immediately notified of payment completions, failures, and other status updates. Webhooks work identically in both sandbox and production environments.

Webhook Headers

Webhook Payload

All webhook payloads include environment information to help you differentiate between sandbox and production transactions:

{
    "data": {
        "ref_trx": "TXNT4AQFESTAG4F",
        "description": "Order #1234",
        "ipn_url": "https://webhook.site/5711b7d5-917a-4d94-bbb3-c28f4a37bea5",
        "cancel_redirect": "https://merchant.com/cancel",
        "success_redirect": "https://merchant.com/success",
        "customer_name": "John Doe",
        "customer_email": "john@example.com",
        "merchant_name": "Xanthus Wiggins",
        "amount": 200,
        "currency_code": "USD",
        "environment": "production",
        "is_sandbox": false
    },
    "message": "Payment Completed",
    "status": "completed",
    "timestamp": 1705747245
}

Signature Verification

Always verify webhook signatures to ensure authenticity and prevent unauthorized requests. Use your API secret (environment-specific) to verify signatures:

<?php
// Laravel Webhook Handler
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use App\Enums\EnvironmentMode;

class WalletPlugWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Get webhook headers
        $environment = $request->header('X-Environment', 'production');
        $signature = $request->header('X-Signature');
        $webhookId = $request->header('X-Webhook-ID');
        
        // Get appropriate secret based on environment
        $secret = $this->getSecretForEnvironment($environment);
        
        // Verify signature
        if (!$this->verifySignature($request->getContent(), $signature, $secret)) {
            Log::warning('WalletPlug webhook signature verification failed', [
                'webhook_id' => $webhookId,
                'environment' => $environment
            ]);
            
            return response()->json(['error' => 'Invalid signature'], 401);
        }
        
        $payload = $request->json()->all();
        
        // Handle based on environment
        if ($environment === EnvironmentMode::SANDBOX->value) {
            return $this->handleSandboxWebhook($payload);
        } else {
            return $this->handleProductionWebhook($payload);
        }
    }
    
    private function getSecretForEnvironment(string $environment): string
    {
        // Return test secret for sandbox, live secret for production
        return $environment === 'sandbox' 
            ? config('walletplug.test_webhook_secret')
            : config('walletplug.webhook_secret');
    }
    
    private function verifySignature(string $payload, string $signature, string $secret): bool
    {
        $expectedSignature = hash_hmac('sha256', $payload, $secret);
        return hash_equals($expectedSignature, $signature);
    }
    
    private function handleSandboxWebhook(array $payload): JsonResponse
    {
        Log::info('Processing sandbox webhook', $payload);
        
        // Your sandbox-specific logic here
        // Don't fulfill orders, don't send emails to real customers, etc.
        
        return response()->json(['status' => 'sandbox_processed']);
    }
    
    private function handleProductionWebhook(array $payload): JsonResponse
    {
        Log::info('Processing production webhook', $payload);
        
        // Your production logic here
        // Fulfill orders, send confirmation emails, etc.
        
        return response()->json(['status' => 'processed']);
    }
}

const crypto = require('crypto');
const express = require('express');

const EnvironmentMode = {
    SANDBOX: 'sandbox',
    PRODUCTION: 'production'
};

// Webhook handler
app.post('/api/webhooks/walletplug', async (req, res) => {
    const environment = req.headers['x-environment'] || 'production';
    const signature = req.headers['x-signature'];
    const webhookId = req.headers['x-webhook-id'];
    
    // Get appropriate secret based on environment
    const secret = getSecretForEnvironment(environment);
    
    // Verify signature
    if (!verifySignature(JSON.stringify(req.body), signature, secret)) {
        console.warn('WalletPlug webhook signature verification failed', {
            webhook_id: webhookId,
            environment: environment
        });
        
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    const payload = req.body;
    
    try {
        // Handle based on environment
        if (environment === EnvironmentMode.SANDBOX) {
            await handleSandboxWebhook(payload);
        } else {
            await handleProductionWebhook(payload);
        }
        
        res.json({ status: 'processed' });
    } catch (error) {
        console.error('Webhook processing error:', error);
        res.status(500).json({ error: 'Processing failed' });
    }
});

function getSecretForEnvironment(environment) {
    // Return test secret for sandbox, live secret for production
    return environment === 'sandbox' 
        ? process.env.WALLETPLUG_TEST_WEBHOOK_SECRET
        : process.env.WALLETPLUG_WEBHOOK_SECRET;
}

function verifySignature(payload, signature, secret) {
    if (!signature) {
        return false;
    }
    
    const expectedSignature = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(expectedSignature),
        Buffer.from(signature)
    );
}

async function handleSandboxWebhook(payload) {
    console.log('Processing sandbox webhook:', payload);
    
    // Your sandbox-specific logic here
    // Don't fulfill orders, don't send emails to real customers, etc.
}

async function handleProductionWebhook(payload) {
    console.log('Processing production webhook:', payload);
    
    // Your production logic here
    // Fulfill orders, send confirmation emails, etc.
}

import hmac
import hashlib
import json
import logging
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods

logger = logging.getLogger(__name__)

ENVIRONMENT_MODE = {
    'SANDBOX': 'sandbox',
    'PRODUCTION': 'production'
}

@csrf_exempt
@require_http_methods(["POST"])
def walletplug_webhook(request):
    environment = request.headers.get('X-Environment', 'production')
    signature = request.headers.get('X-Signature', '')
    webhook_id = request.headers.get('X-Webhook-ID')
    
    // Get appropriate secret based on environment
    secret = get_secret_for_environment(environment)
    
    // Verify signature
    if not verify_signature(request.body, signature, secret):
        logger.warning('WalletPlug webhook signature verification failed', extra={
            'webhook_id': webhook_id,
            'environment': environment
        })
        
        return JsonResponse({'error': 'Invalid signature'}, status=401)
    
    try:
        payload = json.loads(request.body)
        
        // Handle based on environment
        if environment == ENVIRONMENT_MODE['SANDBOX']:
            handle_sandbox_webhook(payload)
        else:
            handle_production_webhook(payload)
        
        return JsonResponse({'status': 'processed'})
    
    except Exception as e:
        logger.error(f'Webhook processing error:{str(e)}')
        return JsonResponse({'error': 'Processing failed'}, status=500)

def get_secret_for_environment(environment):
    from django.conf import settings
    
    // Return test secret for sandbox, live secret for production
    return (settings.WALLETPLUG_TEST_WEBHOOK_SECRET 
            if environment == 'sandbox' 
            else settings.WALLETPLUG_WEBHOOK_SECRET)

def verify_signature(payload, signature, secret):
    if not signature:
        return False
    
    expected_signature = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_signature, signature)

def handle_sandbox_webhook(payload):
    logger.info('Processing sandbox webhook', extra=payload)
    
    // Your sandbox-specific logic here
    // Don't fulfill orders, don't send emails to real customers, etc.

def handle_production_webhook(payload):
    logger.info('Processing production webhook', extra=payload)
    
    // Your production logic here
    // Fulfill orders, send confirmation emails, etc.

Environment-Specific Best Practices

Transaction Lifecycle

Every payment created via the WalletPlug API moves through a defined set of states. Understanding this lifecycle helps you implement correct webhook handlers, retry logic, and order management.

Status Reference

// ❌ Wrong — never redirect to old payment_url after failure
window.location.href = oldPaymentUrl;

// ✅ Correct — create a new session with a fresh ref_trx
const result = await fetch('/api/v1/initiate-payment', {
    method: 'POST',
    body: JSON.stringify({
        payment_amount: 100.00,
        currency_code: 'USD',
        ref_trx: `ORDER_${orderId}_${Date.now()}`, // fresh reference
        // ... other params
    })
});
const { payment_url } = await result.json();
window.location.href = payment_url;

Subscriptions API

WalletPlug's Subscriptions API lets you build recurring billing into your product in minutes. Create plans, store customers, attach payment methods, and let WalletPlug bill your customers automatically on every cycle — with retries, dunning, and outbound webhooks.

https://walletplug.com/api/v1/billing

Core Concepts

Subscription Lifecycle

incomplete → trialing? → active → past_due ⇆ active → canceled / expired

A failed charge moves the subscription to past_due. After 3 failed attempts the subscription remains past_due until either the next retry succeeds or the merchant/customer cancels.

Authentication

Every Subscriptions API request uses the same authentication as the rest of the WalletPlug merchant API:

Plans

POST /api/v1/billing/plans

Create a recurring pricing plan.

Request Body

Example

curl -X POST https://walletplug.com/api/v1/billing/plans \
  -H "X-Merchant-Key: $WP_MERCHANT_KEY" \
  -H "X-API-Key: $WP_API_KEY" \
  -H "X-Environment: production" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "amount": 29.99,
    "currency": "USD",
    "billing_interval": "month",
    "interval_count": 1,
    "trial_days": 14
  }'

Response (201)

{
  "data": {
    "uuid": "5f8a2b1e-9c4d-4e7f-b2c1-a3d4e5f6g7h8",
    "name": "Pro Monthly",
    "amount": "29.99",
    "currency": "USD",
    "billing_interval": "month",
    "interval_count": 1,
    "trial_days": 14,
    "total_cycles": null,
    "is_active": true,
    "created_at": "2026-01-15T10:23:45.000000Z"
  }
}

Other Plan Endpoints

Customers

POST /api/v1/billing/customers

Create a customer (idempotent on email).

Example

curl -X POST https://walletplug.com/api/v1/billing/customers \
  -H "X-Merchant-Key: $WP_MERCHANT_KEY" \
  -H "X-API-Key: $WP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "name": "Alex Doe",
    "phone": "+14155550100",
    "metadata": {"signup_source": "landing-page-v2"}
  }'

Attach a Payment Method

POST /api/v1/billing/customers/{uuid}/payment-methods

{
  "gateway": "walletplug",
  "gateway_token": "wptok_1OZxyzAbcDef123",
  "brand": "visa",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2028
}

In most integrations you do not call this endpoint directly. The WalletPlug hosted checkout captures the card and creates the payment method server-side; the resulting subscription comes back ready to charge. This endpoint is exposed for advanced integrations that have already tokenised a card through a WalletPlug client SDK.

Subscriptions

POST /api/v1/billing/subscriptions

Subscribe a customer to a plan. The first invoice is charged immediately unless the plan has a trial.

Request Body

Example

curl -X POST https://walletplug.com/api/v1/billing/subscriptions \
  -H "X-Merchant-Key: $WP_MERCHANT_KEY" \
  -H "X-API-Key: $WP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "5f8a2b1e-9c4d-4e7f-b2c1-a3d4e5f6g7h8",
    "customer": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
  }'

Response

{
  "data": {
    "uuid": "sub_2a3b4c5d6e7f",
    "status": "active",
    "amount": "29.99",
    "currency": "USD",
    "billing_interval": "month",
    "interval_count": 1,
    "cycles_completed": 1,
    "current_period_start": "2026-01-15T10:24:00Z",
    "current_period_end":   "2026-02-15T10:24:00Z",
    "next_billing_at":      "2026-02-15T10:24:00Z",
    "plan":     { "uuid": "...", "name": "Pro Monthly" },
    "customer": { "uuid": "...", "email": "alex@example.com" }
  }
}

Other Subscription Endpoints

Hosted Checkout

Every plan automatically gets a public checkout URL. Share it on your website, in an email, or as a QR code — no integration code required.

https://walletplug.com/subscribe/{plan_uuid}

The customer enters their email and card details on a WalletPlug-hosted page. On success, your webhook receives subscription.activated and invoice.paid.

Embedding on Your Site

<a href="https://walletplug.com/subscribe/5f8a2b1e-9c4d-4e7f-b2c1-a3d4e5f6g7h8"
   class="btn btn-primary">
  Subscribe — $29.99/month
</a>

Webhooks

Register an HTTPS endpoint in your merchant dashboard and WalletPlug will POST a signed JSON payload on every lifecycle event.

Event Types

Payload Format

{
  "id": "evt_a1b2c3d4",
  "type": "invoice.paid",
  "created": 1718640000,
  "data": {
    "invoice": { "uuid": "...", "amount": "29.99", "status": "paid" }
  }
}

Verifying Signatures

Every request includes an X-WalletPlug-Signature header in the form t={timestamp},v1={hmac}. Verify it by computing HMAC-SHA256 over {timestamp}.{raw_body} with your endpoint's signing secret:

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_WALLETPLUG_SIGNATURE'];
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m);
[$ts, $sig] = [$m[1], $m[2]];

$expected = hash_hmac('sha256', $ts . '.' . $payload, $signing_secret);
if (!hash_equals($expected, $sig)) {
    http_response_code(400);
    exit('Invalid signature');
}

// Reject replays older than 5 minutes
if (abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit('Stale timestamp');
}

$event = json_decode($payload, true);
// ... handle $event['type'] ...
http_response_code(200);

Retry Policy

If your endpoint returns a non-2xx status or times out (10 s), the event is retried with exponential backoff: 5 min → 30 min → 2 h → 12 h → 24 h. After 5 failed attempts the event is marked dead and surfaced in your dashboard.

End-to-End Example

A complete flow: create a plan, share its hosted checkout URL, and listen for the webhook when the customer subscribes.

<?php
$base    = 'https://walletplug.com/api/v1/billing';
$headers = [
    'X-Merchant-Key: ' . getenv('WP_MERCHANT_KEY'),
    'X-API-Key: '      . getenv('WP_API_KEY'),
    'X-Environment: production',
    'Content-Type: application/json',
];

function wp($method, $url, $body, $headers) {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
        CURLOPT_HTTPHEADER     => $headers,
    ]);
    return json_decode(curl_exec($ch), true);
}

// 1. Create a plan (do this once, in your admin)
$plan = wp('POST', "$base/plans", [
    'name'             => 'Pro Monthly',
    'amount'           => 29.99,
    'currency'         => 'USD',
    'billing_interval' => 'month',
    'interval_count'   => 1,
    'trial_days'       => 14,
], $headers);

$planUuid = $plan['data']['uuid'];

// 2. Send the customer to the hosted checkout — WalletPlug will create the
//    customer, capture the card, and create the active subscription for you.
$checkoutUrl = "https://walletplug.com/subscribe/{$planUuid}";
header("Location: {$checkoutUrl}");

// 3. In your webhook handler, react when the subscription activates:
//      POST /your-webhook  →  event.type = "subscription.activated"
//                           → event.data.subscription.uuid is now active
echo "Sent customer to {$checkoutUrl}";

Integrating Subscriptions Into Your App

This is the end-to-end pattern for selling subscriptions on your website using WalletPlug. Most merchants only need this one page to ship a complete recurring billing flow.

The big picture

Customers pay on a WalletPlug-hosted page. The moment they pay, we POST a signed JSON event to your server. Your server reads the event and grants the customer access in your own database. That's it — no API polling, no client-side trust, no PCI scope.

1. Customer clicks "Subscribe" on YOUR site
   ↓
2. They land on walletplug.com/subscribe/{plan_uuid}
   ↓
3. They enter email + card and click Subscribe
   ↓
4. WalletPlug charges the card through your gateway
   ↓
5. WalletPlug POSTs to YOUR webhook URL:
   POST https://yoursite.com/webhooks/walletplug
   {
     "type": "subscription.activated",
     "data": { "customer": { "email": "alice@example.com" }, ... }
   }
   ↓
6. Your server finds Alice, marks her as paid, grants access

Step 1 — Create a plan

From your dashboard click 'New plan'. Set the name, amount, currency, and billing interval. You'll get back a plan UUID and a hosted checkout URL like:

https://walletplug.com/subscribe/5f8a2b1e-9c4d-4e7f-b2c1-a3d4e5f6g7h8

Step 2 — Put the subscribe link on your website

Any link, button, or pricing card. Reuse the same URL for every customer — WalletPlug captures their email at checkout.

<a href="https://walletplug.com/subscribe/5f8a2b1e-..." class="btn btn-primary">
    Subscribe — $29/month
</a>

Or use the embeddable widget — see the SDKs & Plugins section.

Step 3 — Tell us where to send webhook events

Go to Webhooks and add your endpoint URL plus the events you care about. We recommend the 'Essential' preset to start:

• subscription.activated — grant access
• invoice.paid — a renewal succeeded
• invoice.failed — a charge failed (still retrying)
• subscription.canceled — revoke access

Copy the signing secret WalletPlug generates — your handler verifies every payload with it.

Step 4 — Build your webhook handler

Pick your language. All three examples below do exactly the same thing — verify the signature, route by event type, update the user.

PHP / Laravel

<?php
// routes/web.php
Route::post('/webhooks/walletplug', function (Request $request) {
    // 1. Verify signature
    $payload   = $request->getContent();
    $signature = $request->header('X-WalletPlug-Signature');
    [$ts, $sig] = explode(',', str_replace(['t=', 'v1='], '', $signature));

    $expected = hash_hmac('sha256', $ts . '.' . $payload, env('WALLETPLUG_WEBHOOK_SECRET'));
    if (!hash_equals($expected, $sig)) {
        return response('Invalid signature', 400);
    }
    // 2. Reject events older than 5 minutes (replay protection)
    if (abs(time() - (int)$ts) > 300) return response('Stale', 400);

    // 3. Parse and route
    $event = json_decode($payload, true);

    // 4. Idempotency — don't process the same event twice
    $processed = DB::table('webhook_log')->where('event_id', $event['id'])->exists();
    if ($processed) return response('OK', 200);
    DB::table('webhook_log')->insert(['event_id' => $event['id'], 'created_at' => now()]);

    // 5. Handle the event
    $email = $event['data']['customer']['email'] ?? null;
    $user  = User::firstWhere('email', $email);
    if (!$user) {
        // Account doesn't exist yet — auto-create + email a magic-login link
        $user = User::create(['email' => $email, 'password' => bcrypt(Str::random(32))]);
        Mail::to($email)->send(new MagicLoginEmail($user));
    }

    switch ($event['type']) {
        case 'subscription.activated':
            $user->update([
                'subscription_status' => 'active',
                'subscription_plan'   => $event['data']['plan']['name'],
                'walletplug_sub_uuid' => $event['data']['subscription']['uuid'],
            ]);
            break;
        case 'invoice.paid':
            // A renewal — extend access if you're tracking expiry locally
            break;
        case 'invoice.failed':
            $user->update(['subscription_status' => 'past_due']);
            break;
        case 'subscription.canceled':
            $user->update(['subscription_status' => 'canceled']);
            break;
    }

    return response()->json(['ok' => true]);
});

Node.js / Express

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use('/webhooks/walletplug', express.raw({ type: 'application/json' }));

const processed = new Set(); // use Redis/DB in production

app.post('/webhooks/walletplug', (req, res) => {
    // 1. Verify signature
    const sigHeader = req.headers['x-walletplug-signature'] || '';
    const [tsPart, sigPart] = sigHeader.split(',');
    const ts  = tsPart.replace('t=', '');
    const sig = sigPart.replace('v1=', '');

    const expected = crypto
        .createHmac('sha256', process.env.WALLETPLUG_WEBHOOK_SECRET)
        .update(`${ts}.${req.body.toString()}`)
        .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
        return res.status(400).send('Invalid signature');
    }
    if (Math.abs(Date.now()/1000 - parseInt(ts)) > 300) {
        return res.status(400).send('Stale');
    }

    // 2. Parse
    const event = JSON.parse(req.body.toString());

    // 3. Idempotency
    if (processed.has(event.id)) return res.json({ ok: true });
    processed.add(event.id);

    const email = event.data?.customer?.email;

    switch (event.type) {
        case 'subscription.activated':
            // grantAccess(email, event.data.plan.name);
            break;
        case 'invoice.failed':
            // markPastDue(email);
            break;
        case 'subscription.canceled':
            // revokeAccess(email);
            break;
    }

    res.json({ ok: true });
});

app.listen(3000);

Python / Flask

import os, hmac, hashlib, time
from flask import Flask, request, abort, jsonify

app = Flask(__name__)
SECRET = os.environ['WALLETPLUG_WEBHOOK_SECRET']
processed = set()  # use Redis/DB in production

@app.post('/webhooks/walletplug')
def walletplug_webhook():
    # 1. Verify signature
    header = request.headers.get('X-WalletPlug-Signature', '')
    parts = dict(p.split('=', 1) for p in header.split(','))
    ts, sig = parts.get('t'), parts.get('v1')

    expected = hmac.new(
        SECRET.encode(),
        f"{ts}.{request.data.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, sig or ''):
        abort(400, 'Invalid signature')
    if abs(time.time() - int(ts)) > 300:
        abort(400, 'Stale')

    event = request.get_json()

    # 2. Idempotency
    if event['id'] in processed:
        return jsonify(ok=True)
    processed.add(event['id'])

    email = event.get('data', {}).get('customer', {}).get('email')

    handlers = {
        'subscription.activated': lambda: grant_access(email, event['data']['plan']['name']),
        'invoice.failed':         lambda: mark_past_due(email),
        'subscription.canceled':  lambda: revoke_access(email),
    }
    if event['type'] in handlers:
        handlers[event['type']]()

    return jsonify(ok=True)

Two ways to match the customer

Option A — Match by email (most common)

If the customer already has an account on your site, they use the same email at checkout. Your webhook handler does: User::where('email', $event['data']['customer']['email']).

Option B — Match by metadata (most reliable)

Append your internal user ID to the subscribe link:

<a href="https://walletplug.com/subscribe/{plan_uuid}?metadata[user_id]=42&metadata[ref]=blog">
    Subscribe
</a>

That metadata appears in every webhook payload:

{
  "type": "subscription.activated",
  "data": {
    "subscription": {
      "uuid": "sub_xyz",
      "metadata": { "user_id": "42", "ref": "blog" }
    }
  }
}

Then your handler can match by your own ID: User::find($event['data']['subscription']['metadata']['user_id']).

Retry policy you should know about

• If your endpoint returns anything other than 2xx, we retry.
• Retry delays: 5 min → 30 min → 2 h → 12 h → 24 h
• After 5 failed attempts the delivery is marked dead and shown in your dashboard.
• We expect a response within 10 seconds — do slow work asynchronously.

Common gotchas

• Always verify the signature — Otherwise anyone can POST fake events to your webhook URL and unlock your product for free.
• Always check idempotency — Webhooks can fire twice. Track event IDs and skip ones you've already processed.
• Don't block on the response — Return 200 immediately, then process asynchronously. Slow webhooks miss the 10-second deadline and get retried unnecessarily.
• Handle the trial-end transition — During a trial, status is trialing. Don't revoke access just because last_payment_at is null.

Test it before going live

1. Add your endpoint and select events.
2. Click 'Send test event' on the endpoint card. We'll POST a sample subscription.activated to your URL.
3. Verify your handler returns 200 in the Recent Deliveries panel.
4. Do a real $1 subscription with your own card to confirm the full flow end-to-end.

WordPress Plugin

Drop subscription checkout into any WordPress site with our official plugin. No code required — just paste a shortcode or use the Gutenberg block.

[walletplug_subscribe plan="YOUR_PLAN_UUID" label="Subscribe — $29/mo"]

Or use the Gutenberg block: WalletPlug Subscribe.

Plain HTML Embed

Works on any site — landing pages, no-code builders, plain HTML. Two lines.

<script src="https://walletplug.com/js/walletplug-billing.js" async></script>
<walletplug-button plan="YOUR_PLAN_UUID">Subscribe</walletplug-button>

Or use a data attribute on any link / button you already have:

<a href="#" data-walletplug-plan="YOUR_PLAN_UUID">Start free trial</a>

Listen for subscription events:

window.addEventListener('walletplug:subscription', (e) => {
    console.log('New subscription:', e.detail);
    // e.g. redirect to thank-you page
    window.location = '/thank-you';
});

PHP / Laravel SDK Example

Server-side: create a plan and send the customer to the WalletPlug hosted checkout.

<?php
use GuzzleHttp\Client;

$wp = new Client([
    'base_uri' => 'https://walletplug.com/api/v1/billing/',
    'headers'  => [
        'X-Merchant-Key' => env('WP_MERCHANT_KEY'),
        'X-API-Key'      => env('WP_API_KEY'),
        'X-Environment'  => 'production',
        'Accept'         => 'application/json',
    ],
]);

// 1. Create a plan once
$plan = json_decode($wp->post('plans', [
    'json' => [
        'name'             => 'Pro Monthly',
        'amount'           => 29.99,
        'currency'         => 'USD',
        'billing_interval' => 'month',
        'interval_count'   => 1,
        'trial_days'       => 14,
    ]
])->getBody(), true);

$planUuid = $plan['data']['uuid'];

// 2. Send the user to the WalletPlug hosted checkout.
//    WalletPlug captures the card, creates the customer + subscription,
//    and fires `subscription.activated` to your webhook on success.
return redirect("https://walletplug.com/subscribe/{$planUuid}");

Node.js / TypeScript Example

const BASE = 'https://walletplug.com/api/v1/billing';
const headers = {
    'X-Merchant-Key': process.env.WP_MERCHANT_KEY,
    'X-API-Key':      process.env.WP_API_KEY,
    'X-Environment':  'production',
    'Content-Type':   'application/json',
};

async function wp(method, path, body) {
    const r = await fetch(`${BASE}${path}`, {
        method, headers, body: body ? JSON.stringify(body) : undefined,
    });
    if (!r.ok) throw new Error(await r.text());
    return r.json();
}

// Create a plan
const plan = await wp('POST', '/plans', {
    name: 'Pro Monthly', amount: 29.99, currency: 'USD',
    billing_interval: 'month', interval_count: 1, trial_days: 14
});

// Redirect the user to the WalletPlug hosted checkout
const checkoutUrl = `https://walletplug.com/subscribe/${plan.data.uuid}`;
console.log('Send your user to:', checkoutUrl);

Python Example

import os, requests

BASE = "https://walletplug.com/api/v1/billing"
H = {
    "X-Merchant-Key": os.environ["WP_MERCHANT_KEY"],
    "X-API-Key":      os.environ["WP_API_KEY"],
    "X-Environment":  "production",
    "Content-Type":   "application/json",
}

def wp(method, path, body=None):
    r = requests.request(method, BASE + path, headers=H, json=body, timeout=15)
    r.raise_for_status()
    return r.json()

plan = wp("POST", "/plans", {
    "name":"Pro Monthly", "amount":29.99, "currency":"USD",
    "billing_interval":"month", "interval_count":1, "trial_days":14,
})

# Send your user to the WalletPlug hosted checkout
checkout_url = f"https://walletplug.com/subscribe/{plan['data']['uuid']}"
print("Redirect user to:", checkout_url)

cURL One-liners

# List plans
curl -H "X-Merchant-Key: $KEY" -H "X-API-Key: $SECRET" \
     https://walletplug.com/api/v1/billing/plans

# Cancel subscription immediately
curl -X POST -H "X-Merchant-Key: $KEY" -H "X-API-Key: $SECRET" \
     https://walletplug.com/api/v1/billing/subscriptions/SUB_UUID/cancel

# Cancel at period end
curl -X POST -H "X-Merchant-Key: $KEY" -H "X-API-Key: $SECRET" \
     -d 'at_period_end=true' \
     https://walletplug.com/api/v1/billing/subscriptions/SUB_UUID/cancel

Rate Limits

The WalletPlug API uses rate limiting to ensure stability and fair usage across all merchants. Limits are applied per merchant account, not per IP address.

Limits by Endpoint

Rate Limit Response Headers

Every API response includes these headers so you can monitor your usage:

Recommended Retry Strategy

async function apiCallWithRetry(fn, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        const response = await fn();
        if (response.status !== 429) return response;
        const retryAfter = response.headers.get('Retry-After');
        const waitMs = retryAfter
            ? parseInt(retryAfter) * 1000
            : Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitMs));
    }
    throw new Error('Max retries exceeded');
}

Supported Currencies & Countries

WalletPlug is a global fintech platform — Plug to the World. We power international payments for merchants and customers across every major region: the Americas, Europe, Asia Pacific, the Middle East, and Africa. One integration, one API, the entire world.

Supported Currencies

All major global and regional currencies are supported. Minimum amounts apply per currency.

Supported Countries

WalletPlug supports merchants and customers across every major region worldwide. If your country is not listed below contact us — we likely already support it.

Supported Payment Methods

WalletPlug is an all-in-one payment platform. Merchants integrate once and instantly support every major payment method globally — no separate gateway accounts, no extra integrations, no complexity.

Filter Payment Methods at Checkout

Use the optional allow_payment_methods parameter to restrict which methods appear at checkout. Omit it to show all methods available in the customer's region — recommended for maximum conversion.

{
    "payment_amount": 100.00,
    "currency_code": "USD",
    "ref_trx": "ORDER_12345",
    "allow_payment_methods": "card,bank_transfer,wallet"
}

Security & Compliance

WalletPlug is built as an enterprise-grade fintech platform. This section covers our security architecture, compliance posture, and the responsibilities shared between WalletPlug and merchants integrating the API.

X-Signature: sha256=a8b9c2d1e5f3... (HMAC-SHA256 of raw body using Client Secret)

Official SDKs & Packages

WalletPlug publishes official SDK packages for the most popular server-side languages. Each package handles authentication, request signing, automatic retries, error normalisation, and typed responses — so you can integrate in minutes instead of hours.

npm install walletplug-node

import WalletPlug from 'walletplug-node';

const wp = new WalletPlug({
  merchantKey: process.env.WALLETPLUG_MERCHANT_KEY,
  apiKey:      process.env.WALLETPLUG_API_KEY,
  environment: 'sandbox',
});
wp.setWebhookSecret(process.env.WALLETPLUG_WEBHOOK_SECRET);

// Initiate payment
const result = await wp.payments.initiate({
  amount: 250.00, currency: 'USD', reference: 'ORDER_12345',
  successUrl: 'https://yoursite.com/success',
  failureUrl: 'https://yoursite.com/failed',
  cancelUrl:  'https://yoursite.com/cancel',
  webhookUrl: 'https://yoursite.com/webhook',
});
res.redirect(result.paymentUrl);

// Verify payment
const payment = await wp.payments.verify('TXNQ5V8K2L9N3XM1');

// Webhook — use express.raw() for HMAC verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = wp.webhooks.verifyAndParse(
    req.body.toString('utf8'),
    req.headers['x-signature']
  );
  if (payload.status === 'completed') fulfillOrder(payload.data.ref_trx);
  res.json({ received: true });
});

composer require walletplug/walletplug-php

<?php
use WalletPlug\WalletPlug;

$wp = new WalletPlug([
    'merchant_key'   => getenv('WALLETPLUG_MERCHANT_KEY'),
    'api_key'        => getenv('WALLETPLUG_API_KEY'),
    'webhook_secret' => getenv('WALLETPLUG_WEBHOOK_SECRET'),
    'environment'    => 'sandbox',
]);

$result = $wp->payments->initiate([
    'amount' => 250.00, 'currency' => 'USD', 'reference' => 'ORDER_12345',
    'success_url' => 'https://yoursite.com/success',
    'failure_url' => 'https://yoursite.com/failed',
    'cancel_url'  => 'https://yoursite.com/cancel',
    'webhook_url' => 'https://yoursite.com/webhook',
]);
header('Location: ' . $result->paymentUrl);

php artisan vendor:publish --provider="WalletPlug\Laravel\WalletPlugServiceProvider"

<?php
// .env
WALLETPLUG_MERCHANT_KEY=test_your_merchant_key
WALLETPLUG_API_KEY=test_your_api_key
WALLETPLUG_WEBHOOK_SECRET=your_client_secret
WALLETPLUG_ENVIRONMENT=sandbox

// Controller (dependency injection)
class PaymentController extends Controller {
    public function __construct(private readonly WalletPlug $walletplug) {}

    public function pay(Request $request) {
        $result = $this->walletplug->payments->initiate([
            'amount' => $request->amount, 'currency' => 'USD',
            'reference'   => 'ORDER_' . $request->order_id,
            'success_url' => route('payment.success'),
            'failure_url' => route('payment.failed'),
            'cancel_url'  => route('payment.cancel'),
            'webhook_url' => route('payment.webhook'),
        ]);
        return redirect($result->paymentUrl);
    }
}

pip install walletplug-python

from walletplug import WalletPlug
import os

wp = WalletPlug(
    merchant_key=os.getenv('WALLETPLUG_MERCHANT_KEY'),
    api_key=os.getenv('WALLETPLUG_API_KEY'),
    environment='sandbox',
)
wp.set_webhook_secret(os.getenv('WALLETPLUG_WEBHOOK_SECRET'))

result = wp.payments.initiate(
    amount=250.00, currency='USD', reference='ORDER_12345',
    success_url='https://yoursite.com/success',
    failure_url='https://yoursite.com/failed',
    cancel_url='https://yoursite.com/cancel',
    webhook_url='https://yoursite.com/webhook',
)
return redirect(result.payment_url)

from walletplug import AsyncWalletPlug
from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse

app = FastAPI()
wp  = AsyncWalletPlug.sandbox('test_merchant_key', 'test_api_key')
wp.set_webhook_secret(os.getenv('WALLETPLUG_WEBHOOK_SECRET'))

@app.post('/pay')
async def pay(order_id: str):
    result = await wp.payments.initiate(
        amount=100.00, currency='USD', reference=f'ORDER_{order_id}',
        success_url='https://yoursite.com/success',
        failure_url='https://yoursite.com/failed',
        cancel_url='https://yoursite.com/cancel',
        webhook_url='https://yoursite.com/webhook',
    )
    return RedirectResponse(result.payment_url)

@app.post('/webhook')
async def webhook(request: Request):
    raw  = (await request.body()).decode('utf-8')
    sig  = request.headers.get('x-signature', '')
    data = wp.webhooks.verify_and_parse(raw, sig)
    if data.status == 'completed':
        await fulfill_order(data.data.ref_trx)
    return {'received': True}

SDK Feature Comparison

Integration Examples

Complete integration examples for popular platforms and frameworks.

<?php
// Laravel Integration Service
namespace App\Services;

use Illuminate\Support\Facades\Http;
use Exception;

class WalletPlugService
{
    private string $baseUrl;
    private string $merchantKey;
    private string $apiKey;
    private string $environment;

    public function __construct()
    {
        $this->baseUrl = config('walletplug.base_url');
        $this->merchantKey = config('walletplug.merchant_key');
        $this->apiKey = config('walletplug.api_key');
        $this->environment = config('walletplug.environment'); // 'sandbox' or 'production'
    }

    public function initiatePayment(array $paymentData): array
    {
        try {
            $response = Http::withHeaders([
                'Content-Type' => 'application/json',
                'X-Environment' => $this->environment,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->post("{$this->baseUrl}/api/v1/initiate-payment", $paymentData);

            if ($response->successful()) {
                return $response->json();
            }

            throw new Exception('WalletPlug API Error: Payment initiation failed');
        } catch (Exception $e) {
            throw new Exception('WalletPlug API Error: ' . $e->getMessage());
        }
    }

    public function verifyPayment(string $transactionId): array
    {
        try {
            $response = Http::withHeaders([
                'Accept' => 'application/json',
                'X-Environment' => $this->environment,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->get("{$this->baseUrl}/api/v1/verify-payment/{$transactionId}");

            if ($response->successful()) {
                return $response->json();
            }

            throw new Exception('WalletPlug API Error: Payment verification failed');
        } catch (Exception $e) {
            throw new Exception('WalletPlug API Error: ' . $e->getMessage());
        }
    }
}

// Configuration (config/walletplug.php)
return [
    'base_url' => env('WALLETPLUG_BASE_URL', 'https://walletplug.com'),
    'environment' => env('WALLETPLUG_ENVIRONMENT', 'sandbox'), // sandbox or production
    'merchant_key' => env('WALLETPLUG_MERCHANT_KEY'), // Use appropriate prefix
    'api_key' => env('WALLETPLUG_API_KEY'), // Use appropriate prefix
];

// Usage in Controller
class PaymentController extends Controller
{
    public function initiatePayment(Request $request, WalletPlugService $walletplug)
    {
        $paymentData = [
            'payment_amount' => $request->amount,
            'currency_code' => 'USD',
            'ref_trx' => 'ORDER_' . time(),
            'description' => $request->description,
            'success_redirect' => route('payment.success'),
            'failure_url' => route('payment.failed'),
            'cancel_redirect' => route('payment.cancelled'),
            'ipn_url' => route('webhooks.walletplug'),
        ];

        try {
            $result = $walletplug->initiatePayment($paymentData);
            return redirect($result['payment_url']);
        } catch (Exception $e) {
            return back()->withErrors(['error' => $e->getMessage()]);
        }
    }
}

// Node.js Integration Service
const axios = require('axios');

class WalletPlugService {
    constructor() {
        this.baseUrl = process.env.WALLETPLUG_BASE_URL || 'https://walletplug.com';
        this.environment = process.env.WALLETPLUG_ENVIRONMENT || 'sandbox'; // sandbox or production
        this.merchantKey = process.env.WALLETPLUG_MERCHANT_KEY; // Use appropriate prefix
        this.apiKey = process.env.WALLETPLUG_API_KEY; // Use appropriate prefix
    }

    async initiatePayment(paymentData) {
        try {
            const response = await axios.post(`${this.baseUrl}/api/v1/initiate-payment`, paymentData, {
                headers: {
                    'Content-Type': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            return response.data;
        } catch (error) {
            throw new Error(`WalletPlug API Error: ${error.message}`);
        }
    }

    async verifyPayment(transactionId) {
        try {
            const response = await axios.get(`${this.baseUrl}/api/v1/verify-payment/${transactionId}`, {
                headers: {
                    'Accept': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            return response.data;
        } catch (error) {
            throw new Error(`WalletPlug API Error: ${error.message}`);
        }
    }
}

// Express.js Route Example
const express = require('express');
const app = express();
const walletplug = new WalletPlugService();

app.post('/initiate-payment', async (req, res) => {
    const paymentData = {
        payment_amount: req.body.amount,
        currency_code: 'USD',
        ref_trx: `ORDER_${Date.now()}`,
        description: req.body.description,
        success_redirect: `${req.protocol}://${req.get('host')}/payment/success`,
        failure_url: `${req.protocol}://${req.get('host')}/payment/failed`,
        cancel_redirect: `${req.protocol}://${req.get('host')}/payment/cancelled`,
        ipn_url: `${req.protocol}://${req.get('host')}/webhooks/walletplug`,
    };

    try {
        const result = await walletplug.initiatePayment(paymentData);
        res.redirect(result.payment_url);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

module.exports = WalletPlugService;

# Python/Django Integration Service
import os
import requests
from django.conf import settings

class WalletPlugService:
    def __init__(self):
        self.base_url = getattr(settings, 'WALLETPLUG_BASE_URL', 'https://walletplug.com')
        self.environment = getattr(settings, 'WALLETPLUG_ENVIRONMENT', 'sandbox')  # sandbox or production
        self.merchant_key = getattr(settings, 'WALLETPLUG_MERCHANT_KEY')  # Use appropriate prefix
        self.api_key = getattr(settings, 'WALLETPLUG_API_KEY')  # Use appropriate prefix

    def initiate_payment(self, payment_data):
        try:
            headers = {
                'Content-Type': 'application/json',
                'X-Environment': self.environment,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.post(
                f"{self.base_url}/api/v1/initiate-payment",
                headers=headers,
                json=payment_data,
                timeout=30
            )

            response.raise_for_status()
            return response.json()

        except requests.RequestException as e:
            raise Exception(f'WalletPlug API Error: {str(e)}')

    def verify_payment(self, transaction_id):
        try:
            headers = {
                'Accept': 'application/json',
                'X-Environment': self.environment,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.get(
                f"{self.base_url}/api/v1/verify-payment/{transaction_id}",
                headers=headers,
                timeout=30
            )

            response.raise_for_status()
            return response.json()

        except requests.RequestException as e:
            raise Exception(f'WalletPlug API Error: {str(e)}')

# Django Settings Configuration
WALLETPLUG_BASE_URL = 'https://walletplug.com'
WALLETPLUG_ENVIRONMENT = 'sandbox'  # Change to 'production' for live
WALLETPLUG_MERCHANT_KEY = os.environ.get('WALLETPLUG_MERCHANT_KEY')  # Use appropriate prefix
WALLETPLUG_API_KEY = os.environ.get('WALLETPLUG_API_KEY')  # Use appropriate prefix

# Django View Example
from django.shortcuts import redirect
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
import json

walletplug = WalletPlugService()

@csrf_exempt
def initiate_payment(request):
    if request.method == 'POST':
        data = json.loads(request.body)
        
        payment_data = {
            'payment_amount': data['amount'],
            'currency_code': 'USD',
            'ref_trx': f'ORDER_{int(time.time())}',
            'description': data['description'],
            'success_redirect': request.build_absolute_uri('/payment/success/'),
            'failure_url': request.build_absolute_uri('/payment/failed/'),
            'cancel_redirect': request.build_absolute_uri('/payment/cancelled/'),
            'ipn_url': request.build_absolute_uri('/webhooks/walletplug/'),
        }

        try:
            result = walletplug.initiate_payment(payment_data)
            return redirect(result['payment_url'])
        except Exception as e:
            return JsonResponse({'error': str(e)}, status=500)

# Environment Variables Setup
export WALLETPLUG_ENVIRONMENT="sandbox"  # or "production"
export WALLETPLUG_MERCHANT_KEY="test_merchant_your_key"  # or "merchant_your_key" for production
export WALLETPLUG_API_KEY="test_your_api_key"  # or "your_api_key" for production

# Initiate Payment
curl -X POST "https://walletplug.com/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "X-Environment: $WALLETPLUG_ENVIRONMENT" \
  -H "X-Merchant-Key: $WALLETPLUG_MERCHANT_KEY" \
  -H "X-API-Key: $WALLETPLUG_API_KEY" \
  -d '{
    "payment_amount": 250.00,
    "currency_code": "USD",
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "success_redirect": "https://yoursite.com/payment/success",
    "failure_url": "https://yoursite.com/payment/failed",
    "cancel_redirect": "https://yoursite.com/payment/cancelled",
    "ipn_url": "https://yoursite.com/api/webhooks/walletplug"
  }'

# Verify Payment
curl -X GET "https://walletplug.com/api/v1/verify-payment/TXNQ5V8K2L9N3XM1" \
  -H "Accept: application/json" \
  -H "X-Environment: $WALLETPLUG_ENVIRONMENT" \
  -H "X-Merchant-Key: $WALLETPLUG_MERCHANT_KEY" \
  -H "X-API-Key: $WALLETPLUG_API_KEY"

# Environment-specific credential examples:
# Sandbox: test_merchant_xxxxx, test_api_key_xxxxx
# Production: merchant_xxxxx, api_key_xxxxx

Mobile SDKs (Android & iOS)

Official lightweight clients for integrating WalletPlug payments in native mobile apps.

https://walletplug.com

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    // org.json is available in Android SDK
}

val client = WalletplugClient(
    WalletplugConfig(
        baseUrl = "https://walletplug.com",
        merchantKey = "test_merchant_key", // or live key
        apiKey = "test_api_key",           // or live key
        environment = EnvironmentMode.SANDBOX // or PRODUCTION
    )
)

val req = InitiatePaymentRequest(
    payment_amount = 250.00,
    currency_code = "USD",
    ref_trx = "ORDER_12345",
    description = "Premium Subscription",
    success_redirect = "https://yoursite.com/payment/success",
    failure_url = "https://yoursite.com/payment/failed",
    cancel_redirect = "https://yoursite.com/payment/cancelled",
    ipn_url = "https://yoursite.com/api/webhooks/walletplug",
    allow_payment_methods = listOf("card", "wallet"),
    customer_name = "John Doe",
    customer_email = "john@example.com"
)

val res = client.initiatePayment(req)
// Open res.paymentUrl in Custom Tabs/WebView to complete checkout

val verification = client.verifyPayment("TXNQ5V8K2L9N3XM1")
// Handle status: success | pending | failed

let client = WalletplugClient(
    config: WalletplugConfig(
        baseURL: URL(string: "https://walletplug.com")!,
        merchantKey: "test_merchant_key", // or live key
        apiKey: "test_api_key",           // or live key
        environment: .sandbox              // or .production
    )
)

let req = InitiatePaymentRequest(
    payment_amount: 250.0,
    currency_code: "USD",
    ref_trx: "ORDER_12345",
    description: "Premium Subscription",
    success_redirect: "https://yoursite.com/payment/success",
    failure_url: "https://yoursite.com/payment/failed",
    cancel_redirect: "https://yoursite.com/payment/cancelled",
    ipn_url: "https://yoursite.com/api/webhooks/walletplug",
    allow_payment_methods: ["card", "wallet"],
    customer_name: "John Doe",
    customer_email: "john@example.com"
)

client.initiatePayment(req) { result in
    switch result {
    case .success(let payload):
        let paymentUrl = payload.paymentUrl
        // Present SFSafariViewController / ASWebAuthenticationSession with paymentUrl
    case .failure(let error):
        print("Initiation failed: \(error)")
    }
}

client.verifyPayment(trxId: "TXNQ5V8K2L9N3XM1") { result in
    print(result)
}

React Native SDK

WalletPlug provides an official React Native SDK for building payment flows in any React Native or Expo mobile app. The SDK includes a drop-in WalletPlugCheckout WebView component, a useWalletPlug hook, typed API client, and full TypeScript support. Compatible with React Native 0.68+ and all Expo SDK versions.

# React Native CLI
npm install walletplug-react-native react-native-webview
cd ios && pod install

# Expo
npx expo install walletplug-react-native react-native-webview

import React, { useState } from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import WalletPlug, { WalletPlugCheckout, useWalletPlug } from 'walletplug-react-native';

// Initialise once — outside your component
const wp = WalletPlug.sandbox('test_merchant_key', 'test_api_key');
// For production: WalletPlug.production('merchant_key', 'api_key')

export default function CheckoutScreen({ navigation, route }) {
  const { order } = route.params;
  const { initiatePayment, verifyPayment, loading, error, paymentResult, clearError } = useWalletPlug(wp);

  const handlePay = async () => {
    await initiatePayment({
      amount:      order.total,
      currency:    'USD',
      reference:   `ORDER_${order.id}_${Date.now()}`,
      description: `Order #${order.id}`,
      // Your backend handles the webhook — not the mobile app
      successUrl:  'walletplug://payment/success',
      failureUrl:  'walletplug://payment/failure',
      cancelUrl:   'walletplug://payment/cancel',
      webhookUrl:  'https://your-backend.com/webhook/walletplug',
    });
  };

  const handleSuccess = async (trxId) => {
    // Optionally verify the payment from your app
    const payment = await verifyPayment(trxId);
    navigation.replace('OrderConfirmation', {
      orderId: order.id,
      status:  payment?.status,
      trxId,
    });
  };

  // Show checkout WebView when paymentUrl is ready
  if (paymentResult) {
    return (
      <WalletPlugCheckout
        paymentUrl={paymentResult.paymentUrl}
        onSuccess={handleSuccess}
        onFailure={(err) => navigation.navigate('PaymentFailed', { error: err })}
        onCancel={() => navigation.goBack()}
        showCloseButton={true}
        closeButtonLabel="Cancel Payment"
      />
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Order #{order.id}</Text>
      <Text style={styles.amount}>${order.total} USD</Text>

      {error && (
        <View style={styles.errorBox}>
          <Text style={styles.errorText}>{error}</Text>
          <Button title="Try Again" onPress={clearError} />
        </View>
      )}

      <Button
        title={loading ? 'Please wait...' : 'Pay with WalletPlug'}
        onPress={handlePay}
        disabled={loading}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 24, gap: 16 },
  title:     { fontSize: 22, fontWeight: '600', textAlign: 'center' },
  amount:    { fontSize: 32, fontWeight: '700', textAlign: 'center', color: '#0066cc' },
  errorBox:  { backgroundColor: '#fef2f2', padding: 12, borderRadius: 8 },
  errorText: { color: '#dc2626', marginBottom: 8 },
});

Flutter SDK

WalletPlug provides an official Flutter SDK published on pub.dev. Accept international payments in any Flutter mobile, web, or desktop app with a drop-in WalletPlugCheckout widget, typed Dart models, a full exception hierarchy, and HMAC-SHA256 webhook verification. Compatible with Flutter 3.7+, Dart 2.19+, iOS 12+, Android API 21+, and all Dart server frameworks including Dart Frog and Shelf.

dependencies:
  walletplug: ^1.0.0

flutter pub get

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

<uses-permission android:name="android.permission.INTERNET"/>

import 'package:walletplug/walletplug.dart';

// Initialise once — outside your widget tree
final wp = WalletPlug(
  merchantKey: const String.fromEnvironment('WALLETPLUG_MERCHANT_KEY'),
  apiKey:      const String.fromEnvironment('WALLETPLUG_API_KEY'),
  environment: WalletPlugEnvironment.sandbox,
);
wp.setWebhookSecret(
  const String.fromEnvironment('WALLETPLUG_WEBHOOK_SECRET'),
);

import 'package:flutter/material.dart';
import 'package:walletplug/walletplug.dart';

final wp = WalletPlug.sandbox('test_merchant_key', 'test_api_key');

class CheckoutPage extends StatefulWidget {
  const CheckoutPage({super.key, required this.orderId, required this.amount});
  final String orderId;
  final double amount;
  @override
  State<CheckoutPage> createState() => _CheckoutPageState();
}

class _CheckoutPageState extends State<CheckoutPage> {
  bool _loading = false;
  String? _error;

  Future<void> _pay() async {
    setState(() { _loading = true; _error = null; });

    try {
      final result = await wp.payments.initiate(
        amount:      widget.amount,
        currency:    'USD',
        reference:   'ORDER_${widget.orderId}',
        description: 'Order #${widget.orderId}',
        successUrl:  'walletplug://payment/success',
        failureUrl:  'walletplug://payment/failure',
        cancelUrl:   'walletplug://payment/cancel',
        webhookUrl:  'https://your-backend.com/webhook',
        // Optional: restrict payment methods
        // allowPaymentMethods: ['card', 'mobile_money'],
      );

      if (!mounted) return;

      await Navigator.push(
        context,
        MaterialPageRoute(
          builder: (_) => WalletPlugCheckout(
            paymentUrl: result.paymentUrl,
            onSuccess: (trxId) async {
              Navigator.pop(context);
              // Optionally verify on-device
              final payment = await wp.payments.verify(trxId);
              if (payment.isCompleted) showSuccess(payment);
            },
            onFailure: (error) {
              Navigator.pop(context);
              setState(() => _error = error);
            },
            onCancel: () => Navigator.pop(context),
          ),
        ),
      );
    } on WalletPlugAuthException {
      setState(() => _error = 'Invalid credentials.');
    } on WalletPlugNetworkException {
      setState(() => _error = 'Network error. Check your connection.');
    } on WalletPlugException catch (e) {
      setState(() => _error = e.message);
    } finally {
      if (mounted) setState(() => _loading = false);
    }
  }

  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('Checkout')),
    body: Padding(
      padding: const EdgeInsets.all(24),
      child: Column(
        children: [
          if (_error != null) Text(_error!, style: const TextStyle(color: Colors.red)),
          const Spacer(),
          FilledButton.icon(
            onPressed: _loading ? null : _pay,
            icon: _loading
              ? const SizedBox(width:16,height:16,child:CircularProgressIndicator(strokeWidth:2,color:Colors.white))
              : const Icon(Icons.payment),
            label: Text(_loading ? 'Please wait…' : 'Pay \$${widget.amount.toStringAsFixed(2)}'),
            style: FilledButton.styleFrom(minimumSize: const Size.fromHeight(50)),
          ),
        ],
      ),
    ),
  );
}

// Verify a payment
final payment = await wp.payments.verify('TXNQ5V8K2L9N3XM1');
print(payment.status);       // PaymentStatus.completed
print(payment.amount);       // 99.99
print(payment.currency);     // USD
print(payment.isCompleted);  // true
print(payment.customer.name);

// Issue a partial refund
final refund = await wp.payments.refund(
  trxId:     'TXNQ5V8K2L9N3XM1',
  amount:    50.00,                      // omit for full refund
  reason:    'Customer requested refund',
  refRefund: 'REFUND_${orderId}',        // idempotency key
);
print(refund.status);    // RefundStatus.processing
print(refund.refundId);

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:scheme="walletplug"/>
</intent-filter>

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>walletplug</string>
    </array>
  </dict>
</array>

WooCommerce Integration

Advanced WalletPlug payment gateway for WooCommerce — fully mobile-responsive checkout, WooCommerce Blocks (Gutenberg) support, HPOS compatible, refund support, and enterprise-grade HMAC webhook security. Compatible with WooCommerce 7.0+ on WordPress 5.8+. Version 2.0.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

Shopify Integration

Accept WalletPlug payments directly inside your Shopify store with a fully offsite payment gateway plugin — supporting sandbox testing, real-time webhook order updates, and one-click deployment.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

OpenCart Integration

Accept WalletPlug payments directly inside your OpenCart store with a native payment gateway extension — supporting sandbox testing, HMAC-verified webhooks, and automatic order status updates.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

PrestaShop Integration

Accept WalletPlug payments natively inside your PrestaShop store — a full payment module with offsite checkout, HMAC-verified IPN webhooks, sandbox/production switching, and automatic order status management. Compatible with PrestaShop 1.7.x and 8.x.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

Magento / Adobe Commerce Integration

Accept WalletPlug payments natively inside your Magento 2 or Adobe Commerce store — a full payment module with offsite checkout, HMAC-verified IPN webhooks, encrypted credential storage, and automatic order state management. Compatible with Magento 2.4.x and Adobe Commerce 2.4.x.

bin/magento module:enable WalletPlug_Pay
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

BigCommerce Integration

Accept WalletPlug payments inside your BigCommerce store via a hosted app — OAuth-based installation, HMAC-verified webhooks, automatic order status updates, and a lightweight checkout script injected via BigCommerce Script Manager.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

Easy Digital Downloads Integration

Accept WalletPlug payments inside your Easy Digital Downloads store — a native WordPress payment gateway with offsite checkout, HMAC-verified IPN webhooks, automatic payment status updates, and purchase receipt emails triggered on completion. Compatible with EDD 3.0+ on WordPress 5.8+.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

CS-Cart / Multi-Vendor Integration

Accept WalletPlug payments natively inside your CS-Cart or Multi-Vendor store — a full payment addon with offsite checkout, HMAC-verified IPN webhooks, automatic order status updates, and Multi-Vendor marketplace support. Compatible with CS-Cart 4.14+ and Multi-Vendor 4.14+.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

Gravity Forms Integration

Accept WalletPlug payments inside any Gravity Forms form — donations, order forms, event registrations, membership signups, and bookings. A native Gravity Forms payment addon built on the GF Payment Addon Framework with HMAC-verified webhooks, per-form feed configuration, and automatic GF entry status management. Compatible with Gravity Forms 2.6+ on WordPress 5.8+.

Ecwid / Lightspeed E-Series Integration

Accept WalletPlug payments in your Ecwid or Lightspeed E-Series store using Ecwid's Custom Payment Method API. The plugin runs as a WordPress companion app — no coding required, full HMAC-verified webhook support, and automatic Ecwid order status updates via the Ecwid REST API. Compatible with Ecwid Free, Venture, Business, and Unlimited plans and Lightspeed E-Series.

WHMCS Integration

Integrate WalletPlug as an offsite/redirect payment gateway in WHMCS with secure webhooks and API-compatible payloads.

{your_whmcs_url}/modules/gateways/callback/walletplug.php

/modules/gateways/walletplug.php
/modules/gateways/callback/walletplug.php

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

{
  "payment_amount": 100.00,
  "currency_code": "USD",
  "ref_trx": "{invoiceId}",
  "description": "Invoice #{invoiceId}",
  "success_redirect": "{whmcs}/viewinvoice.php?id={invoiceId}",
  "failure_url": "{whmcs}/viewinvoice.php?id={invoiceId}",
  "cancel_redirect": "{whmcs}/viewinvoice.php?id={invoiceId}",
  "ipn_url": "{whmcs}/modules/gateways/callback/walletplug.php"
}

Bubble.io Integration

Accept WalletPlug payments inside your Bubble no-code app using three server-side actions — Initiate Payment, Verify Payment, and Refund Payment. A lightweight companion server handles HMAC-verified webhook delivery to your Bubble Data API. Compatible with all Bubble plans.

GiveWP Integration

Accept WalletPlug donations in any GiveWP donation form — the first truly global all-in-one donation gateway for GiveWP. Cards, mobile money, bank transfers, wallets, crypto, and vouchers in 135+ countries. Compatible with GiveWP 3.0+ on WordPress 5.8+.

WPForms Integration

Accept WalletPlug payments in any WPForms form — order forms, deposits, event registrations, and bookings. Supports all payment methods globally including mobile money, cards, wallets, bank transfers, and crypto. The first truly international payment addon for WPForms' 5 million active installs. Compatible with WPForms 1.8+ on WordPress 5.8+.

Webflow Integration

Accept WalletPlug payments in any Webflow site using a lightweight companion server and a custom code embed. The first global all-in-one payment solution for Webflow merchants outside Stripe and PayPal's supported countries — covering 135+ countries, mobile money, crypto, and local bank transfers that Webflow's built-in gateways don't support. Compatible with all Webflow plans including Starter.

<!-- Option A: HTML Embed element in Webflow -->
<button
  data-walletplug-pay
  data-amount="99.99"
  data-currency="USD"
  data-order-id="ORDER_001"
  data-description="Premium Plan"
  data-customer-email="customer@email.com"
  style="padding:14px 28px;background:#4353ff;color:#fff;border:none;border-radius:8px;font-size:15px;cursor:pointer;"
>
  Pay with WalletPlug
</button>

<!-- Option B: Webflow native button with Custom Attributes -->
<!-- Add data-walletplug-pay, data-amount, data-currency, data-order-id -->
<!-- in Webflow Designer → Element Settings → Custom Attributes -->

Squarespace Integration

Accept WalletPlug payments on any Squarespace site — the first global all-in-one payment solution for Squarespace merchants who need more than the built-in options. Cards, mobile money, bank transfers, wallets, and crypto in 135+ countries. Fully mobile-responsive embed — works on all Squarespace 7.0 and 7.1 templates. Compatible with all Squarespace plans.

<!-- WalletPlug Pay Button — paste into Squarespace Code Block -->
<button
  class="wp-pay-btn"
  onclick="WalletPlugSquarespace.pay()"
  data-amount="99.99"
  data-currency="USD"
  data-order-id="ORDER_001"
  data-description="Product Name"
>
  Pay with WalletPlug
</button>
<!-- Full CSS + JS included in squarespace-embed.html -->

LearnDash LMS Integration

Accept WalletPlug payments directly in LearnDash course and group checkouts — the first truly global payment gateway for LearnDash LMS. Cards, mobile money, bank transfers, wallets, and crypto in 135+ countries. Compatible with LearnDash 4.0+ on WordPress 5.8+.