跳转到主内容

交易

该交易是该交易的核心对象 4pay.online API。每一笔付款、付款和退款都是一笔交易。

基础 URL: https://4pay.online/api/v1/transactions

创建交易​

POST /api/v1/transactions

请求机构​

{
  "params": {
    "type": "payment",
    "amount": "1000",
    "currency": "USD",
    "txid": "order-12345",
    "env": "test",
    "hosted": true,
    "returnUrl": "https://yoursite.com/success",
    "failUrl": "https://yoursite.com/fail"
  }
}

参数​

外地类型要求数说明
typestring✅交易类型 : payment, payout
amountstring✅以最小货币单位计的金额,作为小数字符串("1000" = 10.00 USD)
currencystring✅ISO 4217 货币编码( $USD, EUR, USDT, …)
txidstring—你点的菜 ID。自由形式; 独一无二 ** 每个伙伴**. 实现一能——见下文
returnUrlstring—支付者在支付后登陆的地方. 服务器对服务器付款的要求; 主机支付和支付可选
failUrlstring—付款人失败后降落的地方 规则与 returnUrl
envstring✅prod or test。必须在里面 params - 见下文。
hostedboolean—true 发送付款人到主机页面。 ** 无默认** - 见下文。 show_widget 是一个更古老的化名,用于同一事物
descriptionstring—向付款人出示的付款说明
customerobject—支付者信息 : { email, phone, name }
langstring—UI 语言 : en, ru, ar, es, …
merchant_metaobject—您的不透明数据, 在读取时返回, 在Webhook 通知中没有改变 。

回应​

{
  "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.4pay.online?id=550e8400-...&org_id=...&token=eyJhbGciOi..."
}

将您的用户重定向到 widget_url 以完成付款。 token in it is a JWT 无效的 约 15 分钟 —— 迅速重定向, 并创建新的交易, 而不是存储 URL.

危险
hosted 没有默认

一个创建没有 hosted: true (or show_widget: true) 被视为: 服务器对服务器编号: 平台需要卡片细节 money_storage,没有他们答案 201 Created 与 "status": "rejected" 和 "error_description": "unexpected card"。没有。 HTTP 状态 告诉你这笔钱被拒绝了

服务器对服务器的付款额外要求 两者 returnUrl 和 failUrl 没有他们 它被创造,并立即被否认, return_url/fail_url params not specified.

时间戳不是 ISO 8601

started 和 finished 回来吧 2026-09-03 11:18:30.101839 Etc/UTC - 一个空间,在那里 T 属于,六个分数,一个命名区域。 new Date(...) 在 JavaScript 中返回无效 日期; datetime.fromisoformat 在蟒蛇的堆积中; PHP 在服务器上读取一个“无区”值 时区。 SDK 在三部曲中正确诠释了它。

幂等性​

txid 是您选择的任意字符串, 它是独一无二的 ** 每个伙伴**重复 a 以 a 创建请求 txid 已经存在,不会创建第二个 交易 —— 将现有的一个拿回来, 再次使用 201 备注a location 一个组织内部的两个伙伴可能会重用同样的 txid 不发生碰撞。

创建交易 不含 txid 完全没有能力: 重试 在超时后产生第二次交易,从而产生第二次付款。 发送一个 txid 任何涉及金钱的东西

制约因素​

外地约束
txidUp to 255 字符。拒绝使用更长的值 422,而不是数据库错误
txid对案件敏感,并按发送的原样储存—— ORDER-abc 和 order-abc 是两种不同的交易
amount一定大于零 绝对是零 "0" 并拒绝负值 422
amount任意精度小数字符串 — a 18-数字值( O)1 ETH 在 Wei 中被接受为是 。
注意点
除此之外,无所不包 txid

重复相同的创建 txid 但是,一个 不同 amount 仍然返回原始内容 交易, 不变, 按原金额计算。 新金额没有应用, 没有错误 。

  • 阅读答复,而不是假设最新答复 amount 已经生效。

环境​

发送 env 内部 params. A ?env= 查询参数选择 环境 列表或查询搜索; 它不设置环境 。 正在创建交易。创建请求只包含 ?env=test 生成一个 生产 交易。当付款时 换句话说,需要从中流的付款人那里得到一些东西, 动作到达了 auth_params - 看见了 通用交易协议.

