README

English ｜ 简体中文

A PHP library that automatically cracks Alipay bill ZIP passwords and extracts transaction details. Combined with email monitoring scripts, it enables fully automated bill collection and parsing.

Warning

This project is for learning and communication purposes only. Commercial or illegal use is strictly prohibited.

Want a quick overview? The codebase has been parsed by Zread.

Features

• 🔐 Automatic password cracking: Built-in C-based multithreaded brute-force tool for 6-digit numeric passwords, significantly faster than pure PHP implementations
• 📦 No manual extraction: Automatically detects encrypted ZIP files, extracts them, and reads the CSV bill file inside
• 📄 Smart encoding detection: Auto-detects UTF-8 / GBK / CP936 encodings to prevent garbled Chinese characters
• 🧩 Callback-driven flow control: Flexibly control the parsing process via callbacks — retrieve only the password, only the data, or abort at any stage
• 📬 Automation-friendly: Works with email monitoring scripts to achieve fully automated bill processing

Requirements

• PHP >= 8.1
• PHP extensions: ext-zip, ext-mbstring
• libzip development library (for compiling the C brute-force tool)
• GCC (usually pre-installed on macOS / Linux; Windows users need a pre-compiled zip_bruteforce.exe)

Installing libzip

# macOS
brew install libzip

# Ubuntu / Debian
sudo apt install libzip-dev

Windows users are recommended to use WSL, or use a pre-compiled zip_bruteforce.exe.

Installation

composer require hejunjie/alipay-bill-parser

On first use, the library automatically detects the libzip environment and compiles the C brute-force tool. If compilation fails, make sure libzip is properly installed.

Quick Start

use Hejunjie\AlipayBillParser\AlipayBillParser;
use Hejunjie\AlipayBillParser\ParseOptions;

$zipFile = '/path/to/alipay-transactions(20240501-20250430).zip';

$options = new ParseOptions($zipFile);
$options->onPasswordFound = function ($password) {
    echo "Password: $password\n";
    return true; // Return false to abort subsequent parsing
};
$options->onDataParsed = function ($data) {
    echo "Name: " . $data['real_name'] . PHP_EOL;
    echo "Account: " . $data['account'] . PHP_EOL;
    echo "Total records: " . count($data['data']) . "\n";
    return true;
};

$parser = new AlipayBillParser();
$parser->parse($options);

Usage

Get password only

$options = new ParseOptions('/path/to/bill.zip');
$options->onPasswordFound = function ($password) {
    echo "Password: $password\n";
    return false; // Return false to skip CSV parsing
};

(new AlipayBillParser())->parse($options);

Get bill data only (when password is known)

If you already know the ZIP password, you can ignore it in the onPasswordFound callback and let the flow proceed to data extraction. Alternatively, extend ZipPasswordCracker to skip the brute-force step entirely.

Output data structure

The $data array passed to the onDataParsed callback:

[
    'real_name' => '张三',           // Alipay real name
    'account'   => '18273727771',    // Registered account (phone number or email)
    'data'      => [
        // Each record contains 12 fields
        ['Transaction Time', 'Transaction Category', 'Counterparty', 'Counterparty Account', 'Product Description', 'Income/Expense', 'Amount', 'Payment Method', 'Transaction Status', 'Transaction Order No.', 'Merchant Order No.', 'Remarks'],
        // ...
    ],
]

Directory Structure

├── bin/zip_bruteforce.c    # C source code for the brute-force tool
├── resources/               # Compiled binary (zip_bruteforce executable)
├── src/
│   ├── AlipayBillParser.php    # Entry point, orchestrates the parsing pipeline
│   ├── ParseOptions.php        # Options DTO (ZIP path + callbacks)
│   ├── ZipPasswordCracker.php  # Password cracker (invokes the C binary)
│   ├── CsvExtractor.php        # ZIP extraction and CSV parsing
│   └── Installer.php           # libzip environment detection and C compilation
├── composer.json
├── README.md
└── README.zh-CN.md

FAQ

"zip_bruteforce executable not found and cannot be auto-compiled"

Your system is likely missing the libzip development library or GCC. Install the required dependencies as described in the Requirements section and try again.

Password cracking failed with a non-zero exit code

Alipay bill ZIP passwords are typically 6-digit numbers. This tool brute-forces the range 000000–999999. If the password falls outside this range (e.g., alphanumeric), cracking will fail.

Garbled Chinese characters in CSV output

The library includes automatic UTF-8 / GBK / CP936 detection and conversion, so garbled text should not occur under normal circumstances. If you encounter an unexpected encoding, please file an issue with a sanitized sample of the bill file.

Which Alipay bill formats are supported?

This tool is designed for the "Transaction Details" ZIP file exported from the Alipay web portal. Other bill export formats may not be compatible.

Motivation

I maintain a personal finance tracker, but the bill formats exported by Alipay and WeChat are inconsistent and often arrive as encrypted ZIP files. Manually processing them every time was tedious. So I built this tool — paired with automatic email forwarding, it parses bill emails into structured data with a single step, eliminating download, extraction, and manual verification. Hopefully it helps others with the same need.

Contact

For questions or suggestions, feel free to open an issue.