付款流程

本指南涵盖由下列机构支持的所有支付流动: 4pay.online: 直接支付卡片,托管支付,支付,退款,以及级联路由.

交易周期

每笔交易都遵循此状态机器:

created → new → authorizing → charging → charged ✅
                    │                  → failed ❌
                    └► action_required  → rejected ❌

charged → reversed (a settled transaction was returned)

状态	最终	说明
`created`	no	交易已初始化
`new`	no	正在接受、路线和审定
`authorizing`	no	获得提供者授权
`action_required`	no	等待付款人(3-D 安全,请检查d 安全 OTP,签名)
`charging`	no	由提供者处理
`charged`	对	已确认付款,已收到资金
`failed`	对	提供者错误,或在和解前取消
`rejected`	对	验证、路由或合规检查失败
`reversed`	对	退回了一笔已结清的交易
`refunded`	no	退款完成——终局取决于铁路

仅就最终地位采取行动,并将你不承认的任何地位视为非最终结果:名单未关闭,铁路载有自己的中间状态 (cancelled, payment_suspended 完整的模型,包括: 每一个最终结果对钱意味着什么,是在协议规格.

直接卡付款

为: PCI DSS 直接处理卡片数据的认证合伙人.

Partner API                     4pay.online                    Provider
    │                               │                             │
    ├─── POST /transactions ───────►│                             │
    │    (card data included)       │── route + validate ────────►│
    │                               │                             │
    │                               │◄── 3DS required ───────────┤
    │◄── status: action_required ───┤                             │
    │                               │                             │
    ├─── POST /additional_params ──►│── 3DS verification ────────►│
    │    (OTP or 3DS data)          │                             │
    │                               │◄── charged ────────────────┤
    │◄── webhook: charged ──────────┤                             │

创建支付

付款需要所有五个牌区—— cardnumber, cardholder, exp_month, exp_year, cvv ——和两个重定向 URL。只需支付 cardnumber,没有方向URL。

通过您自己的服务器传递卡片数据会让您进入 PCI DSS 瞄准镜,除非你持有证明,使用以下主机流.

curl -X POST https://4pay.online/api/v1/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "txid": "order_123",
      "type": "payment",
      "amount": "10000",
      "currency": "USD",
      "env": "prod",
      "money_storage": {
        "type": "bank_card",
        "cardnumber": "PROVIDER_TEST_PAN",
        "cardholder": "IVAN PETROV",
        "exp_month": "12",
        "exp_year": "2027",
        "cvv": "PROVIDER_TEST_CVV"
      },
      "description": "Order #123",
      "returnUrl": "https://your-site.com/result",
      "failUrl": "https://your-site.com/failed"
    }
  }'

处理 3DS 认证

当状态变成 action_required,动作本身在 auth_params ——委员会 type 告诉你该怎么做redirect or auth_3ds_form),以及 url, method 和 params 告诉你送哪里去顾客,没有 action_required 布尔和否 auth_url 字段键入。

经核实后,提交认证数据:

curl -X POST https://4pay.online/api/v1/transactions/additional_params_for_auth/TX_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{"params": {"otp": "123456"}}'

托管付款

没有伙伴的 PCI DSS 客户在 a 上输入卡片细节 4pay.online- 主持网页。

Partner API                     4pay.online                    Customer
    │                               │                             │
    ├─── POST /transactions ───────►│                             │
    │    (NO card data)             │                             │
    │◄── widget_url ────────────────┤                             │
    │                               │                             │
    │    redirect customer ─────────┼─────────────────────────────►
    │                               │◄── card data ──────────────┤
    │                               │── process payment ──►       │
    │◄── webhook: charged ──────────┤                             │

创建主机支付

curl -X POST https://4pay.online/api/v1/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "txid": "order_456",
      "type": "payment",
      "amount": "5000",
      "currency": "EUR",
      "env": "prod",
      "hosted": true,
      "description": "Order #456",
      "returnUrl": "https://your-site.com/result",
      "failUrl": "https://your-site.com/failed"
    }
  }'

