对接 GemCredit 账户中的贷款台账

一个 GemCredit 账户承载了一笔消费贷款的完整生命周期：按 App 自己的描述，本金介于 500 万到 3500 万越南盾之间，期限最长 12 个月，签约前屏幕上会列明利息和各项费用，随后是还款计划、实时的结清余额，以及带时间戳的交易流水。这些都是真实的、逐用户的服务端状态——正是放贷方、催收合作方或个人理财产品想要读取并保持同步的那种数据。与此同时，越南的开放银行规则也在这套体系周边逐步落地，接入路径因此有所不同。本文说明这些数据存放在哪里、经授权的接入方式，以及我们最终交付的内容。

先给出我们的判断：面向借款人的 App 就是 GemCredit 一笔贷款的完整、实时接入面，因此集成方案的做法是在账户持有人授权下分析该 App 自身的流量，并随着 Circular 64 分阶段推进的经同意开放 API 逐步可用，把银行通道那部分并入进来。接口工作由我们完成；客户负责提供 App 名称，以及他们想从数据里得到什么。

账户里保存了什么

下表每一行都是 GemCredit App 向自己用户展示的一个数据面，尽量沿用 App 描述里的叫法。集成方案读取这些数据的方式，与账户持有人本人看到的一致。

接入路径

真正适用于 GemCredit 的接入路径有三条。与其说它们是相互替代的方案，不如说是彼此重叠的阶段。

对借款人 App 做授权协议分析

移动端持有完整台账，因此我们在账户持有人授权下抓取并记录它自身的请求/响应流量：注册与验证握手、会话令牌及其刷新，再到档案、还款计划、余额和历史等接口。可触达范围：App 向用户展示的一切。工作量：中等，主要花在梳理鉴权链路和分页上。稳定性：与 App 版本发布相关，我们用带版本的固定样例（fixtures）来管理。工作环境会与客户一起搭建——在启动阶段安排一个知情同意的借款人账户，或一个测试账户。

经用户同意的账户访问

在知情同意的借款人实时会话中运行，按你控制的节奏拉取当前的还款计划、结清和交易数据。它与第一条路径配合，正是让同步保持新鲜的部分。同意范围与撤回都会记录，符合 PDPL 要求。

Circular 64 经同意开放 API（银行通道）

GemCredit 的资金通过一个以借款人本人名义开立的银行账户流转。随着越南各银行依据 Circular 64 上线经同意的开放 API 查询——经客户同意的信息查询阶段将在 2025 年 3 月 1 日生效日起的 18 个月内落地——这些查询将成为在银行侧核对放款与还款的合规方式。我们在设计时就让方案能够切换到该接口而无需重构。App 原生的历史导出功能（借款人可自行导出记录）在验证阶段可作为人工交叉核对之用。

读取还款计划的请求

以下仅为示意——字段名和结构会在开发过程中对照实时 App 确认，并非摘自任何已公开的 GemCredit 文档。它展示的是鉴权握手和一次还款计划读取，用的是 App 自带示例贷款里的推算数字。

# Device-bound session after register / OTP verify
POST /v1/auth/token
  { "phone": "+84xxxxxxxxx", "device_id": "…", "otp": "######" }
  -> 200 { "access_token": "…", "refresh_token": "…", "expires_in": 1800 }

# Read the repayment plan for one loan
GET /v1/loans/{loan_id}/schedule
  Authorization: Bearer <access_token>
  -> 200 {
       "loan_id": "…",
       "principal_vnd": 10000000,     # integer VND, no minor unit
       "term_months": 12,
       "apr_pct": 21.9,
       "outstanding_vnd": 12190000,
       "installments": [
         { "due_date": "15/07/2026", "amount_vnd": 1015833, "status": "due" },
         { "due_date": "15/08/2026", "amount_vnd": 1015833, "status": "scheduled" }
         # …
       ]
     }

