快速启动 — 您的首笔付款 。 15 分钟
本指南从无到有支付。 不需要事先了解平台 。
先决条件
您的操作员将两个值一起发布, 您需要两个值:
- an API 密钥 (伙伴区) + 设置 − API 密钥);
- 编号 组织编号 关键在其中
加号 curl,或任何 HTTP 客户端。请快点: SDK 执行相同的四个
呼叫十几条线。
组合对照 https://sandbox.4pay.online 并切换主机 当你去现场。沙盒
与模拟提供者是同一个平台——见 沙盒测试( T).
步骤 1 检查您的连接
curl https://sandbox.4pay.online/api/v1/health
{
"core_status": "ok",
"db_status": "ok",
"appversion": "f0175d14",
"env": "sandbox",
"domain": "sandbox.4pay.online"
}
准备状态是 core_status。没有字段叫做 status.
步骤 2 - 创建付款
curl -X POST https://sandbox.4pay.online/api/v1/transactions \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-organization-id: YOUR_ORGANIZATION_ID" \
-d '{
"params": {
"type": "payment",
"amount": "1000",
"currency": "USD",
"txid": "order-12345",
"env": "test",
"hosted": true,
"returnUrl": "https://yoursite.com/success",
"failUrl": "https://yoursite.com/fail"
}
}'
hosted 没有默认, 设置它离开 hosted 将请求读为 服务器对服务器: 平台寻找卡片
细节,没有找到,答案 201 Created 与 "status": "rejected" 和
"error_description": "unexpected card"。这是第一个最常见的原因。
集成交易不会向任何人收取费用。
amount 是一个字符串，以货币的最小单位表示金额，例如美分、便士、
戈比。"1000" = $10.00 USD。使用字符串是因为具有
十八位小数精度的资产无法安全地用 JSON number 表示：请发送 "1000"，而不是 1000。
答复:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "created",
"type": "payment",
"env": "test",
"txid": "order-12345",
"amount": "1000",
"currency": "USD",
"started": "2026-09-03 11:18:30.101839 Etc/UTC",
"widget_url": "https://pay.sandbox.4pay.online?id=550e8400-...&org_id=...&token=eyJhbGciOi..."
}
将付款人重新定向到 widget_url ——主机支付页面,他们在其中输入他们的卡片。
服务器从不触摸卡片数据,这是让你远离 PCI DSS 范围。
widget_url 过期时间约为 15 几分钟。 其 类 token 是一个短暂的寿命 JWT重定向
立即; 从不存储 URL 如果支付者明天回来,请创建
一个新的交易。
201 Created 并不意味着被接受。 追索、限制和反欺诈均拒绝支付
创建为 rejected读取 status 每一份答复中,不仅仅是 HTTP 代码。
时间戳不是 ISO 8601. started 和 finished 以
2026-09-03 11:18:30.101839 Etc/UTC ——一个空间代替 T区域。大多数日期解析器
返回无效的日期;有些默读为本地时间。 SDK
处理它。
步骤 3 ——检查交易状况.
curl https://sandbox.4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: YOUR_API_KEY" \
-H "x-organization-id: YOUR_ORGANIZATION_ID"
双头,每次都是,键被解决了 * 内 * 组织中的第二个头名, 并且只携带钥匙的请求被拒绝。
交易状态 :
| 状态 | 最终 | 含义 |
|---|---|---|
created, new | no | 已创建, 尚未路由 |
authorizing | no | 获得授权 |
action_required | no | 付款人必须做点什么 |
charging | no | 由提供者处理 |
charged | ** 对** | 解决了... |
rejected | ** 对** | 在提供者之前或被提供者拒绝——释放的资金 |
failed | ** 对** | 处理错误,或在结算前注销——释放资金 |
reversed | ** 对** | 一笔已结清的付款已退还 |
refunded | no | 退款完成 |
仅就最终地位采取行动,并将你不承认的任何地位视为 非最终的——列表没有关闭,铁路承载着自己的中间状态. 完全状态模式在 协议规格.
步骤 4 - 看着它解决
在沙盒中,你可以直接充值一张卡片,并观察整个生命周期,没有浏览器:
curl -X POST https://sandbox.4pay.online/api/v1/transactions \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-organization-id: YOUR_ORGANIZATION_ID" \
-d '{
"params": {
"type": "payment",
"amount": "1000",
"currency": "USD",
"txid": "order-12346",
"env": "test",
"show_widget": false,
"money_storage": {
"cardnumber": "2201382000000013",
"cvv": "PROVIDER_TEST_CVV",
"cardholder": "IVAN IVANOV",
"exp_year": "20",
"exp_month": "12"
},
"returnUrl": "https://yoursite.com/success",
"failUrl": "https://yoursite.com/fail"
}
}'
回来啦 charging,并达到 charged 约一分钟内就自行行动。 3, or
取下网钩.
数目, CVV,持单人和过期人被比作一个Tuple. IVAN IVANOV 在首都, exp_year
of "20" - 任何区别都给 rejected / unexpected card。完整的卡片是
in 沙盒测试( T).
A 服务器对服务器 两者均需 returnUrl 和 failUrl 没有他们
平台创建交易并立即以“ return_url/fail_url params not”拒绝交易
`. 托管付款和付款并不需要。
步骤 5 ——接收webhook通知
而不是投票, 你的接线员设置一个 notify_url ** 在您的终端**
在行政控制台中,加一个网钩密钥。它适用于每个
该终端上的交易——没有按要求通知字段,以及
a notifyUrl 在创建体中被忽略。
当状态发生变化时,签名 POST 到了那个位置 URL:
{
"event_id": "4d9d0e6c-1d0a-4a2e-9a2f-0c9a1b0e8f21",
"timestamp": 1772668800,
"type": "transaction.charged",
"data": {
"txid": "order-12345",
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "charged",
"amount": "1000",
"amount_dest": "950"
}
}
在信任之前验证签名, 并复制到 event_id - 详细情况
Webhook 通知.
下一个去哪里?
| 我想... 我想... 我想... 我想... 说说... I want to... | 链接 |
|---|---|
| 全部用十几行代码进行 | SDK |
| 让一个 AI 代理接受付款 | 代理付款 |
| 了解交易的每个字段 | 交易 |
| 正确处理失败 | 引用错误 |
| 阅读正式合同 | 通用交易协议 |