오픈뱅킹 API를 직접 붙여보면 보이는 것들 — OAuth·FAPI·동의 관리

오픈뱅킹(Open Banking)은 금융기관이 표준화된 API를 통해 고객 동의를 기반으로 데이터를 공개하고 결제 기능을 제3자에게 제공하는 체계다. PSD2·UK OBIE 같은 해외 규제와 국내 공동망 확산에 따라 은행-핀테크-머천트 간 연동 효율과 보안 수준을 동시에 끌어올리려는 시도이며, API Economy 맥락에서 금융 서비스의 조합 가능성과 고객 경험 개선의 핵심 인프라로 자리 잡았다.

누가 무엇을 주고받는가

오픈뱅킹은 인증·인가를 거친 제3자(핀테크, 머천트, 금융 플랫폼)에게 고객 동의 범위 내에서 계좌정보 조회 및 결제지시 기능을 제공하는 표준 API 체계다. 핵심 역할자는 ASPSP(은행, 계정 서비스 제공자), TPP(제3자 제공자 — AISP는 계정정보, PISP는 결제지시), 고객(데이터 주체), 규제기관·표준기구로 나뉜다. 기술 표준은 OAuth 2.0/OIDC, FAPI(Financial-grade API), mTLS, JWS/JWE, PAR/JAR, ISO 20022 메시징으로 구성되고, 데이터 모델·동의 스코프·보안 프로파일의 상호운용성을 확보하는 것이 목표다. 동의·거버넌스는 목적·범위·기간·철회가 가능한 세분 동의 관리, Auditability, 데이터 최소수집 원칙을 요구하며 지역별 규제 준수 사항이 상이해 최신 정보 확인이 필요하다.

인증은 FAPI 프로필이 기준선이다

OAuth 2.0 Authorization Code + PKCE와 OIDC 토큰으로 사용자 인증과 세션 안전성을 확보한다. FAPI 프로파일은 토큰 발급·검증 시 JWS 서명과 mTLS 적용을 요구하고, PAR/JAR는 요청 파라미터 변조를 방지해 피싱을 저감한다. SCA(Strong Customer Authentication) 도입으로 결제 보안을 강화하는 것도 이 계층의 역할이다.

동의는 스코프 단위로 쪼개서 관리한다

데이터 항목·결제한도·유효기간·재동의 정책을 스코프 단위로 관리하고, 동의가 철회되거나 만료되면 접근을 자동 차단한다. 감사 추적 로그와 사용자 투명성 포털을 함께 제공해야 신뢰성이 확보된다.

데이터 모델과 메시징은 표준을 따른다

계좌, 거래내역, 수취인, 결제 상태 등 공통 리소스 스키마를 정의하고, 페이징·정렬·증분 동기화를 위한 커서·타임라인 모델을 제공한다. ISO 20022 기반 결제 메시지와 웹훅 이벤트 모델이 상태 전파의 일관성을 담당한다.

결제지시는 상태 머신으로 다룬다

결제지시(PISP) 요청은 idempotency key로 멱등 처리해 중복 결제를 방지한다. 상태는 생성 → 승인대기(SCA) → 처리중 → 완료/실패로 전이하며, 트랜잭션 경계와 잠금 정책을 정의해 정합성과 이중지불 방지를 함께 챙긴다.

운영·보안 거버넌스 측면에서는 레이트리밋·스로틀링·WAF·봇 탐지로 남용을 막고, 키·인증서를 정기적으로 순환하며 토큰 수명을 최소화한다. 분산 트레이싱과 동의·API 호출 단위 APM·지표 대시보드로 관측성을 확보하고, 규제 준수와 침해 대응 시나리오를 내재화해야 한다.

결제 요청 하나가 지나는 경로

⤢✕

전체 흐름은 동의 생성 → 토큰 발급 → API 호출 → 결과 반환 순이다. SCA 실패, 토큰 만료, 동의 철회 시에는 재인증·재동의로 분기 처리한다. 결제 전용 테이블 락 또는 분산 락으로 중복 실행을 막고, 멱등 키로 재시도 안정성을 확보한다.

어디에 쓰이는가

계좌 집계·PFM에서는 다중 은행 계좌·카드·대출 데이터를 모아 카테고리 분류와 현금흐름 분석을 자동화하고 맞춤 알림·예산 관리를 제공한다. 결제 지시·계좌이체는 카드 네트워크를 우회하는 계좌기반 결제(Pay by Bank)로 수수료 절감과 결제 승인율 향상을 노린다. 대출·리스크 심사는 트랜잭션 데이터로 상환능력을 추정해 중소기업 캐시플로 대출에 활용하고, 실시간 잔액 확인과 상환 자동이체를 연계한다. 자본시장·자산관리에서는 계좌 보유자 검증과 수취인 화이트리스트, 저축·투자 자동이체, 투자·보험·연금 데이터 결합에 쓰인다. 회계·ERP 연동은 법인계좌 실시간 동기화와 미수·미지급 매칭 자동화, 시재관리 고도화로 이어진다.

