Mollie 开发者核心概念 - Organization Profile Balance 等实体关系

为什么重要

Mollie API 的数据模型是围绕一组稳定的实体（Entity）构建的。理解这些实体的关系，能帮你：

更准确地理解 Connect 平台模式的资金流
在 Payment、Order、Subscription 等 API 调用里选对参数
设计你自己的数据模型（尤其是 SaaS 和平台建设者）

五个核心实体

1. Organization（组织）

Organization 是最高层级的容器——一个 Mollie 账号就是一个 Organization。它包含：

公司或个人经营者的注册信息
一个或多个 Profile（店铺）
一个主 Balance + 可选的多币种 Balance
可用的 Capabilities（能做什么操作）

# Organization 唯一标识：org_xxxxxxxxxxxxxxxx
# 你自己的 Organization 可以 GET /v2/me 查看

在 Connect 模式下：

你的平台是一个 Organization
每个通过 OAuth 连接的商户也是独立的 Organization（叫 Connected Account）

2. Profile（店铺配置）

一个 Organization 可以有多个 Profile——每个 Profile 代表一个独立的"店铺视图"：

店铺名称（展示给客户）
网站 URL
启用的支付方式列表
品牌 Logo 和颜色
可用的币种

# Profile 唯一标识：pfl_xxxxxxxxxxxx
# GET /v2/profiles 获取当前 Organization 的所有 Profile
# GET /v2/profiles/{id} 获取单个 Profile

场景举例：一个 Organization 运营两个业务——一个荷兰电商、一个德国电商。可以创建两个 Profile：

Profile A：名称 "NL Shop"，网站 nl.example.com，启用 iDEAL + Bancontact
Profile B：名称 "DE Shop"，网站 de.example.com，启用 SEPA + PayPal

创建 Payment 时可以指定 profileId，Payment 会显示该 Profile 的品牌和支付方式。

3. Customer（客户记录）

Customer 是 Mollie 用来存储可重复使用支付方式的容器——它的主要用途是 Subscription（订阅）。

# Customer 唯一标识：cst_xxxxxxxxxxxxx
# 创建 Customer
customer = client.customers.create({
    "name": "John Doe",
    "email": "john@example.com"
})

# 关联 Customer 到 Payment
payment = client.payments.create({
    "amount": {...},
    "customerId": customer.id,  # ← 关键：关联后 Mollie 才知道这个客户有哪些可用的 Mandate
    "sequenceType": "first",   # 标记为首次 Payment，支付成功后会创建 Mandate
    ...
})

4. Mandate（支付授权）

Mandate 是 Customer 对 SEPA Direct Debit 或信用卡的支付授权：

Customer（cst_xxx）
  ├── Mandate（mdt_xxx，SEPA 直接扣款授权，valid 状态）
  │     └── Subscription（sub_xxx，每月扣 €29.99）
  └── Mandate（mdt_yyy，信用卡授权，valid 状态）
        └── Subscription（sub_yyy，每年扣 €299.99）

Mandate 状态：

valid：可以用来发起后续的自动扣费
invalid：已失效（客户取消、银行拒绝等）
pending：等待验证

5. Balance（资金余额）

Balance 是 Organization 在 Mollie 持有的资金——按币种分多个 Balance：

Organization（org_xxx）
  ├── Balance EUR：€5,000.00（主余额）
  ├── Balance GBP：£1,200.00（多币种）
  └── Balance USD：$800.00（多币种）

Balance 里的钱有两个状态：

pending：刚收到的 Payment，还在 Mollie 的结算处理中
available：可以用来发起 payout（结算到你银行账户）

# 查询 Balance
balance = client.balances.get("EUR")
print(balance.pending_amount)   # 待结算
print(balance.available_amount) # 可结算

# 发起 payout（结算到你银行）
payout = client.payouts.create({
    "amount": {"currency": "EUR", "value": "5000.00"}
})

实体关系图

Organization（org_）
  │
  ├── Profile（pfl_）── 支付方式配置、品牌、网站
  │     └── Payment（tr_）── 每次收单
  │
  ├── Customer（cst_）── 可重复支付的客户容器
  │     └── Mandate（mdt_）── 支付授权
  │           └── Subscription（sub_）── 定期扣费
  │
  └── Balance（可选币种）── 资金池
        └── Payout（po_）── 结算到银行

资金流示例

单次收单

客户付 €100
  │
  ├── Payment 创建 → Mollie Checkout → 客户付款成功
  │
  ├── Mollie 扣除 €2.00（费率）
  │
  └── Balance EUR（available）增加 €98.00
        └── 发起 Payout → €98.00 到你的银行账户

订阅首次 + 自动扣费

1. 客户首次付 €29.99（创建 Subscription）
   │
   ├── Payment（sequenceType: first）成功
   ├── Mollie 自动创建 Mandate（有效）
   └── Subscription 创建完成

2. 一个月后，Mollie 自动发起 €29.99 扣费
   │
   ├── Payment（sequenceType: recurring）自动创建
   ├── 从 Mandate 授权的 SEPA 账户扣款
   ├── 成功 → Balance EUR 增加
   └── 失败 → Mollie 重试（最多 5 次）→ 全部失败后 Subscription 取消

Marketplace 模式

客户从 Seller A 买 €60 商品 + Seller B 买 €40 商品
  │
  ├── Payment 创建，€100 进入 Holding Balance（托管）
  │
  ├── 你创建 Routes：
  │     ├── Seller A：€60 → Seller A Organization Balance
  │     └── Seller B：€40 → Seller B Organization Balance
  │
  └── Routes 执行后，你的 Marketplace Organization 余额 = €0（如果不收佣金）

为什么这个模型重要

理解这些实体后，你就不会犯常见的新手错误：

不会忘记在创建 Subscription 前先创建 Customer（没 Customer 就没地方存 Mandate）
不会混淆 Organization 和 Profile（一个 Organization 可以有多个 Profile，各自独立配置）
不会在 Connect 模式下忘记 Authorization（每个 Connected Account 是独立 Organization，需要各自 OAuth 授权）

继续阅读：定价与费率总览 →