SimpleCMS Payment

中文 | English

A payment package for the SimpleCMS ecosystem with a unified payment adapter layer, callback verification, refund tracking, and lifecycle events.

Highlights

• Unified channel contract for payment adapters
• WeChat Pay and Alipay support
• Additional V1.5 channels: PayPal, Stripe, USDT-TRC20, USDT-ERC20, BTC, ETH
• Standardized callback normalization and webhook verification
• Idempotent lifecycle handling with terminal-state protection
• Refund state synchronization and event-driven status updates
• Configurable route prefix, currency, and channel-specific secrets

Requirements

• PHP >= 8.1
• SimpleCMS Framework >= 1.0
• Composer 2

Installation

composer require simplecms/payment

If your Laravel or SimpleCMS application does not discover package providers automatically, register them manually:

// config/app.php
'providers' => [
    SimpleCMS\Payment\PaymentServiceProvider::class,
],

'aliases' => [
    'Payment' => SimpleCMS\Payment\Facades\Payment::class,
],

Configuration

The package reads channel and route settings from config/cms_payment.php. Keep secrets in the environment and never commit them to source control.

Supported channels

use SimpleCMS\Payment\Enums\ChannelEnum;

ChannelEnum::Wechat->value;    // 1
ChannelEnum::Alipay->value;    // 2
ChannelEnum::Paypal->value;    // 3
ChannelEnum::Stripe->value;     // 4
ChannelEnum::USDTTRC20->value; // 5
ChannelEnum::USDTERC20->value; // 6
ChannelEnum::BTC->value;        // 7
ChannelEnum::ETH->value;        // 8

Model requirement

Your order model should implement the HasPayment contract:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphOne;
use SimpleCMS\Payment\HasPayment;

class Order extends Model implements HasPayment
{
    public function payment(): MorphOne
    {
        return $this->morphOne(\SimpleCMS\Payment\Models\Payment::class, 'order');
    }

    public function getOrderKey(): string
    {
        return 'order_no';
    }
}

Create a payment

use SimpleCMS\Payment\Enums\ChannelEnum;
use SimpleCMS\Payment\Facades\Payment;

$result = Payment::create($order, 99.99, ChannelEnum::Wechat->value, 'Test order');

V2 operational flow

The operational V2 flow is integrated into the main payment facade so it is used as part of the same package runtime instead of as a separate standalone API.

use SimpleCMS\Payment\Facades\Payment;

$transfer = Payment::transferCreate([
    'order_no' => 'TXN-1001',
    'amount' => 199.99,
    'channel' => 'wechat',
]);

$approval = Payment::approvalRun('withdrawal', [
    'amount' => 15000,
    'channel' => 'wechat',
]);

$reconciliation = Payment::reconciliationRun('wechat', '2024-06-30');

Host app integration example

In a Laravel or SimpleCMS application, register the package provider and then use the main payment facade for both the original payment flows and the V2 operational flows from the same runtime:

// config/app.php
'providers' => [
    SimpleCMS\Payment\PaymentServiceProvider::class,
],

'aliases' => [
    'Payment' => SimpleCMS\Payment\Facades\Payment::class,
],

use SimpleCMS\Payment\Facades\Payment;

public function dispatchWithdrawal(): array
{
    return Payment::transferCreate([
        'order_no' => 'WITHDRAW-2026-001',
        'amount' => 2500,
        'channel' => 'wechat',
        'direction' => 'out',
    ]);
}

The same runtime can be used for operational tasks like risk checks, settlement runs, and reconciliation at scheduled intervals.

Callback and verification

The callback service standardizes provider payloads and verifies signatures before changing payment state.

• Stripe: verifies the Stripe-Signature header against the webhook secret
• PayPal: validates transmission metadata and webhook identity
• Replay and terminal-state updates are blocked to prevent stale callback overwrites

Events

use SimpleCMS\Payment\Models\Payment;

Event::listen('plugin.payment.created', function (Payment $payment) {
    // created
});

Event::listen('plugin.payment.pending', function (Payment $payment) {
    // awaiting payment
});

Event::listen('plugin.payment.paid', function (Payment $payment) {
    // payment succeeded
});

Event::listen('plugin.payment.refunding', function (Payment $payment) {
    // refund in progress
});

Event::listen('plugin.payment.refunded', function (Payment $payment) {
    // refund succeeded
});

Event::listen('plugin.payment.close', function (Payment $payment) {
    // payment closed
});

Notes

• Keep secrets in .env or your deployment secret manager.
• Do not commit certificate files, keys, or webhook secrets.
• Ensure your application exposes payment callback routes and handles provider webhook headers correctly.
• This package is designed for Laravel/SimpleCMS integration and uses an adapter-based architecture for provider expansion.

License

MIT