CLIENT PORTAL

API Documentation

v1.1Base: https://api.unipay4u.com

UniPay 客户端应用使用的全部后端接口。开篇先用大白话讲清整条业务流程,后面是逐个接口的详细说明(请求/响应/鉴权)。

整体业务流程

用邮箱或手机号获取验证码注册,设置登录密码。登录后拿到 access_token(短期)和 refresh_token(长期)。之后所有需要登录的接口,请求头都带 Authorization: Bearer <access_token>。若开启了登录二次验证(短信/邮件),登录会先返回一个挑战,验证通过后才发 token。

实名认证(KYC)

部分功能(如汇款、开卡)需要实名。基础实名:上传证件照拿到文件 key,再提交姓名/证件号/地址等。开卡有独立的增强 KYC(见下方「开卡流程」)。

充值(USDT 入金)

选择链(BSC/TRX/ETH)拿到专属充值地址,把 USDT 转进来。链上确认后自动入账到主账户,可在充值订单里查进度。

资产操作

主账户里的 USDT 可以:站内转账给其他用户、提现到链上地址、跨境汇款到银行账户、购买节点(生息)。资金类操作都需要支付密码(开启了 2FA 还要 TOTP),确保是本人操作。

U 卡(虚拟 Visa)

开通信用卡账户(增强 KYC + 人脸核验)→ 充值到卡 → 开卡 → 用安全 iframe 查看完整卡号/CVV → 全球消费,账单实时同步。详见下方「开卡流程」。

U 卡开卡流程(KYC + SumSub 跳转)

提交开户资料

POST /api/card/account,提交持卡人信息(姓名拼音、证件、国籍、地址、证件正面照 base64 等)。后端向发卡方发起增强 KYC,返回一个 idv_url —— 这是 SumSub 的核验链接。

跳转 SumSub 做人脸+证件

前端新开网页跳转 idv_url,用户在手机上完成人脸识别 + 证件核验(SumSub 托管)。idv_url 有时效,过期需重新开户。

查询开户状态

轮询 GET /api/card/account 看 status:none(未开户)/applying(开户中)/incomplete(待核验)/success(成功)/failed(失败)。状态由发卡方回调驱动,并有服务端轮询兜底。

充值到卡 + 开卡

开户成功后,POST /api/card/transfer 从主账户充值到卡账户(达门槛后),再 POST /api/card/cards 开卡。卡状态 pending(制卡中)→ active(已激活)。

查看卡号 / 账单

POST /api/card/cards/:id/secure-token 拿到一次性短时效 iframe_url,在 iframe 内安全展示完整卡号/CVV(全程不落库不打印)。GET /api/card/transactions 查账单。

鉴权

除「公开」标注的接口外,所有接口都需要登录。鉴权基于 JWT:

Base URL:https://api.unipay4u.com,所有路径以 /api 开头。
登录/注册成功返回 access_token(短期)与 refresh_token(长期)。
需登录的接口在请求头带:Authorization: Bearer <access_token>。
access_token 过期(401)时,用 refresh_token 调 POST /api/auth/refresh 换新。
统一响应信封:成功 { code: 0, data: ... };错误 { code: 1xxxxx, message: "..." }。

常见错误码

code	name	含义
0	OK	成功
100006	InvalidCredential	账号或密码错误
100007	RateLimited	操作过于频繁(如验证码冷却中)
100008	Unauthorized	未登录或 token 失效
100020	PaymentPasswordNotSet	未设置支付密码
100021	PaymentPasswordWrong	支付密码错误
100023	TOTPRequired	需要 TOTP 二次验证
200001	InsufficientBalance	余额不足
200004	InvalidAmount	金额非法
300001	KYCInvalidFile	KYC 文件不合法
900003	InvalidParams	参数错误
900099	Internal	服务器内部错误

认证

POST/api/auth/code/send公开

发送验证码

⚠ 公开。同一联系方式有 60 秒冷却 + 失败锁定,请勿频繁调用。

