하나Pay 卡片、二维码与账单数据 API
하나Pay(하나카드) 是韩国发卡机构 Hana Card(하나카드,韩亚金融集团信用卡子公司)面向持卡人的官方 Android 应用。用户用 PIN、指纹(FIDO)或 OneSign 人脸登录后,首页一屏展示卡面价值、剩余额度和当月权益;二维码与条码支付可跳过二次 PIN,主屏小组件或摇一摇即可唤起付款码,同一会话还能查询关联的韩亚银行账户并汇款。离线 MST 与 HCE 覆盖 Samsung Pay 与 Android 感应支付,境外 Visa / Mastercard / 银联二维码与 ZeroPay、T-money 并列,Hana Members 积分、MyData 资产连接、自制卡面和聊天机器人补全产品。应用只在韩国上架,Google Play 评分 4.7,约 27.4 万条评价,安装量超过 1000 万,与 Shinhan pLay、KB Pay、Samsung Card、Hyundai Card 争夺同一批国内卡包。
登录后的 CRD_LIST 把每张卡的 CRD_NO_HASH 钉在可用积分 U_PSB_PT 和虚拟账户 VT_ACNO 旁边。主屏小组件再用 EST_PAY_AMOUNT / EST_PAY_DT 给出预估账单,开放银行跳转则返回韩元现金 AC_BAL_AMT。
二维码解析得到收款账户 ACCTID、金额 AMOUNT 和商户 NAME;HCE 与 MST 签发 ENCRYPTED_TOKEN 和 TRACK2_DATA。境外流水带 APRNO / WC_APR_AM,银联卡用 upi_token_yn 标记令牌,Hana Members SSO 交回 oAuthKey 与 PTR_POINT。资金、收银和忠诚度栈吃这些字段;openData Studio 把它们做成可调用的开放数据。
应用截图
API 端点一览
以下端点与请求/响应示例均依据应用界面推导重构,为示意说明,并非实际抓包。
Issac 公钥引导
POST
/v1/hanapay/device/keysopendata把 HANACARDMOBILE 设备证书和 Issac PUBLIC_KEY 交给应用,之后每一次 PIN、FIDO、nFilter 载荷都靠它们封装。
认证方式: 无需会话。冷启动第一次调用;返回的 HANACARDMOBILE 证书与 PUBLIC_KEY 用来加密后续 PIN 和 FIDO 载荷。
- OS_DV_C
- APP_VER
- DVC
- HANACARDMOBILE
- PUBLIC_KEY
POST /v1/hanapay/device/keys HTTP/1.1 Content-Type: application/json { "OS_DV_C": "A", "APP_VER": "7.7.4", "DVC": "and-hana-8f21" }{ "HANACARDMOBILE": "-----BEGIN CERTIFICATE-----\nMIIB...hana\n-----END CERTIFICATE-----", "PUBLIC_KEY": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." }持卡人登录会话
POST
/v1/hanapay/sessionsosint打开已登录持卡人:脱敏姓名与手机号、加密会员号与卡号、MyData 客户序号,以及解锁二维码、HCE、银联、开放银行和 Hana Money 的功能开关。
认证方式: 用设备密钥引导调用返回的 PUBLIC_KEY 封装 AUTH_PW(PIN)或 FIDO 断言。之后的调用携带下发的会话和 ENC_MBR_ID。
- CST_NM
- CELL_NO
- MBR_ID
- ENC_MBR_ID
- ENC_CNO
- ITG_CNO
- EWLT_CNO
- SEX_DC
- JOIN_DC
- LGN_ST_DV_C
- CST_ST_DV_C
- CRD_LIST
- MYDATA_CST_SEQ
- MYDATA_SYNC_YN
- HANAMONEY_USE_YN
- QR_USE_YN
- HCE_USE_YN
- NFC_PAY_YN
- GTS_UPI_SERVICE_USE_YN
- OB_BN_USE_YN
- AUTH_AUTO_LOGIN_YN
- RES_PAY_TOKEN
- NFILTER_PUBLICKEY
- FIDO_URL
- SERVER_DATE
- SERVER_TIME
POST /v1/hanapay/sessions HTTP/1.1 Content-Type: application/json { "OS_DV_C": "A", "APP_VER": "7.7.4", "AUTH_PW": "nfilter_enc_pin", "FIDO_CTF_US_YN": "Y" }{ "CST_NM": "김하나", "CELL_NO": "01012345678", "MBR_ID": "hana_mbr_8841", "ENC_MBR_ID": "enc_mbr_9f21", "ENC_CNO": "enc_cno_4419", "ITG_CNO": "itg_cno_1204", "EWLT_CNO": "ewlt_8821", "SEX_DC": "M", "JOIN_DC": "20180312", "LGN_ST_DV_C": "1", "CST_ST_DV_C": "00", "CRD_LIST": "[{\"CRD_NM\":\"하나 CLUB SK\",\"CRD_NO_HASH\":\"crd_hash_77a\",\"CRD_MASK_NO\":\"5388-****-****-1234\"}]", "MYDATA_CST_SEQ": "md_seq_3310", "MYDATA_SYNC_YN": "Y", "HANAMONEY_USE_YN": "Y", "QR_USE_YN": "Y", "HCE_USE_YN": "Y", "NFC_PAY_YN": "Y", "GTS_UPI_SERVICE_USE_YN": "Y", "OB_BN_USE_YN": "Y", "AUTH_AUTO_LOGIN_YN": "Y", "RES_PAY_TOKEN": "rpt_hana_7c21", "NFILTER_PUBLICKEY": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "FIDO_URL": "https://fido.example.com", "SERVER_DATE": "20261020", "SERVER_TIME": "104512" }已登记卡包
POST
/v1/hanapay/wallet/cardsopenfinance列出卡包里每一张实体卡与 App 卡:哈希 PAN、品牌、可用积分、虚拟账户,以及额度查询、开放银行余额查询是否打开。
认证方式: 携带登录调用所得会话和 ENC_MBR_ID。
- ALL_CRD_CNT
- REG_CRD_CNT
- SEL_CRD_CNT
- CRD_LIST
- CRD_ID
- CRD_NM
- CRD_NO
- CRD_NO_HASH
- CRD_MASK_NO
- CRD_CD
- CRD_TP
- CRD_OFR_FC
- CD_ST_C
- CARD_LAST
- U_PSB_PT
- VT_ACNO
- OB_ACNT_WIRE_LINK
- LIM_INQ_YN
- AC_BAL_INQ_YN
- MST_USE_YN
- MOBILE_CARD_YN
- CRD_IMG_URL
- ACC_CRD_LIST
- AGNC_CRD_LIST
POST /v1/hanapay/wallet/cards HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "OS_DV_C": "A" }{ "ALL_CRD_CNT": "3", "REG_CRD_CNT": "2", "SEL_CRD_CNT": "1", "CRD_LIST": [ { "CRD_ID": "crd_1204", "CRD_NM": "하나 CLUB SK", "CRD_NO": "538812******1234", "CRD_NO_HASH": "crd_hash_77a", "CRD_MASK_NO": "5388-****-****-1234", "CRD_CD": "HC01", "CRD_TP": "C", "CRD_OFR_FC": "VISA", "CD_ST_C": "00", "CARD_LAST": "1234", "U_PSB_PT": "18420", "VT_ACNO": "110123456789", "OB_ACNT_WIRE_LINK": "oneqpay://account", "LIM_INQ_YN": "Y", "AC_BAL_INQ_YN": "Y", "MST_USE_YN": "Y", "MOBILE_CARD_YN": "Y", "CRD_IMG_URL": "https://cdn.example.com/cards/hc01.png" } ], "ACC_CRD_LIST": [], "AGNC_CRD_LIST": [] }主屏小组件账单快照
POST
/v1/hanapay/widgets/statementopenbanking返回主屏小组件绘制的预估账单金额与还款日,以及精简 CRD_LIST 和最近更新时间。
认证方式: 携带登录调用所得会话。2x2 / 4x1 / 4x2 主屏小组件不打开主界面也会调用。
- EST_PAY_AMOUNT
- EST_PAY_DT
- CRD_LIST
- LGN_ST_DV_C
- CST_ST_DV_C
- JOIN_DC
- MEM_YN
- STP_YN
- ATP_MBG_MBYN
- UD_DTTI
POST /v1/hanapay/widgets/statement HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "OS_DV_C": "A" }{ "EST_PAY_AMOUNT": "428000", "EST_PAY_DT": "20261115", "CRD_LIST": "[{\"CRD_NM\":\"하나 CLUB SK\",\"CRD_NO_HASH\":\"crd_hash_77a\"}]", "LGN_ST_DV_C": "1", "CST_ST_DV_C": "00", "JOIN_DC": "20180312", "MEM_YN": "Y", "STP_YN": "N", "ATP_MBG_MBYN": "Y", "UD_DTTI": "20261020104512" }关联账户开放银行余额
POST
/v1/hanapay/accounts/balanceopenbanking读取绑在卡上的韩亚银行(或其他开放银行)账户韩元余额,以及跳进手机银行的深链 URL。
认证方式: 携带登录调用所得会话。登录载荷里 OB_BN_USE_YN 须为 Y。
- VT_ACNO
- INQ_DC
- AC_BAL_AMT
- TERM_YN
- OB_AC_URL
- OB_AC_POPUP_USE_YN
- OB_AC_POPUP_CONTS
POST /v1/hanapay/accounts/balance HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "VT_ACNO": "110123456789", "INQ_DC": "1" }{ "AC_BAL_AMT": "2534100", "INQ_DC": "1", "TERM_YN": "Y", "OB_AC_URL": "https://bank.example.com/app", "OB_AC_POPUP_USE_YN": "N", "OB_AC_POPUP_CONTS": "" }二维码支付解析
POST
/v1/hanapay/payments/qr/decodeopenbanking把扫到的韩国二维码(ZeroPay / GLN / 商户)解析成收款账户、韩元金额、商户手机、展示名和支付日。
认证方式: 携带登录调用所得会话。由应用内相机扫描商户、ZeroPay 与 GLN 二维码触发。
- QR_RAW
- CRD_NO_HASH
- ACCTID
- AMOUNT
- HPNO
- NAME
- PDATE
POST /v1/hanapay/payments/qr/decode HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "CRD_NO_HASH": "crd_hash_77a", "QR_RAW": "00020101021228...hana" }{ "ACCTID": "110987654321", "AMOUNT": "15800", "HPNO": "01098765432", "NAME": "카페하나", "PDATE": "20261020" }HCE 感应支付令牌
POST
/v1/hanapay/payments/tap/tokenopenbanking签发有时限的 HCE 令牌(加密 + 签名)和 Track2,供 Android 感应支付使用,并带 CA 链和可选韩元授权金额。
认证方式: 携带登录调用所得会话和 PIN/FIDO。由专用的感应支付(HCE)令牌服务处理。
- CRD_NO_HASH
- AUTH_PW
- TP
- CODE
- MSG
- MC_NM
- WC_APR_AM
- DURATION_TIME
- ENCRYPTED_TOKEN
- SIGNED_TOKEN
- TRACK2_DATA
- END_ENTITY_CA
- INTERMEDIATE_CA
POST /v1/hanapay/payments/tap/token HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "CRD_NO_HASH": "crd_hash_77a", "AUTH_PW": "nfilter_enc_pin", "TP": "HCE" }{ "CODE": "0000", "MSG": "OK", "TP": "HCE", "MC_NM": "", "WC_APR_AM": "0", "DURATION_TIME": "90", "ENCRYPTED_TOKEN": "enc_tok_hana_c4e1", "SIGNED_TOKEN": "sig_tok_hana_91ab", "TRACK2_DATA": "5388120012341234D2512", "END_ENTITY_CA": "hana_ee_ca", "INTERMEDIATE_CA": "hana_int_ca" }离线 MST/NFC 支付令牌
POST
/v1/hanapay/payments/offline/tokenopenbanking签发 Samsung Pay / 离线条码界面使用的 MST 磁条或 NFC 令牌,带有效时长和等效 Track2。
认证方式: 携带登录调用所得会话。离线条码 / MST 界面与 Samsung Pay 集成使用。
- CRD_NO_HASH
- DVC
- AUTH_YN
- DURATION_TIME
- ENCRYPTED_TOKEN
- SIGNED_TOKEN
- TRACK2_DATA
- END_ENTITY_CA
- INTERMEDIATE_CA
POST /v1/hanapay/payments/offline/token HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "CRD_NO_HASH": "crd_hash_77a", "DVC": "MST" }{ "AUTH_YN": "Y", "DURATION_TIME": "60", "DVC": "MST", "ENCRYPTED_TOKEN": "enc_mst_hana_22b", "SIGNED_TOKEN": "sig_mst_hana_88c", "TRACK2_DATA": "5388120012341234D2512", "END_ENTITY_CA": "hana_ee_ca", "INTERMEDIATE_CA": "hana_int_ca" }会员积分钱包
POST
/v1/hanapay/membership/pointsopendata返回 Hana Members(及联盟)积分余额 PTR_POINT,以及每张会员卡的卡号、可用标志和卡面。
认证方式: 携带登录调用所得会话。
- EWLT_CNO
- PTR_POINT
- CRD_LIST
- ms_cd_nm
- ms_cdno
- ms_point
- ms_us_yn
- ms_cd_img_ph_nm
POST /v1/hanapay/membership/points HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "EWLT_CNO": "ewlt_8821" }{ "PTR_POINT": "18420", "CRD_LIST": [ { "ms_cd_nm": "하나멤버스", "ms_cdno": "8800-****-****-2211", "ms_point": "18420", "ms_us_yn": "Y", "ewlt_cno": "ewlt_8821", "ms_cd_img_ph_nm": "https://cdn.example.com/cards/hm.png" } ] }境外授权流水
POST
/v1/hanapay/overseas/approvalsopenbanking分页返回境外授权:授权号、商户、韩元金额、外币金额与撤销金额。
认证方式: 携带登录调用所得会话。支撑境外授权列表与支付历史界面。
- CRD_NO_HASH
- SDT
- EDT
- approvalList
- APRNO
- APR_STC
- APR_SYS_PC_DT
- APR_SYS_PC_TI
- APR_SYS_PC_DTTI
- MC_NM
- WC_APR_AM
- BY_AM
- BY_CAN_AM
POST /v1/hanapay/overseas/approvals HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "CRD_NO_HASH": "crd_hash_77a", "SDT": "20260901", "EDT": "20261020" }{ "approvalList": [ { "APRNO": "APR-882199", "APR_STC": "00", "APR_SYS_PC_DT": "20261018", "APR_SYS_PC_TI": "214433", "APR_SYS_PC_DTTI": "20261018214433", "MC_NM": "TOKYO STORE", "WC_APR_AM": "128000", "BY_AM": "12800", "BY_CAN_AM": "0" } ] }境外银联卡列表
POST
/v1/hanapay/overseas/unionpay/cardsopenfinance列出已开通境外银联二维码(GTS UPI)的卡片:哈希 PAN、产品名,以及是否已有银联令牌。
认证方式: 携带登录调用所得会话。GTS_UPI_SERVICE_USE_YN 须为 Y。
- code
- msg
- tp
- card_list_cnt
- cst_nm
- crd_cd
- crd_nm
- crd_no
- crd_no_hash
- crd_ofr_fc
- cd_st_c
- img_ph_nm
- mu_cd_yn
- upi_token_yn
POST /v1/hanapay/overseas/unionpay/cards HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21" }{ "code": "0000", "msg": "OK", "tp": "UPI", "card_list_cnt": "1", "cst_nm": "KIM HANA", "crd_cd": "HC01", "crd_nm": "Hana CLUB SK", "crd_no": "538812******1234", "crd_no_hash": "crd_hash_77a", "crd_ofr_fc": "UPI", "cd_st_c": "00", "img_ph_nm": "https://cdn.example.com/cards/hc01.png", "mu_cd_yn": "N", "upi_token_yn": "Y" }境外模式开通检查
POST
/v1/hanapay/overseas/enrollmentopenfinance检查该设备是否已开通境外支付、Visa / Mastercard 令牌是否已登记,并返回可用卡列表。
认证方式: 携带登录调用所得会话。
- deviceId
- tp
- agYn
- cardCnt
- visaRegCheck
- masterRegCheck
- cardListArray
POST /v1/hanapay/overseas/enrollment HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21", "deviceId": "and-hana-8f21" }{ "tp": "GTS", "agYn": "Y", "cardCnt": "2", "deviceId": "and-hana-8f21", "visaRegCheck": "Y", "masterRegCheck": "Y", "cardListArray": "[{\"crd_nm\":\"Hana CLUB SK\",\"crd_no_hash\":\"crd_hash_77a\"}]" }OpenPay 发卡行目录
POST
/v1/hanapay/issuersopendata列出 OpenPay / 他行卡流程可添加的第三方发卡行:名称、鉴权类型、是否已在 App 内、是否已登记签名。
认证方式: 携带登录调用所得会话。用于添加他行卡(OpenPay)的流程。
- CODE
- MSG
- TP
- PRV_AG_YN
- CDCO_LIST
- CDCO_NM
- CDCO_DC
- CDCO_AUTH_DC
- CDCO_IMG_URL
- CRD_IN_CA
- SIGN_REG_YN
POST /v1/hanapay/issuers HTTP/1.1 Content-Type: application/json { "ENC_MBR_ID": "enc_mbr_9f21" }{ "CODE": "0000", "MSG": "OK", "TP": "OP", "PRV_AG_YN": "Y", "CDCO_LIST": [ { "CDCO_NM": "신한카드", "CDCO_DC": "SH", "CDCO_AUTH_DC": "01", "CDCO_IMG_URL": "https://cdn.example.com/issuers/sh.png", "CRD_IN_CA": "Y", "PRV_AG_YN": "Y", "SIGN_REG_YN": "N" } ] }Hana Members 单点登录
POST
/v1/hanapay/membership/ssoosint把持卡人换进 Hana Members:oAuthKey、会员客户号、邮箱本地部分/域名、停用标志和是否使用 PIN。
认证方式: Hana Card 会话加上 Hana Members 初始化调用下发的 E2E 密钥。
- mebCstNo
- encParam
- oAuthKey
- emlId
- emlDmn
- cstStC
- accStopYn
- cddYn
- reArYn
- usePin
- pswdErrCotiTms
POST /v1/hanapay/membership/sso HTTP/1.1 Content-Type: application/json { "mebCstNo": "hana_mbr_8841", "encParam": "issac_e2e_blob" }{ "oAuthKey": "oauth_hm_7c21", "mebCstNo": "hana_mbr_8841", "emlId": "hana", "emlDmn": "hanamail.net", "cstStC": "00", "accStopYn": "N", "cddYn": "N", "reArYn": "N", "usePin": "Y", "pswdErrCotiTms": "0" }
数据类别
- 卡片
- 余额
- 支付
- 账单
- 会员积分
- 身份
- 开放银行
数据使用场景与案例
卡包对账
记账机器人每晚拉取 CRD_LIST,按 CRD_NO_HASH 对齐发卡文件,并标出 CD_ST_C、CRD_INACT_YN 漂移和 U_PSB_PT 积分变动。
收银与感应确认
门店应用把 HanaPay 二维码解析成 ACCTID / AMOUNT / NAME,再用 HCE 或 MST 令牌的 TRACK2_DATA、WC_APR_AM 对齐 POS 授权。
账单到期资金安排
家庭现金流工具读取小组件快照里的 EST_PAY_AMOUNT、EST_PAY_DT 以及关联账户 AC_BAL_AMT,确保하나카드扣款日前资金到位。
会员积分与 MyData 归户
忠诚度栈把 PTR_POINT、ms_cdno 与 MYDATA_CST_SEQ / mebCstNo 归到同一客户键,让 Hana Members 积分和开放银行资产清单在一起。
常见问题
하나Pay 如何鉴权持卡人?
冷启动先调 POST /v1/hanapay/device/keys 取 HANACARDMOBILE 证书和 Issac PUBLIC_KEY,再在 POST /v1/hanapay/sessions 提交 nFilter 封装的 PIN 或 FIDO 断言。之后的调用携带该会话和 ENC_MBR_ID。Hana Members 另走 POST /v1/hanapay/membership/sso,返回 oAuthKey。
卡包里用哪些字段识别一张卡?
POST /v1/hanapay/wallet/cards 的 CRD_LIST 行含 CRD_ID、CRD_NM、脱敏 CRD_NO、CRD_NO_HASH、CRD_OFR_FC(Visa 等)、积分 U_PSB_PT、虚拟账户 VT_ACNO,以及额度查询、MST、手机卡开关。
除了卡,能读到账单日和银行余额吗?
可以。小组件接口 POST /v1/hanapay/widgets/statement 返回 EST_PAY_AMOUNT 与 EST_PAY_DT;POST /v1/hanapay/accounts/balance 返回绑卡开放银行账户的 AC_BAL_AMT,并带跳进韩亚银行手机端的 OB_AC_URL。
二维码或感应支付会返回什么?
POST /v1/hanapay/payments/qr/decode 解析出 ACCTID、AMOUNT、HPNO、NAME、PDATE。HCE 的 POST /v1/hanapay/payments/tap/token 和离线 MST 的 POST /v1/hanapay/payments/offline/token 签发 ENCRYPTED_TOKEN、SIGNED_TOKEN、TRACK2_DATA 和 DURATION_TIME。
与 하나Pay(하나카드) 相似的应用
- KB Pay — KB Pay 是 KB国民卡(KB국민카드)的 Android 应用,可查询消费、即时还款、申卡,用已登记的卡、银行账户或积分付款,并开通韩国公交地铁的手机交通卡。
- 신한 SOL페이 — 신한 SOL페이 是新韩卡的支付平台,覆盖现场与电脑付款、账单和分卡消费、积分与优惠券,并按消费习惯推荐卡片,没有新韩卡也可以使用。
- 현대카드 — 现代卡(현대카드)应用可办卡、查账,并在线下和海外商户用 App 卡代替实体卡付款,还能在同一应用查看账户、保险、汽车和房产。
- 모니모 — 모니모 是三星卡把三星人寿、三星火灾、三星卡和三星证券收进同一应用的入口,可查三星卡消费、申请保险金并做证券投资。
- 디지로카(롯데카드) — 디지로카 是乐天卡的应用,用来查看支付记录、卡权益和活动,并办理贷款、购车金融、购物优惠券和旅行预订。
- 우리카드 우리WON카드 — 우리WON카드 是友利卡的应用,可查看预计还款额、额度、持卡和近期消费,并申请新卡以及短期或长期卡片贷款。
- NH pay(NH페이) — NH pay 是农协卡的支付应用,可登记农协信用/借记/礼品卡或农协账户,用二维码、条码或 NFC 做线上和现场付款,并查询其他机构的账单。
- 카카오페이 — 카카오페이 是韩国支付应用,可用条码、二维码以及三星支付和 ZeroPay 在店内付款,并在同一应用里转账、管卡管账户、办保险贷款和投资。
相关主题
- 하나페이 api
- 하나카드 api
- hanapay
- 韩国信用卡接口
- 二维码支付
- hana members 积分
- 开放银行 卡片
需要集成这个 App 的数据 API?
我们可为任意指定 App 交付定制集成——源码交付 USD 500 起,或托管 API 按调用计费。告诉我们您需要的数据即可。
- 每个项目均签 NDA 与 SOW
- 3–7 天交付
- 验收通过后才付款
- 仅在授权范围内作业