答复包括 widget_url - 将客户改到那里,付款后,客户返回 returnUrl 你将获得一个网签。

付款

从您的账户中将资金寄给一个接受者(卡,银行账户,钱包).

curl -X POST https://4pay.online/api/v1/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "txid": "payout_789",
      "type": "payout",
      "amount": "25000",
      "currency": "USD",
      "env": "prod",
      "money_storage": {
        "type": "bank_card",
        "cardnumber": "PROVIDER_TEST_PAN"
      },
      "description": "Withdrawal request #789"
    }
  }'

付款周期相同: created → new → charging → charged/failed.

退款

a/ 发放全额或部分退款 charged 交易。

全额退款

curl -X PUT https://4pay.online/api/v1/transactions/TX_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{"params": {"type": "refund"}}'

部分退款

curl -X PUT https://4pay.online/api/v1/transactions/TX_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{"params": {"type": "refund", "amount": "5000"}}'

交易结果为: refund_id 和 refund_msg退款。不重写原始状态:完全返回的和解成为 reversed.

双阶段付款(授权+捕获)

一些提供商支持授权(持有),然后是捕获(充电). 平台先持有资金,然后在确认时捕获.

authorize → charging (funds held) → commit → charged

手动进行授权交易:

curl -X POST https://4pay.online/api/v1/transactions/commit/TX_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -H "Content-Type: application/json" \
  -d '{"params": {"money_storage_meta": {}}}'

在你犯罪之前,资金是持有的,没有解决的。终止控股, 交易失败—— 控股永远不会被解除被俘的比预留的还要多

连锁跑道

当一个提供者失败时,该平台会自动与下一个可用的提供者重试:

Provider A (priority 0) → failed → rollback hold
                                    ↓
Provider B (priority 1) → failed → rollback hold
                                    ↓
Provider C (priority 2) → charged ✅

连锁店对合伙人透明。您总是通过 Webhook 获得最终结果。配置管理控制台下的路由优先级 终端运行( R).

数额

每个交易回复包括三个金额字段:

外地	说明	示例
`amount`	原先要求的数额	`"10000"`
`amount_with_fee`	数额,包括所有费用	`"10500"`
`amount_dest`	按目的地分列的收到的金额	`"9500"`

为: 支付额: 客户付费 amount,商家收到 amount_dest. 为: 付款: 商家发送 amount,接收者收到 amount_dest.

所有金额均为十进制 字符串 最小货币单位(百分数、高压单位)。 "10000" = 100.00 USD。它们是字符串,因为有十八小数的资产不符合 JSON 号码安全。

Webhook 通知

您在每次状态变化时都会收到网路选择。 Webhook 通知关于设置细节。

示例webhook有效载荷:

{
  "event_id": "4d9d0e6c-1d0a-4a2e-9a2f-0c9a1b0e8f21",
  "timestamp": 1772668800,
  "type": "transaction.charged",
  "data": {
    "type": "payment",
    "txid": "order_123",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "charged",
    "amount": "10000",
    "amount_dest": "9500",
    "amount_with_fee": "10500"
  }
}

幂等性

复制在 event_id,交易时不使用 id 一项交易在其生命中产生多个事件,平台可能发送同样的事件不止一次不止一次吗?

恢复和复原能力

交易状态在每一个处理阶段都持续存在
如果一个节点在中流中坠落,则从最后一个检查站自动恢复恢复
无需人工干预——平台保证至少一交货

下一个步骤

代码示例 - Python, 节点.js, PHP 执行情况
Webhook 通知 - Webhook 设置和签名验证
引用错误 - 错误代码和排除故障
沙盒测试( T) - 测试卡和沙盒环境

付款流程

交易周期​

直接卡付款​

创建支付​

处理 3DS 认证​

托管付款​

创建主机支付​

付款​

退款​

全额退款​

部分退款​

双阶段付款(授权+捕获)​

连锁跑道​

数额​

Webhook 通知​

恢复和复原能力​

下一个步骤​