参数	类型	必填	说明
contact	string	✓	邮箱或手机号
type	"email"\|"mobile"	✓	联系方式类型
mobile_prefix	string	—	手机区号,如 +86
scene	"register"\|"login"\|"reset"\|"change_contact"	✓	场景

响应示例

{ "code": 0 }

POST/api/auth/register公开

参数	类型	必填	说明
contact	string	✓	邮箱或手机号
type	"email"\|"mobile"	✓	类型
mobile_prefix	string	—	区号
code	string	✓	验证码
password	string	✓	登录密码
invite_code	string	—	邀请码

响应示例

{ "code": 0, "data": { "user": { "id": "a1b2c3d4-…", "uid": "U10001", "invite_code": "INV123", "is_node": false, "effective_level": 0 }, "access_token": "<JWT>", "refresh_token": "<token>" } }

POST/api/auth/login公开

⚠ 公开。若开启登录 2FA,返回 { mfa_required: true, pending_id, channels } 挑战。

参数	类型	必填	说明
contact	string	✓	账号
type	"email"\|"mobile"	✓	类型
password	string	—	登录密码
code	string	—	验证码(scene=login)

响应示例

{ "code": 0, "data": { "user": { "uid": "U10001", "effective_level": 0 }, "access_token": "<JWT>", "refresh_token": "<token>" } }

POST/api/auth/refresh公开

刷新令牌

参数	类型	必填	说明
refresh_token	string	✓	刷新令牌

响应示例

{ "code": 0, "data": { "access_token": "<JWT>", "refresh_token": "<token>" } }

POST/api/auth/login/2fa/send公开

登录2FA·发码

参数	类型	必填	说明
pending_id	string	✓	登录挑战 id
channel	"sms"\|"email"	✓	渠道

响应示例

{ "code": 0 }

POST/api/auth/login/2fa/verify公开

登录2FA·验证

参数	类型	必填	说明
pending_id	string	✓	挑战 id
channel	"sms"\|"email"	✓	渠道
code	string	✓	验证码

响应示例

{ "code": 0, "data": { "access_token": "<JWT>", "refresh_token": "<token>" } }

POST/api/auth/password/setup需登录

设置登录密码(首登)

参数	类型	必填	说明
password	string	✓	新密码

响应示例

{ "code": 0, "data": { "ok": true } }

POST/api/auth/password需登录

修改登录密码

参数	类型	必填	说明
old_password	string	✓	旧密码
new_password	string	✓	新密码

响应示例

{ "code": 0 }

POST/api/auth/logout需登录

登出

参数	类型	必填	说明
refresh_token	string	—	要吊销的刷新令牌

响应示例

{ "code": 0 }

GET/api/auth/devices需登录

登录设备列表

响应示例

{ "code": 0, "data": [ { "id": "d-…", "browser": "Chrome", "os": "iOS", "ip": "1.2.3.4", "is_master": true, "is_current": true, "last_seen_at": "2026-06-28T10:00:00Z" } ] }

POST/api/auth/devices/:id/kick需登录

踢出设备

响应示例

{ "code": 0 }

POST/api/auth/contact/bind/send需登录

绑定联系方式·发码

响应示例

{ "code": 0 }

POST/api/auth/contact/bind/verify需登录

绑定联系方式·验证

响应示例

{ "code": 0 }

POST/api/auth/login2fa需登录

开关登录二次验证

参数	类型	必填	说明
channel	"sms"\|"email"	✓	渠道
enabled	boolean	✓	开/关

响应示例

{ "code": 0 }

用户 / 团队

GET/api/user/me需登录

我的资料

响应示例

{ "code": 0, "data": { "uid": "U10001", "email": "u***@example.com", "invite_code": "INV123", "is_node": false, "kyc_status": "approved", "google2fa_enabled": false, "level": { "system": 0, "effective": 0 } } }

GET/api/user/invite-code需登录

邀请码 + 分享链接

响应示例

{ "code": 0, "data": { "code": "INV123", "share_url": "https://unipay4u.com/app?ref=INV123" } }

GET/api/user/team需登录

团队成员(分页)

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页数量

响应示例

