토스페이먼츠 버전 2022-11-16이 나왔어요! 약 4개월 만의 버전 업데이트인 만큼 많은 변화가 있는데요, 어떤 변화가 왜 있었는지 알려드려요.
숫자 기관 코드
이번 릴리즈에 가장 큰 변화는 은행, 카드사 필드에 있어요. 필드 값의 한글·영어 코드를 숫자 코드로 대체했어요.
왜 숫자 코드를 사용해요?
1️⃣ 응답 일관성
API의 Accept-Language 헤더, 브라우저 환경에 따라 응답이 한글 또는 영어로 왔어요. 응답 언어를 예측하기 어려워서 상점에서 두 언어를 모두 대응해야 하는 불편함이 있었어요. 상점에서 API 응답을 더 쉽게 대응할 수 있도록 다국어 환경에서 일관성 있게 돌아오는 숫자 코드를 사용하기로 했어요.
2️⃣ 기관 코드 관리
제일은행을 기억하시나요? 외환위기 이후 SC제일은행이 되었죠. 은행이나 카드사 이름은 언제든 바뀔 수 있는데, 한글·영어 코드는 한 번 설정하면 토스페이먼츠에서 변경하기 어려워요. 토스페이먼츠에서 변경을 못 하면 상점에서도 구식 이름을 써야하는 불편함이 있죠. 그래서 이름 변화가 있어도 유지보수 없이 계속 사용할 수 있는 숫자 코드를 도입했어요.
이런 이유로 응답 객체는 숫자 코드만 사용해요! 요청은 숫자·한글·영어 코드를 지원하지만 숫자 코드 사용을 권장해요.
✅ 어떤 필드가 바뀌었는지 알고 싶으면 릴리즈 노트를 참고하세요.
카드사 구분
카드사 필드에는 숫자 코드 외에 다른 변화도 있어요. 바로 발급사, 매입사가 구분된다는 점이에요.
발급사, 매입사가 뭐예요?
발급사는 우리가 일반적으로 생각하는 카드사에요. 카드에 새겨져있는 브랜드에요. 발급사의 주 업무는 카드사 회원 관리에요.
매입사는 카드가 사용된 후 매출 전표를 매입하고 가맹점에 대금을 입금해줘요. 즉, 카드 거래를 처리할 수 있는 시스템을 갖추고 실제 카드사로서의 역할을 수행하는 곳이죠. 국내 매입사는 현대, 농협, 비씨, 삼성, 롯데, 신한, 국민, 하나 총 8개사가 있어요. 발급사가 여러 곳이어도 매입은 이 8개사에서만 해요.
매입사를 왜 알아야 해요?
토스페이먼츠를 이용하는 상점이 많아지면서 요구사항도 더 다양해졌어요. 매입사 프로모션 혜택을 제공하는 상점도 있고, 매입사별로 정산하는 상점도 있어요. 이런 요구로 이번 버전부터 매입사 정보도 제공해요. 더 많은 상점이 저희와 함께 성장할 수 있도록 계속 발전하고 있어요!
✅ 어떤 필드가 바뀌었는지 알고 싶으면 릴리즈 노트를 참고하세요.
브랜드페이 약관 파라미터 변경
브랜드페이에는 총 4개의 약관 항목이 있어요. 회원가입, 카드, 계좌, 자동결제 이용 약관이에요.
각 약관 동의는 고객이 해당 서비스를 사용할 때 받아야 해요. 예를 들어 고객이 브랜드페이로 카드 결제를 해요. 그럼 브랜드페이 회원가입 약관, 카드 결제 약관에 고객 동의를 받은 이후 결제를 진행해요.
브랜드페이 API
그래서 미동의 약관 조회 API, 약관 동의 API에 약관 항목을 지정할 수 있는 scope 파라미터를 추가했어요. scope 에는 배열로 1개 또는 2개의 약관 항목을 설정할 수 있어요. 2개의 항목을 설정할 때는 반드시 아래와 같이 회원가입 + 결제 수단의 조합이어야 해요.
회원가입 + 카드: ['REGISTER', 'CARD']
회원가입 + 계좌: ['REGISTER', 'ACCOUNT']
회원가입 + 빌링: ['REGISTER', 'BILLING']예를 들어 브랜드페이를 처음 사용하는 고객이 계좌 결제를 한다면 약관 동의 API로 회원가입, 계좌 결제 이용 약관 동의를 한 번에 받으세요. 추후에 같은 고객이 카드 결제를 하고 싶다면 scope 파라미터에 CARD 를 설정해서 카드 결제 이용 약관 동의를 받아요.
✅ 더 자세한 내용은 약관 동의 API를 참고하세요.
브랜드페이 SDK
API만 바뀌면 섭섭하죠? 약관 동의를 요청하는 requestAgreement() SDK 메서드에 파라미터가 추가되었어요. 회원가입, 카드, 계좌, 빌링 파라미터를 사용할 수 있어요. SDK는 파라미터를 하나씩 넣어 사용하세요.
✅ 사용 예시는 브랜드페이 SDK를 참고하세요.
대신 사용하세요
위 세 가지 변화 외에도 제거된 필드, 파라미터가 있어요.
- Payment 객체의
transactionKey필드가 제거됐어요. lastTransactionKey 필드를 사용하세요. 필드 값을 더 직관적으로 나타내는 필드 이름으로 바뀌었어요. - Payment 객체의
cancels.taxAmount필드가 제거됐어요. cancels.taxFreeAmount 필드가 비과세 금액으로 판단되기 때문에taxAmount를 사용하지 않았어요. - 가상계좌 SDK의 requestPayment() 메서드, 가상계좌 발급 API에서 사용되었던
virtualAccountCallbackUrl파라미터가 제거됐어요. 앞으로 가상계좌 입금 알림은 웹훅으로 받아보세요.
토스페이먼츠 Twitter를 팔로우하시면 더욱 빠르게 블로그 업데이트 소식을 만나보실 수 있어요.