# 401 -> refresh once. Persistent 401 -> consent withdrawn or session
# revoked: stop the pull, log it, do not retry.
      

注意日期是 dd/mm/yyyy 格式，VND 金额则不含小数位。二者在进入规范化 schema 时都会归一化，以保证数字对账一致。

你会拿到什么

交付物紧扣 GemCredit 的实际接口，而非一套通用模板：

• 一份 OpenAPI/Swagger 规范，覆盖鉴权、贷款档案、还款计划、余额和交易流水等接口。
• 一份协议与鉴权流程报告：注册/验证链路、bearer 令牌、刷新行为以及撤回信号。
• 可运行的源码——Python 或 Node.js——用于还款计划、结清和历史的读取，分页已处理妥当。
• 自动化测试，包括令牌刷新、同意过期路径，以及 VND/日期归一化检查。
• 接口文档，即使从未见过这个 App 的开发者也能照着上手。
• 依据 PDPL 编写的同意记录与留存指引，让你所构建的东西经得起追责。

Circular 64 与 PDPL

有两部越南法规为这项工作划定框架，而且都很新。开放银行受 Circular 64/2024/TT-NHNN 约束，该通函由越南国家银行发布，2025 年 3 月 1 日生效；它分三个阶段推进标准化开放 API——先是公开信息查询，其次是经客户同意的信息查询（即账户信息服务式的访问），最后是支付发起——各银行须在 2025 年年中前报送 API 目录，并于 2027 年 3 月 1 日前全面合规。对于一家非银行放贷机构，它主要管的是贷款所依托的银行通道，这也是为什么我们现在把借款人 App 当作实时接入面，把经同意的开放 API 当作银行侧的长期稳定路径。

个人数据则归《个人数据保护法》管辖，该法自 2026 年 1 月 1 日起施行，取代了第 13/2023/ND-CP 号法令，同时提高了同意门槛和处罚力度。我们坚持同意优先：每次读取都绑定一份可记录、可撤回、有明确目的的同意；访问留痕；数据最小化到集成所需；在项目需要时签署保密协议。另有第 94/2025/ND-CP 号法令下的金融科技监管沙盒，自 2025 年 7 月 1 日起运行，管辖 P2P 借贷和信用评分试点——如果一个与 GemCredit 相邻的产品进入受监管测试，它是相关背景，但对读取一个已存在的账户而言关系不大。

我们会处理的细节

这个 App 实实在在带来的一些约束，以及我们在自己这一侧的处理方式：

• VND 与越南本地化。金额是不含小数子单位的大整数，日期是 dd/mm/yyyy。我们在边界处对二者做规范化，使每月 1,015,833 越南盾的数字和约 12,190,000 越南盾的结清额在下游能干净地对上。
• 同意的生命周期。我们围绕 PDPL 的同意与撤回模型来设计同步，因此借款人撤回同意会即时传导，读取随即停止，事件也会留痕——绝不做无声、陈旧的抓取。
• 前端变动。档案和还款计划界面会随版本发布而变化。我们保留还款计划、余额和历史响应的带版本固定样例，并在每次发布时重新核对，这样界面一变会体现为一个失败的测试，而不是悄无声息的数据漂移。
• 银行通道的时间节点。放款和还款会触及一个以借款人本人名义开立的银行账户。我们对跨放贷方台账与该银行的资金流向建模，并把接口设计成随着银行开放而可切换到 Circular 64 的经同意查询。

访问权限和启动由我们与你一起在项目中安排——共同搭建一个知情同意的账户或测试环境。这是我们的步骤，在开发过程中处理。

数据的去向

这套集成常见的服务对象：

• 需要每位借款人到期日和当前结清额来安排提醒和结算时点的催收或贷后服务平台。
• 把知情同意用户的还款计划和历史汇入一处、统一呈现其债务的个人理财或负债聚合 App。
• 放贷方一侧的对账任务，将 App 内交易流水与放款银行账户逐笔匹配。
• 跟踪申请到审批状态、并对照 21.9% 上限核查年化利率的分析流水线。