{ "code": 0, "data": { "items": [ { "uid": "U10002", "is_node": false, "sub_count": 3, "created_at": "2026-06-01T00:00:00Z" } ], "page": 1, "size": 20 } }

GET/api/user/team/summary需登录

团队汇总

响应示例

{ "code": 0, "data": { "direct": 5, "recursive": 23, "this_week_new": 2, "this_month_new": 8 } }

GET/api/user/level需登录

我的等级(实时/差距)

响应示例

{ "code": 0, "data": { "is_node": true, "current_effective": 1, "realtime_system": 1, "manual_active": false } }

账户

GET/api/account/balance需登录

账户余额(主/节点)

响应示例

{ "code": 0, "data": { "main": { "balance": "1000.00", "frozen": "0" }, "node": { "balance": "0", "frozen": "0" }, "total": "1000.00" } }

GET/api/account/ledger需登录

资金流水

参数	类型	必填	说明
account	string	—	账户(main/node/card)
type	string	—	业务类型
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": { "items": [ { "id": "l-…", "account_type": "main", "direction": "debit", "amount": "100.00", "balance_after": "900.00", "biz_type": "withdraw", "memo": "USDT 提现", "created_at": "2026-06-28T10:00:00Z" } ], "page": 1, "size": 20 } }

POST/api/account/transfer-internal需登录

主/节点账户互转

⚠ 资金操作:需支付密码(开 2FA 还需 TOTP)。

参数	类型	必填	说明
from	"main"\|"node"	✓	转出
to	"main"\|"node"	✓	转入
amount	string	✓	金额
payment_password	string	✓	支付密码
totp_code	string	—	TOTP

响应示例

{ "code": 0, "data": { "transfer_id": "t-…", "from": "main", "to": "node", "amount": "100.00", "created_at": "2026-06-28T10:00:00Z" } }

资产 / 行情

GET/api/upt/balance需登录

UPT 余额(主/节点)

响应示例

{ "code": 0, "data": { "main": 0, "node": 120, "total": 120 } }

GET/api/quote/upt-kline公开

UPT 行情 K 线

⚠ 公开,无需登录。

响应示例

{ "code": 0, "data": { "klines": [ { "time": 1782470000, "close": 1.02 } ], "last_price": 1.02, "default_price": 1.0 } }

充值

GET/api/recharge/address需登录

获取充值地址

参数	类型	必填	说明
chain	string	✓	链:BSC/TRX/ETH

响应示例

{ "code": 0, "data": { "chain": "BSC", "address": "0x1234…abcd", "qr_code_payload": "0x1234…abcd", "min_deposit_usdt": "1" } }

GET/api/recharge/orders需登录

充值订单列表

参数	类型	必填	说明
status	string	—	状态过滤
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": { "items": [ { "id": "r-…", "chain": "BSC", "amount_credited": "100.00", "status": "credited", "tx_hash": "0x…", "created_at": "2026-06-28T10:00:00Z" } ] } }

GET/api/recharge/orders/:id需登录

充值订单详情

响应示例

{ "code": 0, "data": { "id": "r-…", "chain": "BSC", "status": "credited", "amount_received": "100.00", "amount_credited": "100.00", "confirmations": 20 } }

USDT 提现

POST/api/withdrawal/usdt需登录

发起 USDT 提现

⚠ 资金操作:需支付密码(开 2FA 还需 TOTP)。

参数	类型	必填	说明
chain	string	✓	链
to_address	string	✓	收款地址
amount	string	✓	金额
payment_password	string	✓	支付密码
totp_code	string	—	TOTP

响应示例

{ "code": 0, "data": { "order_id": "w-…", "chain": "TRX", "to_address": "T…", "amount": "100.00", "fee": "2.00", "amount_net": "98.00", "status": "submitted", "created_at": "2026-06-28T10:00:00Z" } }

GET/api/withdrawal/usdt/orders需登录

提现订单列表

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": { "items": [ { "id": "w-…", "chain": "TRX", "amount": "100.00", "fee": "2.00", "amount_net": "98.00", "status": "confirmed", "tx_hash": "…" } ] } }

站内转账

GET/api/transfer/lookup需登录

