支付链接( F) QR 代码

支付链接允许您创建可重复使用或一次性支付页面而无需写入任何退出 UI. QR 代码来自支付链接,可以打印、嵌入到电子邮件中,或者显示在 POS 屏幕。

用于经常性 Heth 明确钱包同意的账户支付,使用 HethWallet 订阅于 Heth.me 文档. 一个正常的付款链接不给予经常性借记许可。

创建支付链接

POST /api/v1/links

curl -X POST https://4pay.online/api/v1/links \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": {
      "default": 1000,
      "currency": "RUB"
    },
    "amount_type": "fixed",
    "pay_config": {
      "methods": ["card"]
    }
  }'

参数

外地	类型	要求数	说明
`amount`	object	✓	数量对象
`amount.default`	integer	✓	以最小货币单位计算的数额(例如: RUB)
`amount.currency`	string	✓	ISO 4217 货币编码(例如). `"RUB"`, `"USD"`)
`amount_type`	string	✓	`"fixed"` - 付款人看到固定数额; `"dynamic"` ——付款人输入金额
`pay_config`	object	✓	付款配置
`pay_config.methods`	array	—	启用支付方法,例如: `["card", "sbp"]`
`products`	array	—	产品 UUID 组合以附加链接。产品必须属于同一个伙伴。在更新时, 将当前列表全部替换
`image`	string	—	图像 URL 以下列方式获取: `POST /api/v1/images`

回应

{
  "data": {
    "id": "abc12345-0000-0000-0000-000000000000",
    "created": "2026-03-01T10:00:00+00:00",
    "partner_id": 42,
    "amount": {
      "default": 1000,
      "currency": "RUB"
    },
    "amount_type": "fixed",
    "pay_config": {
      "methods": ["card"]
    },
    "image": null,
    "products": []
  }
}

将产品附加到支付链接中

产品和支付链接 数对数 关系。一个链接可以包含多个产品,一个产品可以连接多个链接。

分步前进

创建产品 通过 POST /api/v1/products 并拯救他们, id 数值
创建链接 与 products 包含一系列产品UUID的字段:

curl -X POST https://4pay.online/api/v1/links \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": { "default": 198000, "currency": "RUB" },
    "amount_type": "fixed",
    "pay_config": { "methods": ["card"] },
    "products": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9500-f39c-52e5-b827-557766551111"
    ]
  }'

回复返回 products 作为完整产品对象的数组(与 price, header, image等) (中文(简体).

更新产品绑定

为了改变附着的产品,通过一个新的 UUID 阵列中 PATCH /api/v1/links/:id:

curl -X PATCH https://4pay.online/api/v1/links/abc12345-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{ "products": ["550e8400-e29b-41d4-a716-446655440000"] }'

那个... products 数组完全取代当前绑定。要拆卸所有产品,请发送 "products": [].

假设	结果
UUID 未找到	产品被默默忽略
空阵列 `[]`	与无产品的联系
`products` 字段省略	装订不变(在更新时)

获取支付链接

GET /api/v1/links/:id

curl https://4pay.online/api/v1/links/abc12345-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

列表支付链接

GET /api/v1/links

curl https://4pay.online/api/v1/links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

更新付款链接

PATCH /api/v1/links/:id

curl -X PATCH https://4pay.online/api/v1/links/abc12345-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": {
      "default": 2000,
      "currency": "RUB"
    }
  }'

删除付款链接

DELETE /api/v1/links/:id

curl -X DELETE https://4pay.online/api/v1/links/abc12345-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

链接付款的 Webhook

链接付款产生与任何其他付款相同的网签——没有单独的链接事件类型 :

{
  "event_id": "4d9d0e6c-1d0a-4a2e-9a2f-0c9a1b0e8f21",
  "timestamp": 1772668800,
  "type": "transaction.charged",
  "data": {
    "type": "payment",
    "txid": "generated-txid",
    "id": "550e8400-...",
    "status": "charged",
    "amount": "1000",
    "amount_dest": "950",
    "amount_with_fee": "1050",
    "error_description": ""
  }
}

要了解支付到的链接, 请将交易读回 GET /api/v1/transactions/{id} - 它载着 link_id.

QR 代码产品

用于零售或 POS ,您可以创建产品与 QR 触发固定价格支付流量的代码 :

POST /api/v1/products

curl -X POST https://4pay.online/api/v1/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "header": "Coffee",
    "text": "Espresso 200ml",
    "price": 350,
    "currency": "RUB",
    "qty": "1"
  }'

产品参数

外地	类型	要求数	说明
`header`	string	✓	支付页面上显示的产品名称
`text`	string	✓	产品简介
`price`	integer	—	以最小货币单位计的价格
`currency`	string	—	ISO 4217 货币代码( 默认 ) : `"RUB"`)
`qty`	string	—	数量( 默认 : `"1"`)
`image`	string	—	图像 URL 以下列方式获取: `POST /api/v1/images`

每个产品都会产生一个专用的 QR 代码,可以打印和无限期使用。

上传图像

产品和支付链接的图像单独上传,然后引用 URL.

POST /api/v1/images
Content-Type: multipart/form-data

curl -X POST https://4pay.online/api/v1/images \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -F "image=@photo.jpg"

回应

{
  "data": {
    "url": "https://s3.example.com/images/uploads/42/1709472000000photo.jpg"
  }
}

使用返回的键 url 输入 image 字段创建或更新产品和链接时。

QR Products 是现有 API 的兼容性例外：按当前模式，price 使用表示最小货币单位的精确 JSON 整数。不得发送以主货币单位表示的小数，也不得使用浮点运算。

支付链接( F) QR 代码

创建支付链接​

参数​

回应​

将产品附加到支付链接中​

分步前进​

更新产品绑定​

获取支付链接​

列表支付链接​

更新付款链接​

删除付款链接​

链接付款的 Webhook​

QR 代码产品​

产品参数​

上传图像​

回应​