mcpField
P
payment-reconciliation-automation

payment-reconciliation-automation

github.com/finsilabs其他6082 次安装5 天前更新
代码仓库

关于 payment-reconciliation-automation

为电商财务团队提供支付对账自动化指导,将支付处理商的收款与会计记录及银行入账进行核对。内容涵盖同步工具选择、自定义处理流程,以及手续费、退款、拒付和多币种等差异。

主要功能

  1. 01按电商平台选择对账工具
  2. 02连接支付处理商与会计系统
  3. 03核对手续费、退款和拒付
  4. 04使用 Stripe 余额交易构建自定义流程
  5. 05设置每日差异监控

适用场景

  1. 01减少人工核对支付交易的工作
  2. 02处理多个支付处理商的交易
  3. 03解决月末未匹配款项
  4. 04将退款和拒付准确记入账目

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/finsilabs/awesome-ecommerce-skills --skill payment-reconciliation-automation

安装后在 Claude Code 中输入/payment-reconciliation-automation确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

tile.json
evals/database-schema-and-alerting/
criteria.json
task.md
evals/matching-engine-with-tolerances/
criteria.json
task.md
evals/transaction-ingestion-pipeline/
criteria.json
task.md

详细介绍

支付对账自动化

概述

支付对账会将支付处理商(Stripe、PayPal、Shopify Payments)声称收取的金额,与会计系统记录的金额以及银行实际收到的金额进行匹配。在大多数电商设置中,支付处理商费用、退款、拒付、滚动准备金和货币兑换都不会自动记入日记账,因此会产生差异。每天手动对账的交易量超过几百笔后,就难以扩展。

对大多数商家而言,自动对账的解决方案是使用专用同步工具,将电商平台连接到会计系统(QuickBooks、Xero),而不是自行构建匹配逻辑。

何时使用此技能

  • 财务团队每天花费超过两小时手动进行支付对账时
  • 通过两个或更多支付处理商处理交易时(例如,Stripe + PayPal)
  • 月末结账因尚未解决的支付差异而受阻时
  • 拒付或退款未能可靠地反映在会计系统中时
  • 需要支付流程的 SOC 2 或 PCI-DSS 审计文档时

核心说明

步骤 1:确定平台并选择对账方式
平台推荐的对账工具说明
Shopify PaymentsA2X 或 Bench AccountingA2X 会自动将 Shopify 付款映射到 QuickBooks/Xero 日记账分录,并处理费用、退款和调整
Shopify + StripeA2X for Stripe + A2X for Shopify将两个来源都连接到 QuickBooks/Xero;A2X 会分别对账每笔付款
WooCommerce + StripeSynder 或 WooCommerce QuickBooks Online 插件Synder 会将每笔 Stripe 交易同步到 QuickBooks,并单独列出费用
WooCommerce + PayPalSynder 或 PayPal for WooCommerce + QuickBooksSynder 可通过一个连接同时处理 Stripe 和 PayPal
BigCommerceA2X(提供 BigCommerce 连接器)或 Synder与 Shopify 的方式相同
自定义 / 无头架构使用 Stripe Balance Transactions API 构建对账管道请参阅下方的“自定义 / 无头架构”部分

经验法则:如果你使用 Shopify、WooCommerce 或 BigCommerce,请先使用 A2X 或 Synder,再考虑自行构建。这些工具每月费用为 $25–$100,可省去数周的开发工作。

步骤 2:使用同步工具设置自动对账

Shopify(推荐使用 A2X)
  1. 前往 a2xaccounting.com 注册并安装 Shopify 应用
  2. 连接 Shopify 商店:前往 A2X → Connect a store → Shopify 并授权
  3. 连接会计系统:前往 A2X → Settings → Accounting,连接 QuickBooks Online 或 Xero
  4. 配置科目映射:
    • 在 A2X 中,将 Shopify 的销售额、退款、费用和调整映射到你的会计科目表
    • 将 Shopify Payments 费用映射到“Merchant Fees”费用科目
    • 将礼品卡销售映射到负债科目(而非收入科目)
  5. 每笔 Shopify 付款到账后,A2X 都会自动进行处理,并在 QuickBooks/Xero 中创建汇总日记账分录,使其与银行存款金额完全一致

A2X 自动处理的内容:

  • 从付款中扣除的 Shopify 处理费用
  • 与原始销售发生在不同期间的退款
  • 拒付及拒付撤销
  • 礼品卡兑换与购买
  • 多币种兑换
WooCommerce(Synder — 推荐)
  1. 在 synderapp.com 注册,并通过插件连接 WooCommerce 商店(从 WordPress.org 安装)
  2. 连接支付处理商:前往 Synder → Settings → Platforms,使用 API 密钥连接 Stripe 和/或 PayPal
  3. 在 Synder → Settings → Accounting 下连接 QuickBooks Online 或 Xero
  4. 配置交易分类:将产品类别映射到收入科目,将手续费映射到支出科目
  5. Synder 会以近乎实时的速度同步每笔交易,分别记录总金额和支付处理商手续费

Synder 与 A2X 在 WooCommerce 上的对比:Synder 按交易级别处理(每笔交易对应一条 QuickBooks 记录);A2X 按付款级别处理(每笔存款对应一条汇总记录)。Synder 更适合详细报告;A2X 更适合交易量大的商店。

BigCommerce
  1. 从 BigCommerce 应用市场安装 A2X
  2. 按照上文 Shopify 部分的相同设置流程操作——A2X 的 BigCommerce 连接器与 Shopify 连接器的工作方式相同
  3. 将支付网关(Stripe 或 PayPal)单独连接到 A2X,以便进行包含支付处理商手续费的完整对账

自定义/无头