按 UID 查收款人

参数	类型	必填	说明
q	string	✓	对方 UID

响应示例

{ "code": 0, "data": { "uid": "U10002", "user_id": "a1b2c3d4-…", "name_masked": "张*三", "avatar_color": "#7B3AC2" } }

POST/api/transfer需登录

发起站内转账

⚠ 资金操作:需支付密码(开 2FA 还需 TOTP)。

参数	类型	必填	说明
to_user_id	string	✓	收款人 user_id
amount	string	✓	金额
memo	string	—	备注
payment_password	string	✓	支付密码
totp_code	string	—	TOTP

响应示例

{ "code": 0, "data": { "transfer_id": "t-…", "amount": "50.00", "fee": "0", "status": "success", "created_at": "2026-06-28T10:00:00Z" } }

GET/api/transfer/orders需登录

转账记录

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": { "items": [ { "id": "t-…", "to_user_id": "a1b2c3d4-…", "amount": "50.00", "status": "success" } ] } }

跨境汇款

USDT → 人民币跨境汇款到银行账户(含收款人管理与银行目录)。

GET/api/remittance/recipients需登录

收款人列表

响应示例

{ "code": 0, "data": [ { "id": "rc-…", "nickname": "母亲", "account_holder": "ZHANG SAN", "bank_name": "ICBC", "account_number": "****6789", "review_status": "approved", "status": "active" } ] }

POST/api/remittance/recipients需登录

新增收款人

参数	类型	必填	说明
account_holder	string	✓	收款人姓名
account_number	string	✓	账号
bank_name	string	✓	银行
id_number	string	✓	证件号
msisdn	string	✓	手机号
email	string	✓	邮箱
account_currency_code	string	✓	币种

响应示例

{ "code": 0, "data": { "id": "rc-…", "review_status": "pending", "status": "active" } }

PUT/api/remittance/recipients/:id需登录

编辑收款人

响应示例

{ "code": 0, "data": { "id": "rc-…", "review_status": "pending" } }

DELETE/api/remittance/recipients/:id需登录

删除收款人

响应示例

{ "code": 0, "data": { "ok": true } }

POST/api/remittance/preview需登录

汇款试算

参数	类型	必填	说明
recipient_id	string	✓	收款人
amount	string	✓	汇款本金(USDT)

响应示例

{ "code": 0, "data": { "principal": "100.00", "recipient_cnh": "720.00", "fee_usdt": "1.00", "total_debit": "101.00", "display_fee_cny": "20.00" } }

POST/api/remittance/submit需登录

提交汇款

⚠ 资金操作:需支付密码(开 2FA 还需 TOTP)。

参数	类型	必填	说明
recipient_id	string	✓	收款人
amount	string	✓	本金 USDT
payment_password	string	✓	支付密码
totp_code	string	—	TOTP

响应示例

{ "code": 0, "data": { "id": "rm-…", "principal_usdt": "100.00", "amount_cnh": "720.00", "status": "processing" } }

GET/api/remittance/orders需登录

汇款订单列表

响应示例

{ "code": 0, "data": { "items": [ { "id": "rm-…", "amount_cnh": "720.00", "status": "completed" } ] } }

GET/api/remittance/orders/:id需登录

汇款订单详情

响应示例

{ "code": 0, "data": { "id": "rm-…", "principal_usdt": "100.00", "amount_cnh": "720.00", "status": "completed" } }

GET/api/remittance/banks需登录

银行目录

响应示例

{ "code": 0, "data": [ { "bank_code": "ICBC", "name": "工商银行", "swift_code": "ICBKCNBJ" } ] }

GET/api/remittance/banks/branches需登录

支行查询(CNAPS)

参数	类型	必填	说明
bank_code	string	—	银行码
q	string	—	关键词
cnaps	string	—	联行号

响应示例

{ "code": 0, "data": [ { "cnaps_code": "1022…", "bank_name": "工商银行北京分行" } ] }

节点

购买节点参与生态(生息/返佣/等级)。

GET/api/node/dashboard需登录

节点看板

响应示例

