Stripe Shared Payment Tokens: five wire shapes I only found by shipping

개요

Stripe Shared Payment Tokens (SPT) 미리보기 API에서 문서화되지 않은 5가지 응답 형식이 실제 테스트 모드 응답을 통해 수집되었으며, 이는 에이전트 상거래의 지출 한도가 포함된 토큰 사용 시 발생할 수 있는 오류 및 예상치 못한 시나리오를 보여줍니다.

주요 내용

* HTTP 402 오류 처리: 카드 거절 시 Stripe는 HTTP 402 응답을 반환하며, PaymentIntent는 오류 본문에 중첩됩니다. 클라이언트가 비-2xx 응답을 전송 실패로 처리할 경우, 거절 정보가 손실될 수 있습니다. 해결책은 오류 봉투를 결과로 변환하고 나머지는 다시 발생시키는 것입니다. decline_code를 사용하여 실제 거절 이유를 파악하는 것이 중요합니다.
* 200 응답이 항상 성공은 아님: pm_card_authenticationRequired 카드를 가진 토큰을 충전할 때, status: "requires_action"과 함께 빈 shared_payment_token_action 페이로드가 반환될 수 있습니다. 이는 3D Secure 인증을 의미하며, 판매자 측에서는 아무런 금액도 받지 못했음을 나타냅니다. 성공은 status === "succeeded"인 경우로만 간주해야 합니다.
* 토큰 소비 후 payment_method_details 정보 손실: 토큰이 사용되면 카드 브랜드와 같은 payment_method_details 정보가 null이 됩니다. 영수증에 카드 정보를 표시하려면 토큰 부여 시점에 해당 정보를 기록해야 합니다. 부분 캡처도 토큰을 소비합니다.
* amount_captured 필드 형식 불일치: usage_limits의 max_amount는 정수이지만, usage_details의 amount_captured는 { currency, value } 객체입니다. 이 둘을 직접 비교하면 오류 없이 잘못된 결과가 나올 수 있습니다.
* 부여된 토큰(Granted Token)과 발행된 토큰(Issued Token)의 차이: 발행된 토큰에는 status 필드가 있지만, 부여된 토큰에는 status 필드와 next_action 필드가 없습니다. 따라서 판매자가 부여된 토큰에서 requires_action 상태를 읽으려고 하면 상태를 알 수 없습니다.
* 제한된 엔드포인트 및 웹훅: 부여된 토큰에 대한 목록 엔드포인트는 존재하지 않으며, ID로만 검색 가능합니다. shared_payment.granted_token.deactivated라는 단일 웹훅 이벤트만 존재하며, 비활성화 이유는 deactivated_reason 필드에 포함됩니다.
* rkcs_test_ 샌드박스 키 문제: 샌드박스 키의 403 "does not have access to this endpoint" 오류는 지역별 제한보다는 키 자체의 문제일 가능성이 높습니다.

시사점

Stripe Shared Payment Tokens 미리보기 API의 예상치 못한 응답 형식과 동작은 프로덕션 환경에서 발생할 수 있는 잠재적인 오류를 파악하고, 견고한 시스템 구축을 위해 실제 응답을 기반으로 테스트 케이스를 작성하는 것이 중요함을 시사합니다.