결제 연동 릴리스: API, 웹훅, 정산 리포트까지 버전 관리하기

재무 담당자가 정산 다운로드 파일에 유용한 열 하나를 추가했습니다. 다음 날 아침, 자동 대사 프로세스가 수수료를 금액 필드에 기록했습니다. 결제 API 버전은 아무도 바꾸지 않았고 사이트 배포도 없었지만, 돈이 흐르는 프로세스는 이미 바뀌었습니다. 버전 이야기를 시작하기에 좋은 지점입니다. 연동 계약은 결제 요청 엔드포인트 주소보다 훨씬 넓습니다.

변경은 SDK, API 버전, 알림 형식, 계정 설정, 리포트 구성, 그리고 상태값에 대한 여러분의 해석까지 건드릴 수 있습니다. 팀이 애플리케이션 코드만 통제한다면 릴리스의 일부는 팀이 모르는 사이에 일어납니다. 아래에서는 이런 변경을 눈에 보이게 하고 검증할 수 있게 만드는 프로세스를 제안합니다.

데이터에 관한 네 가지 계약

첫 번째 계약은 애플리케이션이 PG사에 무엇을 보내고 어떤 응답을 이해하는가입니다. 두 번째는 어떤 비동기 이벤트를 받아들이고 그 진위를 어떻게 검증하는가입니다. 세 번째는 리포트로 어떤 재무 기록을 받는가입니다. 네 번째는 자사 제품이 이 정보를 근거로 무엇을 결과로 간주하는가입니다. 하나의 계약이 바뀌어도 나머지가 기술적으로 깨지지는 않을 수 있지만, 그 의미는 달라질 수 있습니다.

Stripe는 API 요청의 버전을 지정할 수 있게 하고, 웹훅 엔드포인트의 버전은 별도로 관리합니다. Stripe 버전 관리 규칙. 따라서 "SDK 업데이트 완료"라는 한 줄은 모든 소비자가 기대한 구조를 받고 있다는 증거가 되지 못합니다. 저장소의 의존성 버전만이 아니라 채널별로 실제 적용 중인 설정을 기록해 두세요.

Adyen은 호환 가능한 변경과 새 API 버전이 필요한 변경을 구분하며, 라이브러리 버전에는 별도의 체계가 있습니다. Adyen 규칙. 정확한 계약 내용은 공급사 문서에서 직접 확인해야 합니다. 허용된 새 필드가 추가되는 것과 기존 필드의 값이 바뀌는 것은 여러분의 핸들러에 서로 다른 결과를 가져옵니다.

처음 보는 값은 반드시 드러나야 한다

학습용 시스템의 parser는 세 가지 상태를 이해합니다. 그런데 네 번째 상태가 들어옵니다. 위험한 선택지 하나는 프로세스가 멈추지 않도록 이를 성공으로 분류하는 것입니다. 또 다른 위험한 선택지는 해당 행을 버리고 재무팀에 "깨끗한" 리포트를 넘기는 것입니다. 제안하는 정책은 허용된 범위 안에서 기록을 보존하고, 지원하지 않는 값임을 표시한 뒤, 자동으로 재무적 효과를 내지 않은 채 검토 대기열로 보내는 것입니다.

선택 항목인 미지의 필드라면 처리 방식이 다를 수 있습니다. 문서화된 계약에 부합한다면 해당 필드를 정상적으로 무시해도 됩니다. 그래서 "새 필드가 오면 무조건 실패" 규칙도 지나치게 거칠습니다. 구조 확장, 미지의 비즈니스 상태, 필수 필드 누락, 금액 형식 변경을 구분하세요. 각각에 별도의 테스트가 필요합니다.

재무 CSV도 API다

Adyen은 리포트의 열 구성과 순서를 바꾸면 자동 처리에 영향을 줄 수 있다고 명시적으로 경고합니다. Payment accounting report 열 설정. 관리자 화면에서 마우스로 바꾸는 설정이라도 통제 대상 연동의 일부로 다루세요.

파서는 "금액은 항상 여덟 번째 열"이라는 가정에 기대지 말고, 기대하는 헤더와 필수 필드를 검사하는 편이 좋습니다. 추가로 통화, 부호, 단위, 레코드 수, 그리고 제공되는 경우 체크섬도 확인하세요. 헤더가 맞아도 필드의 의미가 바뀌는 것까지 막아 주지는 못하므로, 허용된 테스트 세트 안에 실제 레코드 유형의 샘플이 있어야 합니다.

리포트 담당자는 어떤 시스템이 그 리포트를 읽는지 알고 있어야 합니다. 변경 전에 샘플을 준비하고, 소비 시스템을 점검하고, 전환 시점을 합의하세요. 제품이 지원한다면 이전 설정을 보존해 두세요. 비호환성을 숨긴 채 재무팀에 매일 아침 열 순서를 손으로 바꿔 달라고 부탁해서는 안 됩니다.

리허설과 롤백의 경계

인위적으로 만든 예시나 허용된 비식별 예시로 작은 세트를 구성하세요. 승인, 거절, 부분 환불, 보류, 늦게 도착한 이벤트, 미지의 상태가 들어가야 합니다. 외부로 나가는 재무 처리 없이 이 세트를 기존 파서와 새 파서로 각각 돌려 보세요. 업로드 성공 여부만이 아니라 최종 채무, 금액, 예외 대기열까지 비교해야 합니다.

병행 계산이 가능하다면 새 버전은 먼저 관찰 모드로 결과만 계산하고, 실제 출금이나 지급은 실행하지 않습니다. 적용 범위를 넓히기 전에 두 버전 간 차이를 모두 설명할 수 있어야 합니다. 중단 조건도 정해 두세요. 누락된 레코드, 잘못된 통화, 설명되지 않는 금액, 주문 이행 가능 여부의 변화 같은 것들입니다.

코드 롤백은 이미 생성된 환불을 취소하지 않으며, 관리자 화면의 예전 설정을 자동으로 되돌리지도 않습니다. 변경되는 구성 요소마다 되돌리는 방법, 그 제약, 그리고 이미 처리된 거래에 대한 조치를 명시하세요. 되돌리는 경로가 지원되지 않는다면, 계획서는 마법 같은 버튼을 약속할 것이 아니라 앞으로 고쳐 나가는 방식을 솔직하게 적어야 합니다.

업데이트 종료는 첫 HTTP 200이 아니라, 리포트와 대사를 포함해 영향을 받는 첫 번째 전체 주기를 마친 뒤에 선언하는 것이 맞습니다. 그 결과 팀에는 짧은 변경 이력서가 남습니다. 무엇이 바뀌었는지, 어떤 결과를 비교했는지, 누가 확대 적용을 승인했는지, 앞으로 무엇을 더 지켜봐야 하는지입니다.