{ "code": 0, "data": { "is_node": true, "node_count": 1, "current_unit_price": "100.00", "available_stock": 500, "upt_balance": 120 } }

GET/api/node/quote需登录

购买报价

参数	类型	必填	说明
qty	number	✓	数量

响应示例

{ "code": 0, "data": { "qty": 1, "unit_price_first_tier": "100.00", "total_usdt": "100.00", "available": 500, "remaining_for_user": 9 } }

POST/api/node/buy需登录

购买节点

参数	类型	必填	说明
quantity	number	✓	数量
expected_total_usdt	string	✓	预期总价(防滑点)

响应示例

{ "code": 0, "data": { "order_id": "n-…", "quantity": 1, "total_usdt": "100.00", "upt_granted": 100, "status": "paid" } }

GET/api/node/orders需登录

购买订单

响应示例

{ "code": 0, "data": { "items": [ { "id": "n-…", "quantity": 1, "total_usdt": "100.00", "status": "paid" } ] } }

GET/api/node/cashback需登录

返现记录

响应示例

{ "code": 0, "data": { "items": [ { "id": "cb-…", "amount": "5.00", "rate": "0.05", "status": "paid" } ] } }

GET/api/node/holdings需登录

我的持有

响应示例

{ "code": 0, "data": { "count": 1, "upt_balance": 120, "is_node": true, "effective_level": 1 } }

返佣

GET/api/commission/me/summary需登录

返佣汇总

响应示例

{ "code": 0, "data": { "total": "123.45", "today": "1.20" } }

GET/api/commission/rewards需登录

返佣明细

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": { "items": [ { "id": "cr-…", "source_biz_type": "transfer_fee", "amount": "0.50", "layer": 1, "status": "paid" } ] } }

安全

GET/api/security/status需登录

安全状态

响应示例

{ "code": 0, "data": { "payment_password_set": true, "totp_enabled": false } }

POST/api/security/payment-password需登录

设置/修改支付密码

⚠ 改密有 24 小时冷却。

参数	类型	必填	说明
login_password	string	—	登录密码(首次设置用)
old_payment_password	string	—	旧支付密码(修改用)
new_pin	string	✓	新支付密码

响应示例

{ "code": 0 }

POST/api/security/2fa/setup需登录

TOTP 2FA·初始化

参数	类型	必填	说明
login_password	string	✓	登录密码

响应示例

{ "code": 0, "data": { "secret": "<base32>", "otpauth_uri": "otpauth://totp/UniPay:U10001?secret=…" } }

POST/api/security/2fa/confirm需登录

TOTP 2FA·确认开启

参数	类型	必填	说明
code	string	✓	6 位验证码

响应示例

{ "code": 0 }

POST/api/security/2fa/disable需登录

关闭 TOTP 2FA

参数	类型	必填	说明
payment_password	string	✓	支付密码

响应示例

{ "code": 0 }

GET/api/security/log需登录

安全日志

响应示例

{ "code": 0, "data": [ { "event_type": "login", "ip": "1.2.3.4", "created_at": "2026-06-28T10:00:00Z" } ] }

实名认证

GET/api/kyc/me需登录

我的实名状态

响应示例

{ "code": 0, "data": { "stage1": { "status": "approved", "updated_at": "2026-06-28T10:00:00Z" }, "stage2": null } }

POST/api/kyc/upload需登录

上传证件照

⚠ multipart/form-data,字段名 file;限图片/PDF + 大小限制。返回文件 key。

响应示例

{ "code": 0, "data": { "key": "kyc/2026/…/front.jpg" } }

POST/api/kyc/basic需登录

提交基础实名

参数	类型	必填	说明
real_name	string	✓	真实姓名
id_type	string	✓	证件类型
id_number	string	✓	证件号
id_photo_front	string	✓	证件正面 key
id_photo_back	string	—	证件背面 key
address	string	✓	地址
contact	string	✓	联系方式

响应示例

{ "code": 0, "data": { "status": "pending", "created_at": "2026-06-28T10:00:00Z" } }

U 卡(虚拟 Visa)