스크래핑과 표준 API는 여러 측면에서 갈린다

접근 방식	성능	확장성	일관성	안정성	운영 편의
스크린 스크래핑	낮음: HTML 파싱 오버헤드	낮음: UI 변경에 취약	낮음: 데이터 스키마 가변	낮음: 차단·캡차 영향	낮음: 크리덴셜 보관 리스크
표준 오픈뱅킹 API	높음: 경량 JSON/이벤트	높음: 게이트웨이 수평 확장	높음: 스키마/버전 관리	높음: SLO/재시도/멱등	높음: 키/토큰 수명 관리 표준화

참고할 만한 효과 범위

정량 효과는 도메인·기관별로 상이하지만, 결제 승인율은 1~~3%p 개선되고 카드 대비 수수료는 20~~70% 절감 가능성이 있다. 계좌 집계 실패율은 30~~60% 감소하고 동기화 시간은 50% 단축된다. 전자동의·실시간 검증을 적용하면 온보딩 시간이 30~~80% 단축되는 범위가 제시된다. 정성적으로는 사용자 경험 개선, 데이터 주권·투명성 강화, mTLS·JWS·SCA에 따른 보안성 제고, 감사·규제 대응 용이성 향상, 파트너 생태계 확장이 따라온다.

구축은 규제 정합성부터 시작한다

먼저 면허·등록과 표준·프로파일(FAPI, ISO 20022)을 선택하고 현지 규정의 최신 정보를 확인한다. 데이터 최소수집, 보유기간, 파기 절차도 이 단계에서 정한다. 인증·보안 아키텍처는 OAuth2/OIDC + PKCE, FAPI1/2, mTLS, DPoP를 검토하고 PAR/JAR로 요청 보안을 강화하며, 토큰 수명을 최소화하고 권한별 스코프를 분리하며 키 순환을 자동화한다.

API 설계·일관성 단계에서는 리소스 스키마 버저닝, 커서 기반 페이징, 증분 동기화(since/ETag)를 갖추고 결제 멱등 키·상태 머신·오류 코드 카탈로그를 표준화한다. 안정성·관측성 단계에서는 레이트리밋·슬로우 롤백, 서킷브레이커·백오프 재시도, 분산 트레이싱, 계약 테스트(Consumer-Driven), 합의된 SLO를 갖춘다. 이벤트·동기화 전략에서는 웹훅 서명 검증과 재시도·중복 억제(Idempotency), 폴백 폴링, 메시지 보관·재처리 DLQ를 운영한다. 마지막으로 컨포먼스 스위트, 보안성 평가, 침투 테스트를 거쳐 샌드박스 → 파일럿 → 상용 단계로 전개하고, 카나리 배포·A/B 실험으로 실패 반경을 최소화한다.

샌드박스에서 직접 붙여보면

전제는 Python 3.11+, requests 설치, 샌드박스 은행의 client_id/secret 및 발급된 authorization_code 보유이며, 보안 옵션(mTLS, JWS)은 샌드박스에서 비활성화되어 있다고 가정한다.

# pip install requests
import os, uuid, requests

BANK_BASE = "https://sandbox.bank.example.com"
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]
AUTH_CODE = os.environ["AUTH_CODE"]
REDIRECT_URI = "https://app.example.com/callback"

# 1) 토큰 교환
token = requests.post(
    f"{BANK_BASE}/oauth2/token",
    data={
        "grant_type": "authorization_code",
        "code": AUTH_CODE,
        "redirect_uri": REDIRECT_URI,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
    timeout=10,
).json()
access_token = token["access_token"]

# 2) 계좌 목록 조회
accounts = requests.get(
    f"{BANK_BASE}/openbanking/v1/accounts",
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=10,
).json()
print(accounts)

# 3) 결제 지시(멱등 키 포함)
payment = requests.post(
    f"{BANK_BASE}/openbanking/v1/payments",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "amount": {"currency": "KRW", "value": "10000"},
        "debtorAccount": {"iban": "KR00-TEST-ACCOUNT"},
        "creditorAccount": {"iban": "KR00-TEST-PAYEE"},
        "remittanceInfo": "주문번호-12345",
    },
    timeout=10,
).json()
print(payment)

상용 환경에서는 mTLS 클라이언트 인증서, 서명 요청(JWS detached), SCA 리디렉션, PAR/JAR가 필수로 적용된다. 결제 생성 시 X-Idempotency-Key로 재시도 안전성을 확보하는 부분은 샌드박스와 동일하다.

오픈뱅킹은 동의 중심 거버넌스, 멱등·이벤트 기반 처리, 관측성·보안 내재화가 갖춰졌을 때 스크린 스크래핑 대비 일관성·안정성·운영 편의의 우위를 실질적으로 활용할 수 있다. 규제·표준 준수와 운영 자동화를 병행한 단계적 도입이 권장된다.