对于自定义店面,请构建一个对账流程,以 Stripe 的余额交易(每笔资金流动的权威记录)为事实来源:

// Ingest Stripe balance transactions — the only feed that includes fees, refunds, and payouts
async function ingestStripeTransactions(startDate, endDate) {
  const transactions = [];

  for await (const txn of stripe.balanceTransactions.list({
    created: {
      gte: Math.floor(new Date(startDate).getTime() / 1000),
      lte: Math.floor(new Date(endDate).getTime() / 1000),
    },
    limit: 100,
    expand: ['data.source'],
  })) {
    const orderId = txn.source?.metadata?.order_id;

    transactions.push({
      stripe_id: txn.id,
      type: txn.type,            // 'charge', 'refund', 'payout', 'stripe_fee'
      gross: txn.amount / 100,   // in dollars
      fee: txn.fee / 100,
      net: txn.net / 100,
      currency: txn.currency.toUpperCase(),
      date: new Date(txn.created * 1000),
      order_id: orderId ?? null,
      description: txn.description,
    });
  }

  return transactions;
}

// Match Stripe transactions to internal order records
async function reconcileDay(date) {
  const stripeTxns = await ingestStripeTransactions(date, date);
  const internalOrders = await db.orders.findMany({
    where: { createdAt: { gte: startOfDay(date), lte: endOfDay(date) }, status: 'confirmed' },
  });

  const matched = [];
  const exceptions = [];

  for (const stripeTxn of stripeTxns.filter(t => t.type === 'charge')) {
    const order = internalOrders.find(o => o.id === stripeTxn.order_id || o.stripeChargeId === stripeTxn.stripe_id);

    if (order && Math.abs(order.total - stripeTxn.gross) < 0.01) {
      matched.push({ stripeTxn, order, delta: 0 });
    } else {
      exceptions.push({ stripeTxn, order: order ?? null, delta: order ? order.total - stripeTxn.gross : stripeTxn.gross });
    }
  }

  // Alert on exceptions
  if (exceptions.length > 0) {
    await sendSlackAlert(`Reconciliation: ${exceptions.length} unmatched transactions on ${date}`);
  }

  return { matched: matched.length, exceptions: exceptions.length };
}

PayPal 对账: 使用 PayPal Reporting API(/v1/reporting/transactions)获取已结算的交易。将结果筛选为 transaction_status: 'S'(仅已结算),以避免匹配处理中授权。

步骤 3:处理最常见的对账边缘情况

Stripe 付款总额不等于收费总额: 这是预期情况——付款金额已扣除手续费、退款和滚动准备金。在 A2X 和 Synder 中,付款金额会与银行存款进行对账;单笔收费则按总额单独记录,手续费作为支出。

在不同月份发放的退款: A2X 和 Synder 会自动处理——退款记入发放退款的期间,而非原始销售的期间。将会计系统设置为使用权责发生制会计,以便退款冲减相应期间的收入。

拒付: Stripe 和 Shopify Payments 都会自动为拒付金额及拒付手续费创建余额交易。A2X 和 Synder 会将这些记录为负数交易。请确认科目表中有一个用于记录手续费的“拒付”支出科目。

多币种交易: 如果以 EUR 处理交易,而账簿使用 USD,请将 A2X 或 Synder 配置为按交易发生时的汇率记录(而非付款时的汇率)。这符合权责发生制会计原则。

步骤 4:设置每日对账监控

在 QuickBooks 或 Xero 中配置每日报告,显示:

  1. 银行存款与会计系统中收到的款项:两者应相差不超过 $0.01
  2. 未匹配交易:会计系统中未与银行记录匹配的任何交易
  3. 异常率:力争每天未匹配交易低于 1%

在 QuickBooks 中:使用 Reports → Banking → Reconciliation Reports 在 Xero 中:使用 Accounting → Bank Accounts → Reconciliation Reports

最佳实践

  • 先使用 A2X 或 Synder,再考虑自定义开发 — 对于 Shopify、WooCommerce 和 BigCommerce 商店,这些工具只需一天即可解决对账问题;自定义代码则会增加数月的维护工作
  • 以 Stripe 余额交易作为事实来源 — 而不是费用或付款意图;余额交易是唯一能在一条一致记录中包含费用、退款和打款的数据流
  • 对账 T-1(昨天)的数据,而不是当天的数据 — 大多数支付处理商会在交易发生 24 小时后完成结算;对账当天数据会将尚在处理中的授权误报为异常
  • 绝不要自动解决异常 — 所有异常的解决都必须经过人工审批并留下审计记录;将 A2X 和 Synder 配置为标记异常,而不是自动过账
  • 单独核对费用 — 支付处理商的费用通常会从一笔打款中统一扣除;每季度根据商户协议核实费率

常见问题

问题解决方案
Shopify 打款金额与银行入账金额不符A2X 会自动将打款净额映射到银行入账;请确认 A2X 已连接且已启用打款处理
Stripe 退款产生重复的会计分录Synder 和 A2X 会将退款作为冲销原始销售的借项处理;请停用你可能创建的任何手动退款分录
PayPal 交易无法对账PayPal 结算可能需要 2–5 个工作日;将 PayPal 数据导入筛选条件设为仅包含 transaction_status: S(已结算)
货币不匹配导致误报异常将同步工具配置为以交易的原始货币记录交易;使用会计系统内置的货币换算功能,并按交易日期的汇率进行换算
月末差额随时间不断增加每月在会计系统中汇总一次,找出所有超过 30 天仍未匹配的项目,并在结账前解决

相关技能

  • @stripe-integration
  • @paypal-integration
  • @tax-compliance-automation
  • @accounts-receivable-automation
  • @payout-split-management

评论

支持 Markdown