카카오페이·Fiserv 저장결제 등록 API 명세 맞추기

Payment Expansion · Series 2 · Integration Rollout3 / 14Backend

서로 다른 등록 과정을 공통 API로 제공하면서 성공·실패·취소와 결과가 돌아오지 않는 경우를 정리한 경험을 설명합니다.

저장결제 관리 서비스에 카카오페이와 Fiserv Billkey 등록을 추가하면서, 같은 등록 기능이라도 진행 과정과 결과를 받는 방식이 다르다는 문제를 만났습니다. 프론트엔드는 하나의 등록 API를 사용하더라도 그 차이를 처리할 수 있어야 했습니다.

요청·응답 형식과 상태, 필수 값, 오류 처리 등을 API 명세로 정리했습니다. API를 호출하는 쪽과 제공하는 쪽이 같은 규칙으로 처리하도록 맞추는 작업이었습니다.

등록 요청과 등록 완료의 차이

등록을 시작했다는 응답과 사용할 수 있는 결제수단이 저장됐다는 결과는 다릅니다. 카카오페이는 사용자가 앱에서 인증을 마치는 과정이 있어 요청 직후 등록 성공으로 처리할 수 없었습니다.

Fiserv Billkey 지원을 추가할 때도 저장결제 관리 서비스와 결제 연동 서비스를 함께 수정했습니다. 어느 단계에서 등록 정보를 만들고, 이후 어느 서비스가 그 결과를 사용하는지 맞춰야 했습니다.

카카오페이 등록 성공 시 정보를 저장하는 흐름을 먼저 만들고, 취소와 실패 시의 후속 호출도 정리했습니다. 고객이 등록을 중단한 것과 시스템 오류로 등록하지 못한 것은 화면에서 안내할 내용과 이후 처리도 달랐습니다.

상위 API에서 같은 상태 이름을 사용하더라도 벤더별로 어떤 결과에 해당하는지 확인해야 했습니다. 요청을 접수했다는 응답을 등록 완료로 해석하면 실제로 사용할 수 없는 결제수단을 보여줄 수 있습니다.

앱을 열었다가 인증을 마치지 않고 닫거나, 사용할 결제정보가 없어 중간에 이탈하는 경우도 있었습니다. 고객이 취소해도 기대한 취소 콜백이 항상 도착하는 것은 아니었습니다.

응답이 없다는 이유만으로 고객의 취소라고 확정할 수는 없습니다. 등록 결과를 기다리는 상태를 언제까지 유지할지와 이후 처리 방법을 함께 정해야 했습니다. 성공·실패·취소 응답만 나열한 명세로는 이런 상황을 설명하기 어려웠습니다.

웹, 모바일 웹, Android, iOS 팀은 미국에 있었고 국내 간편결제를 직접 검증하기 어려운 경우가 있었습니다. 그래서 초반에는 API 명세를 기준으로 화면과 상태 처리를 구현하는 비중이 컸습니다.

결과적으로 등록 API는 요청·응답 필드뿐 아니라 등록 시작, 저장 완료, 취소·실패를 화면에서 어떻게 처리할지까지 함께 맞추는 작업이 됐습니다. 이를 명세로 정리해 실제 결제 테스트가 어려운 팀도 화면 구현을 이어갈 수 있도록 했습니다.

응답이 오지 않는 경우까지 성공·실패·취소 중 하나로 단정할 수는 없었습니다. 명세를 맞춘 뒤에도 실제 앱에서 인증 후 돌아오고 결과를 표시하는 과정은 별도로 확인해야 했습니다.

다음 글에서는 이 등록 과정에서 발생한 WebView 리다이렉트의 POST·GET 문제를 다룹니다.