得到一笔交易​

GET /api/v1/transactions/:id
curl https://4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

回应​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "charged",
  "txid": "order-12345",
  "amount": "1000",
  "amount_with_fee": "1050",
  "amount_dest": "950",
  "currency": "USD",
  "currency_dest": "USD",
  "started": "2026-03-01T10:00:00Z",
  "finished": "2026-03-01T10:05:00Z"
}

数额字段​

外地说明
amount原始交易金额( 付款人支付)
amount_with_fee数额,包括平台费
amount_dest贷记你账下的数额(扣除费用后)

清单交易​

GET /api/v1/transactions
curl "https://4pay.online/api/v1/transactions?status=charged&limit=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

查询参数​

参数类型说明
statusstring按状态过滤
typestring按类型过滤 : payment, payout
envstringprod or test ——哪些环境需要搜索 .
limitinteger每页结果( 默认 ) : 20,最大值 : 100)
cursorstringcursor_value 从先前的答复中得出——见下文
started_from, started_toISO 8601创作时间
updated_from, updated_toISO 8601上次更新时的边界
finished_from, finished_toISO 8601完成时的界线
amount_from, amount_tostring以小单位计的数额
order_bystringstarted (违约)或 updated
rrnstring检索参考号
link_iduuid通过一个支付链接支付的款项

桌子上没有的东西都会被拒绝的 422 Unexpected field - 包括: page, offset, from, to 和 currency 这些看起来都合理,但都不存在

拨号​

答复内容a cursor 块; 通过它 cursor_value 恢复为 cursor 以获取下一页。

{
  "data": [ … ],
  "cursor": { "cursor_field": "started", "cursor_value": "2026-09-03T11:20:45.377937Z" }
}
curl "https://4pay.online/api/v1/transactions?env=test&limit=50&cursor=2026-09-03T11:20:45.377937Z" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

一页 cursor_value is null 是最后一个。

列表中的两个无声陷阱

start_cursor 被接受,然后 忽略( E) 除非我们... end_cursor 随它而来, 窗口读取 。 所建的循环 start_cursor 单曲翻阅第一页 永远,而且看起来很准确 就像"没有更多的了"

txid 被同样从伴侣的密钥中接受并被忽略,返回您的完整列表而不是 一个命令,保留平台 id 你从创建的电话 读回来与 GET /api/v1/transactions/:id.

总计交易​

通过多个交易获取汇总数据 :

GET /api/v1/transactions/aggregate
curl "https://4pay.online/api/v1/transactions/aggregate?currency=USD&status=charged" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

更新交易​

使用 PUT /api/v1/transactions/:id 以发放退款或取消交易。

退款​

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

Omit( Omit ) (英语). amount 全额退款。

取消( E)​

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

分两阶段付款(授权+扣押)​

对于支持两阶段的提供者,首先创建: type: "payment" ——资金持有但未缴获。

POST /api/v1/transactions/commit/:id
curl -X POST https://4pay.online/api/v1/transactions/commit/550e8400-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

3DS / 额外认证​

当交易需要额外的认证时( Q)3-安全,一次性 密码,钱包签名,其状态变为 action_required 说明 交易将动作本身带入 auth_params - 没有 action_required 布尔。 将动作显示在 协议规格. 付款人必须签到或完全到达的材料 additional_params_for_auth,带有 expires_at 在那之后,它必须是 提交结果时使用:

POST /api/v1/transactions/additional_params_for_auth/:id
{
  "params": {
    "otp": "123456"
  }
}

交易寿命周期​

created
  └─► charging                     processing
        ├─► action_required        payer action needed, then back to charging
        ├─► charged           ✅   settled
        ├─► rejected          ❌   no routing, limits or anti-fraud
        └─► failed            ❌   provider error, or cancelled before settlement
  └─► cancelled                    cancelled before processing started

charged
  ├─► reversed                     a settled transaction was returned
  └─► refunded                     refund completed

charged, rejected, failed 和 reversed 已经是最后的了 其他的都意味着 交易仍在飞行中。

reversed 只能跟随 charged - 已经解决了的归来 交易,而不是注销。结算到来前的注销为 failed.