Mollie 中文文档 下载 App

Mollie 开发者 API 集成 - REST API SDK Orders Payments 详解

两种 API：Payments vs Orders

Mollie 提供两个层级的支付 API，按复杂度从低到高：

API适合场景特点
Payments API简单的"收一笔钱"场景轻量，只关心金额+币种+回调地址
Orders API有完整订单管理系统的电商支持订单项、部分退款、订单状态同步、更好的对账

Payments API（快速上手）

Payments API 是"创建一笔支付请求"的最简路径。你只需要告诉 Mollie：多少钱、什么币种、付款完成后去哪里。

核心流程

POST /v2/payments → 返回 payment 对象 + checkout_url
客户重定向到 checkout_url
客户完成付款
Mollie 发送 payment.paid Webhook
你收到回调，更新订单状态

请求示例（Python SDK）

import mollie_api_client
from mollie_api_client.api_client import ApiClient
from mollie_api_client.api.payments_api import PaymentsApi

client = mollie_api_client.configure("Bearer test_xxxx")

payments_api = PaymentsApi()
payment = payments_api.create_payment({
    "amount": {"currency": "EUR", "value": "19.99"},
    "description": "Premium Plan Monthly",
    "redirectUrl": "https://saas.com/account/upgrade/success",
    "webhookUrl": "https://saas.com/api/mollie/webhook"
})

# payment['_links']['checkout']['href'] 是重定向 URL
checkout_url = payment['_links']['checkout']['href']

Payment 状态机

open（已创建，客户还没付款）
  ├── paid（已成功付款）→ Mollie 发 payment.paid Webhook
  ├── authorized（已授权但未结算，适用于某些卡类）
  ├── canceled（客户取消了）
  ├── expired（超时未付款）
  └── failed（支付失败）

Orders API（完整电商）

Orders API 把支付和订单管理绑定在一起。每个 Order 可以包含多个 Order Line（订单项），每个订单项可以有自己的数量、单价、税率。

什么时候该用 Orders

创建 Order 示例

order = orders_api.create_order({
    "amount": {"currency": "EUR", "value": "129.99"},
    "billingAddress": {
        "givenName": "John",
        "familyName": "Doe",
        "email": "john@example.com",
        "streetAndNumber": "Main Street 123",
        "postalCode": "1234AB",
        "city": "Amsterdam",
        "country": "NL"
    },
    "lines": [
        {
            "name": "Wireless Earbuds Pro",
            "quantity": 1,
            "unitPrice": {"currency": "EUR", "value": "99.99"},
            "vatRate": "21.00"
        },
        {
            "name": "Shipping",
            "quantity": 1,
            "unitPrice": {"currency": "EUR", "value": "30.00"},
            "vatRate": "21.00"
        }
    ],
    "redirectUrl": "https://shop.com/order/success",
    "webhookUrl": "https://shop.com/api/mollie/order-webhook"
})

Order 状态机

Order 的状态比 Payment 更丰富，因为它要追踪从下单到发货的完整周期：

created → paid → authorized
                ├── shipping → completed → refunded
                └── canceled

关于退款

Payments API 的退款

refund = payments_api.create_payment_refund(payment_id, {
    "amount": {"currency": "EUR", "value": "19.99"},
    "description": "Customer request"
})

Payments API 只支持整笔或全额退款（某些场景下可以部分退，但比较受限）。

Orders API 的退款（推荐）

refund = orders_api.create_order_refund(order_id, {
    "lines": [
        {"id": "odl_xxx", "quantity": 1},  # 只退某一件商品
    ],
    "description": "Return defective item"
})

Orders API 可以精确到订单项级别退款，这也是它更强大的地方之一。

幂等性

Mollie API 的所有写操作都是幂等的——用同一个 Idempotency-Key 头重复调用，只会执行一次实际操作：

curl -X POST https://api.mollie.com/v2/payments \
  -H "Authorization: Bearer test_xxxx" \
  -H "Idempotency-Key: unique-uuid-for-this-request" \
  -H "Content-Type: application/json" \
  -d '{...}'

这对于处理网络超时重试非常重要——如果客户端因为超时重试了请求，不会意外创建多笔 Payment。

版本与向后兼容

Mollie API 采用 URL 版本（/v2/payments）。新版本推出时旧版本会保留至少两年，给你充足的升级时间。当前最新版本是 v2。

开发者工具

继续阅读：订阅与重复扣费功能 →