Mollie API 快速入门 - REST v2 端点请求示例

API 基本信息

项目	值
基础 URL	`https://api.mollie.com/v2`
协议	HTTPS only
认证	Bearer Token（API Key）
数据格式	JSON
版本	v2（当前最新）
测试环境	同一套端点 + test_ 开头的 Key

两种 API Key

Mollie 有三种 Key（实际是两种 + 授权码）：

类型	前缀	用途	可见性
API Key	`test_` 或 `live_`	服务端直接调用 API	创建时完整显示，之后只显示掩码
OAuth Access Token	`access_`	第三方代商户操作（Connect 模式）	同上
Authorization Code	单次使用	OAuth 交换流程的中间产物	同上

第一步：获取 API Key

Dashboard → Developers → API Keys → [Create API Key]
  │
  ├── 给 Key 起个名字（如 "Production Payments"）
  │
  └── 创建后立即复制保存（完整 Key 只显示一次！）
        ├── live_xxxxxxxxxxxxxxxxx（正式）
        └── test_xxxxxxxxxxxxxxxx（测试）

如果你忘了保存：

不要慌，可以重新生成 Key
旧 Key 可以在 Dashboard 里手动撤销
记得更新你的应用里的 Key 配置

第二步：发送第一个 API 请求

用 curl

curl -X GET https://api.mollie.com/v2/me \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

这个端点（/v2/me）返回你当前账号的基本信息——作为"连通性测试"特别好用。

用 Python SDK

import requests

headers = {
    "Authorization": "Bearer test_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

response = requests.get("https://api.mollie.com/v2/me", headers=headers)
print(response.json())

返回示例

{
  "resource": "me",
  "id": "org_12345678",
  "name": "Acme Commerce",
  "email": "support@acme.com",
  "country": "NL",
  "address": {
    "streetAndNumber": "Hoofdstraat 123",
    "postalCode": "1234AB",
    "city": "Amsterdam",
    "country": "NL"
  },
  "registrationNumber": "12345678",
  "vatNumber": "NL123456789B01"
}

第三步：创建第一个 Payment

curl -X POST https://api.mollie.com/v2/payments \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "currency": "EUR",
      "value": "19.99"
    },
    "description": "Test Payment #001",
    "redirectUrl": "https://example.com/return",
    "webhookUrl": "https://example.com/webhook"
  }'

参数说明

参数	必需	说明
amount.currency	✅	三个字母货币代码（EUR、GBP、USD 等）
amount.value	✅	金额字符串，两位小数（注意引号！不是数字类型）
description	✅	支付描述，会出现在银行对账单上
redirectUrl	✅	客户付款完成后跳转的 URL
webhookUrl	⭕ 推荐	Mollie 向你推送支付状态的 URL

返回（截取）

{
  "id": "tr_xxxxxxxxxx",
  "status": "open",
  "_links": {
    "checkout": {
      "href": "https://www.mollie.com/checkout/select-method/tr_xxxxxxxxxx"
    },
    "redirect": {
      "href": "https://example.com/return"
    }
  }
}

把客户重定向到 _links.checkout.href 就能开始付款了。

第四步：处理 Webhook（最关键）

客户付款成功后，Mollie 会向你设置的 webhookUrl 发送一个 HTTP POST：

POST https://example.com/webhook
Content-Type: application/x-www-form-urlencoded

id=tr_xxxxxxxxxx

你的 Webhook 处理器需要：

收到 POST 后立即返回 HTTP 200（哪怕还没处理完）
从 id 参数里提取 Payment ID
用 Payment ID 调用 GET /v2/payments/{id} 获取最新状态
根据状态更新你的订单系统

为什么 Webhook 是"真实信号"

重定向 URL 只是通知客户，不能作为支付确认——客户可能付款成功后关闭浏览器，重定向根本不会发生。Webhook 是 Mollie 的服务器主动发给你的，才是可靠的支付状态来源。

Webhook 签名验证

Mollie 发的每个 Webhook 都带一个 Mollie-Signature 头，可以用来验证请求确实来自 Mollie 而不是伪造的。签名算法是 HMAC-SHA256，密钥是你的 API Key。

测试环境

测试 Key 以 test_ 开头
测试环境下的"付款"是模拟的——不会真的扣款
在 Mollie Checkout 测试模式下，选择任何支付方式都会自动触发成功
你可以在 Dashboard → Developers → Webhooks 手动触发事件来测试

常用端点速查

用途	方法	端点
创建支付	POST	/v2/payments
查询支付	GET	/v2/payments/{id}
取消支付	DELETE	/v2/payments/{id}
创建 Customer	POST	/v2/customers
创建订阅	POST	/v2/customers/{id}/subscriptions
创建订单	POST	/v2/orders
查询订单	GET	/v2/orders/{id}
退款（Payment 级）	POST	/v2/payments/{id}/refunds
退款（Order 级）	POST	/v2/orders/{id}/refunds
获取可用支付方式	GET	/v2/methods
查询你自己的信息	GET	/v2/me

下一步

看完 API 入门，建议接着读：

Webhooks 配置与处理——正确处理 Mollie 的事件推送
SDK 与预置插件——不想手写 API 可以用官方 SDK
核心概念：Organization / Profile / Balance——理解数据模型基础

继续阅读：Webhooks 事件回调 →