TBC Bank API Integration Guide
Full reference for building integrations with TBC Bank's Open Banking, PSD2, and payment APIs.
Quick Reference
| Topic | Reference File |
|---|
| OAuth2 & Authentication | INLINECODE0 |
| Account Information Services (AIS) |
references/ais.md |
| Payment Initiation Services (PIS) |
references/pis.md |
| Consents & SCA |
references/consent.md |
| Online Installments |
references/installments.md |
| TPay Gateway |
references/tpay.md |
Base URLs
| Environment | Base URL |
|---|
| Sandbox | INLINECODE6 |
| Dev OpenBanking |
https://dev-openbanking.tbcbank.ge |
| Production |
https://api.tbcbank.ge |
| OpenBanking |
https://openbanking.tbcbank.ge |
API path prefix: /0.8/v1/ (PSD2) or /v1/, /v2/ for non-PSD2
Universal Headers
Every request must include:
CODEBLOCK0
For signed requests (TPP operations) also include:
CODEBLOCK1
Common Error Response
CODEBLOCK2
Key Workflows
1. Account Data Access (AIS)
- 1. Create consent → get INLINECODE13
- Redirect user for SCA authorization
- Exchange auth code for token with consent scope
- Call account/balance/transaction endpoints
→ Read references/consent.md then INLINECODE15
2. Payment Initiation (PIS)
- 1. Initiate payment → get
paymentId + INLINECODE17 - Start authorization via redirect or OAuth SCA
- Poll or use webhook for payment status
→ Read INLINECODE18
3. OAuth2 Setup
→ Read
references/auth.md first — needed by all other flows
4. Installment Loans
→ Read INLINECODE20
5. TPay Gateway
→ Read INLINECODE21
Response Conventions
- - All monetary amounts are strings (e.g.,
"amount": "30.00") - Dates use ISO 8601 (
2023-07-01, 2025-03-26T00:00:00) - HATEOAS
_links pattern — always follow links from responses, don't hardcode paths - INLINECODE26 codes:
RCVD (received), ACTC (accepted technical), ACSP (accepted settlement in progress), ACCC (accepted credit complete), RJCT (rejected) - INLINECODE32 codes:
received, psuIdentified, psuAuthenticated, scaMethodSelected, finalised, INLINECODE38
TBC银行API集成指南
关于TBC银行开放银行、PSD2及支付API集成的完整参考文档。
快速参考
| 主题 | 参考文件 |
|---|
| OAuth2与身份认证 | references/auth.md |
| 账户信息服务(AIS) |
references/ais.md |
| 支付发起服务(PIS) | references/pis.md |
| 授权与SCA | references/consent.md |
| 在线分期 | references/installments.md |
| TPay网关 | references/tpay.md |
基础URL
| 环境 | 基础URL |
|---|
| 沙箱环境 | https://test-api.tbcbank.ge |
| 开发开放银行 |
https://dev-openbanking.tbcbank.ge |
| 生产环境 | https://api.tbcbank.ge |
| 开放银行 | https://openbanking.tbcbank.ge |
API路径前缀： /0.8/v1/ (PSD2) 或 /v1/、/v2/ (非PSD2)
通用请求头
每个请求必须包含：
http
Authorization: Bearer {access_token}
Content-Type: application/json
X-Request-ID: {uuid4} # 每个请求唯一
PSU-IP-Address: {user_ip} # 终端用户IP地址
对于签名请求(TPP操作)还需包含：
http
Digest: SHA-256={base64bodyhash}
Signature: keyId={cert_serial},algorithm=rsa-sha256,headers=...,signature=...
通用错误响应
json
{
code: string,
type: https://...,
title: 错误摘要,
status: 400,
detail: 详细描述,
traceId: abc123
}
关键工作流程
1. 账户数据访问(AIS)
- 1. 创建授权 → 获取 consentId
- 重定向用户进行SCA授权
- 使用授权范围交换授权码获取令牌
- 调用账户/余额/交易接口
→ 先阅读 references/consent.md，再阅读 references/ais.md
2. 支付发起(PIS)
- 1. 发起支付 → 获取 paymentId + _links
- 通过重定向或OAuth SCA启动授权
- 轮询或使用webhook获取支付状态
→ 阅读 references/pis.md
3. OAuth2设置
→ 首先阅读 references/auth.md — 所有其他流程都需要
4. 分期贷款
→ 阅读 references/installments.md
5. TPay网关
→ 阅读 references/tpay.md
响应规范
- - 所有货币金额为字符串（例如 amount: 30.00）
- 日期使用ISO 8601格式（2023-07-01、2025-03-26T00:00:00）
- HATEOAS _links模式 — 始终遵循响应中的链接，不要硬编码路径
- transactionStatus状态码：RCVD（已接收）、ACTC（技术上已接受）、ACSP（已接受结算处理中）、ACCC（已接受信用完成）、RJCT（已拒绝）
- scaStatus状态码：received（已接收）、psuIdentified（用户已识别）、psuAuthenticated（用户已认证）、scaMethodSelected（已选择SCA方法）、finalised（已完成）、failed（失败）