我们梳理过的界面

梳理上述接口时用到的商店截图。点击可放大。

越南同类 App

越南同一市场里的其他消费金融 App 也保存着类似的账户数据；一套归一化 schema 就能让一次集成覆盖其中好几个。此处列出仅为提供参照，并非排名。

• Home Credit (Tài Chính Online)——消费分期与现金贷，App 内含还款计划和余额。
• FE Credit (FE ONLINE)——现金贷、卡片和分期方案，各有自己的账户台账。
• Mcredit——与 MB 关联的消费金融机构，在 App 内保存贷款账户和还款数据。
• Mirae Asset Finance Vietnam——消费与分期贷款，含绑定账户的对账单。
• Lotte Finance——通过其 App 管理的消费信贷与卡片账户。
• Shinhan Finance——消费贷款账户、还款计划和结清金额。
• Cake by VPBank——一家同时放贷的数字银行，保存余额和交易流水。
• Doctor Dong——短期在线贷款，含申请状态和还款跟踪。
• Tima——一个贷款撮合平台，保存借款人的申请与撮合记录。

本文如何撰写

数据接口来自 GemCredit 自己的 Play Store 页面和描述（贷款额度、期限、21.9% 的年化利率上限以及推算的还款示例）；监管框架取自越南国家银行关于开放 API 的 Circular 64、2025 年《个人数据保护法》以及第 94 号法令下的金融科技沙盒。已于 2026 年 6 月对照下列来源核对。

• GemCredit 在 Google Play（pb.publicbankamc.vn）
• Circular 64/2024/TT-NHNN——越南开放 API 框架
• 越南《个人数据保护法》（PDPL 2025）
• 第 94/2025/ND-CP 号法令——金融科技监管沙盒

由 OpenBanking Studio 集成团队梳理 · 2026 年 6 月。

对接方常问的问题

GemCredit 账户里哪些数据值得读取？

借款人填写的贷款档案，签约前展示的额度与期限方案及其利息、费用和还款计划，带有每期到期日的还款计划，实时的结清余额，以及带时间戳的交易流水。以借款人本人名义开立、用于放款和还款的银行账户，把这些数据与资金流向串联在一起。

Circular 64 会改变我们读取 GemCredit 数据的方式吗？

越南国家银行（SBV）发布的 Circular 64/2024/TT-NHNN 于 2025 年 3 月 1 日生效，在银行侧分阶段引入经用户同意的开放 API 查询，其中包括账户信息服务。当前可用的接入面仍是借款人 App 本身，在借款人授权下开展；随着经同意查询阶段上线，它将成为对接放款与还款银行通道的长期稳定路径。

如果借款人依据 PDPL 撤回同意，你们如何处理？

我们把同意记录和撤回机制内建到同步流程中，一旦撤回即停止读取并留痕，符合越南《个人数据保护法》——该法自 2026 年 1 月 1 日起施行。同意范围、目的和留存期限逐次读取时都会记录在案，而非默认假定。

数据全部是越南盾金额和越南日期格式，如何归一化？

我们把 VND 金额按不含小数位的整数处理，并将 dd/mm/yyyy 的到期日转换为规范化 schema 中的 ISO 日期，使还款计划、利息和结清金额能与任何下游系统对账一致。

交付物就是源代码：面向还款计划、余额和交易流水接口的可运行读取、一份 OpenAPI 规范、测试与文档，价格 300 美元起，且只在交付之后、你用自己的 GemCredit 数据验证过确实可用之后才计费。不想自己托管？同一套接口也能作为按调用计费的托管 API 运行，无需预付——你调用，就按调用付费。无论哪种方式，周期都是一到两周。告诉我们 App 名称和你想从数据里得到什么，访问权限和合规环节就会从那里开始与你一起安排——启动一个 GemCredit 集成。