开卡需增强 KYC(SumSub 人脸+证件核验,见上方「开卡流程」)。卡账户只进不出。

POST/api/card/account需登录

开户(增强 KYC)

⚠ 返回 idv_url(SumSub 核验链接),前端新开网页跳转。姓名限拉丁字母。开户失败或认证未通过(idv FAILED)后,用相同接口重新提交即可——系统会自动更新已有持卡人信息(可改生日/证件/地址等,姓名不可改)并返回新的 idv_url 重新认证,无需更换邮箱或手机。

参数	类型	必填	说明
first_name	string	✓	名(拼音)
last_name	string	✓	姓(拼音)
email	string	✓	邮箱
country_code	string	✓	国家码(ISO2)
phone_number	string	✓	手机号
date_of_birth	string	✓	生日 YYYY-MM-DD
nationality	string	✓	国籍
id_type	"ID_CARD"\|"PASSPORT"	✓	证件类型
id_number	string	✓	证件号
id_front	string	✓	证件正面 base64
addr_country	string	✓	地址国家
addr_state	string	✓	省/州
addr_city	string	✓	城市
addr_line1	string	✓	地址行
addr_line_en	string	✓	英文地址
addr_postal_code	string	✓	邮编

响应示例

{ "code": 0, "data": { "status": "applying", "idv_url": "https://in.sumsub.com/websdk/p/…", "idv_expires_at": "2026-06-28T11:00:00Z", "card_balance": "0", "cardholder_id": "ch-…" } }

GET/api/card/account需登录

开户状态(轮询)

响应示例

{ "code": 0, "data": { "status": "success", "card_balance": "209.00", "cardholder_id": "ch-…", "idv_url": "", "idv_expires_at": "" } }

POST/api/card/transfer需登录

充值到卡(只进不出)

⚠ 资金操作:需支付密码。仅支持 main/node → card。

参数	类型	必填	说明
from	"main"\|"node"	✓	转出账户
to	"card"	✓	固定 card
amount	string	✓	金额
payment_password	string	✓	支付密码
totp_code	string	—	TOTP

响应示例

{ "code": 0, "data": { "transfer_id": "t-…" } }

POST/api/card/cards需登录

开卡

⚠ 需卡账户余额达门槛,开卡费成功后扣。

响应示例

{ "code": 0, "data": { "card_id": "cd-…", "status": "pending" } }

GET/api/card/cards需登录

卡列表 / 状态

响应示例

{ "code": 0, "data": { "items": [ { "id": "cd-…", "status": "active", "currency": "USD", "card_limit": "207.00", "masked_pan": "****0477" } ] } }

POST/api/card/cards/:id/secure-token需登录

安全卡面(PAN/CVV iframe)

⚠ 返回一次性、短时效 iframe_url;完整卡号/CVV 只在 iframe 内展示,不落库。

响应示例

{ "code": 0, "data": { "iframe_url": "https://embedded.uqpay.com/iframe/card?token=…&cardId=…" } }

GET/api/card/transactions需登录

卡账单(进页面拉取)

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页(10-100)

响应示例

{ "code": 0, "data": { "items": [ { "transaction_id": "tx-…", "type": "AUTHORIZATION", "status": "APPROVED", "billing_amount": "7.44", "billing_currency": "USD", "merchant_name": "Alipay", "available_balance": "201.56", "transaction_time": "2026-06-26T01:48:00Z" } ], "has_more": false, "available_balance": "201.56" } }

站内信

GET/api/inbox需登录

通知列表

参数	类型	必填	说明
page	number	—	页码
size	number	—	每页

响应示例

{ "code": 0, "data": [ { "id": 1, "type": "recharge_credited", "title": "充值到账", "body": "您的充值 100 USDT 已到账", "read": false, "created_at": "2026-06-28T10:00:00Z" } ] }

GET/api/inbox/unread_count需登录

未读数

响应示例

{ "code": 0, "data": { "count": 3 } }

POST/api/inbox/:id/read需登录

标记已读

响应示例

{ "code": 0 }

POST/api/inbox/read_all需登录

全部已读

响应示例

{ "code": 0 }