汇入通知接口
发送一份加密通知，告知收款账户、金额和币种。通知成功后进入“在途”，不代表资金已经实际到账。
/v1/inward-remittance-notificationshttps://api-integration-gateway-my-7c92.hipayx.com/v1/inward-remittance-notifications
四步完成认证与加密
- 通过私有交接渠道获取 Client ID、API Token 和独立的 AES 加密密钥。真实凭证不在公开文档中展示。
- 将下表业务字段组成 JSON，用 AES-256-GCM 加密；每次由示例代码生成新的12字节随机 nonce。
- 通过 HTTPS POST 提交两个字段 nonce 和 ciphertext，并在请求头携带 Token 和 Client ID。
- 服务器先验证 Token，再用双方持有的同一密钥解密，校验字段并防重保存。共享密钥是秘密，不是公开密钥。
Authorization: Bearer YOUR_API_TOKEN X-Client-Id: YOUR_CLIENT_ID Content-Type: application/json
{"nonce":"BASE64_NONCE","ciphertext":"BASE64_CIPHERTEXT_AND_TAG"}密钥为32个随机字节，使用标准带填充 Base64 编码交接。nonce 为12个随机字节。ciphertext 为密文后拼接16字节 GCM 校验标签，再进行标准 Base64 编码。同一密钥下严禁复用 nonce。不要把 Token 当作加密密钥，也不要使用短数字密码。
附加认证数据（AAD）固定为以下字符串，末尾替换为实际 Client ID。示例代码会自动处理：
hipayx-v1|POST|/v1/inward-remittance-notifications|YOUR_CLIENT_ID
只接受加密后的 JSON 信封，不接受明文业务字段。旧 JWE、公私钥加密方案已停用。
解密后的业务字段
所有字段必填；不允许额外字段。备注可以为空字符串。
| 字段 | 类型 | 说明 |
|---|---|---|
| client_id | string | 分配给您的调用方编号，须与 X-Client-Id 一致。 |
| notification_id | string | 每笔订单的独立编号；8–64 位字母、数字、下划线或连字符。重试不变，不得用于另一笔订单。 |
| batch_id | string | 户名前六个英文字母大写 + YYMMDD + 001–999。 |
| timestamp | integer | 当前 Unix 秒级时间戳，允许与服务器相差五分钟；重试可更新。 |
| recipient_name | string | 收款账户户名，1–140 个字符；目前批次规则要求至少六个英文字母。 |
| recipient_account | string | 收款账号，4–64 个字符；字母或数字开头，可含空格和连字符，保留前导零。 |
| recipient_swift | string | 大写的 8 或 11 位 SWIFT/BIC；仅校验格式，不代表核实银行或账户归属。 |
| amount | string | 正数十进制字符串，整数最多15位、小数最多4位，例如 "12500.00"；不含货币符号、逗号或科学计数。 |
| currency | string | 大写 ISO 4217 币种，例如 USD、AUD、CNY。格式认可不等于支持该付款路线。 |
| remarks | string | 备注，最多500字；无备注传空字符串，不得含控制字符或密码。 |
批次号与独立订单编号
EXAMPLE COMPANY → EXAMPL + 260917 + 001 EXAMPL260917001
取收款账户“户名”的前六个英文字母，忽略空格和标点并转为大写，不是账号前六位。日期格式 YYMMDD，流水号001–999，由发送方协调分配。同一天同一前缀用完999后不可回到001。业务日期的时区以及不足六个英文字母的户名处理方式，需要在接入时另行约定。
批次号是分组信息，不承担独立防重。防重依据是 Client ID + notification_id。同一编号与相同业务内容重试返回原回执；同一编号不同业务内容拒绝。重试保留批次号与独立编号，时间戳可以更新，重新加密时必须生成新 nonce。
响应与重试
{
"receipt_id": "receiver-generated-uuid",
"notification_id": "your-order-reference",
"status": "in_transit",
"duplicate": false,
"received_at": 1789600000
}| 202 | 已保存，状态在途，不代表到账或香港入库完成。 |
|---|---|
| 200 | 重复通知，返回原回执，不新增。 |
| 400 | 密文、字段或时间戳无效。 |
| 401 | 调用方凭证缺失、错误或已停用。 |
| 409 | 独立编号内容冲突，或重复使用 nonce 加密不同内容。 |
| 413 / 415 | 超过16 KiB，或不是 application/json。 |
| 429 | 请求过快，请退避重试。 |
| 5xx / timeout | 结果不确定，使用相同独立编号和业务内容重试。 |
请求失败可从2秒起指数退避并加入随机延迟，间隔上限1分钟；持续失败应人工检查，不要无限重试。
已入账异步回调
收到通知后自动进入 in_transit。只有我方受信任的内部确认才可变更为 credited，并发送回调；对方不能通过通知接口自行标记已入账。
回调地址配置
合作方私下提供 HTTPS 回调地址，按 Client ID 配置；不放在每笔通知中。只允许公网443端口，不跟随跳转，不允许内网地址。目标公网 IP 经核对后固定，变化时需重新审核。
{
"event_id": "stable-event-uuid",
"event_type": "remittance.credited",
"client_id": "YOUR_CLIENT_ID",
"notification_id": "your-order-reference",
"batch_id": "EXAMPL260917001",
"receipt_id": "original-receipt-uuid",
"status": "credited",
"credited_at": 1789600000,
"confirmation_reference": "ledger-reference"
}X-HIPAYX-Event-Id: stable-event-uuid X-HIPAYX-Timestamp: current-unix-seconds X-HIPAYX-Signature: v1=HEX_HMAC_SHA256 HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)
回调通过 HTTPS 发送签名 JSON，不包含收款账号；回调签名密钥与 Token、AES 密钥分开。按原始报文字节验签，恒定时间比较，拒绝超过5分钟的时间戳，并按 event_id 防重。持久保存后返回2xx。
非2xx或网络失败最多尝试12次，间隔从30秒指数增加、上限1小时。事件编号与正文不变，每次更新签名时间戳。超过次数保留待人工处理；未配置地址则保持待发送，不会丢弃。
代码与上线边界
pip install cryptography httpx HIPAYX_CLIENT_ID HIPAYX_API_KEY HIPAYX_ENCRYPTION_KEY HIPAYX_API_URL python client_example.py
通过安全环境变量或密钥管理器传入凭证；HIPAYX_ENCRYPTION_KEY 为私下交接的 Base64 密钥。示例使用虚拟业务数据，不会转账。密钥不可写入浏览器代码、公开仓库或 URL。
当前马来西亚服务接收并保存密文，尚未对接香港主系统。实际合作方回调地址仍需配置和联调；没有自动核实银行到账或改余额。
support@hipayx.com