Toss Payments 연동: 3계층 구조와 에러 처리 전략

// 처음 코드 — UseCase에 외부 API 호출이 섞임
@Service
public class ConfirmPaymentUseCase {
 
    private final RestTemplate restTemplate;
    private final OrderService orderService;
 
    @Transactional
    public ConfirmPaymentResponse execute(final ConfirmPaymentCriteria criteria) {
        final Order order = orderService.validatePayable(
            criteria.getOrderNumber(), criteria.getAmount()
        );
 
        // Toss API 직접 호출
        final HttpHeaders headers = new HttpHeaders();
        final String encoded = Base64.getEncoder()
            .encodeToString(("test_sk_xxx:").getBytes());
        headers.set("Authorization", "Basic " + encoded);
        headers.setContentType(MediaType.APPLICATION_JSON);
 
        final TossConfirmRequest tossRequest = new TossConfirmRequest(
            criteria.getPaymentKey(), criteria.getOrderNumber(), criteria.getAmount()
        );
 
        try {
            final ResponseEntity<TossPaymentsResponse> response = restTemplate.exchange(
                "https://api.tosspayments.com/v1/payments/confirm",
                HttpMethod.POST,
                new HttpEntity<>(tossRequest, headers),
                TossPaymentsResponse.class
            );
            // 결제 성공 처리...
        } catch (final HttpClientErrorException e) {
            // 에러 처리...
        }
    }
}

@Service
@RequiredArgsConstructor
public class ConfirmPaymentUseCase {
 
    private final OrderService orderService;
    private final PaymentInitService paymentInitService;
    private final PaymentResultSaver paymentResultSaver;
    private final TossPaymentsService tossPaymentsService;
 
    @Transactional
    public ConfirmPaymentResponse execute(final ConfirmPaymentCriteria criteria) {
        // ① 주문이 결제 가능한지 검증
        final Order order = orderService.validatePayable(
            criteria.getOrderNumber(), criteria.getAmount()
        );
 
        // ② PG 호출 전에 대기 상태 결제를 먼저 생성
        final Payment pendingPayment = paymentInitService.createPending(
            criteria.toInitCommand(order)
        );
 
        try {
            // ③ Toss Payments API 호출
            final TossPaymentsResponse pgResponse = tossPaymentsService.confirm(
                criteria.toTossRequest()
            );
 
            // ④ 성공 → 주문/결제 상태 업데이트
            return paymentResultSaver.saveSuccess(order, pendingPayment, pgResponse);
 
        } catch (final Exception e) {
            // ⑤ 실패해도 실패 사실을 기록
            paymentResultSaver.saveFailure(order, pendingPayment, e);
            throw e;
        }
    }
}

@Component
@Slf4j
public class TossPaymentsClient {
 
    private <T> T sendRequest(
        final String url,
        final HttpMethod method,
        final Object body,
        final Class<T> responseType,
        final RestTemplate restTemplate
    ) {
        try {
            final ResponseEntity<T> response = restTemplate.exchange(
                url, method, new HttpEntity<>(body), responseType
            );
            return response.getBody();
 
        } catch (final HttpClientErrorException e) {
            // 4xx — Toss가 보내주는 에러 코드를 우리 코드로 매핑
            final TossErrorResponse error = parseError(e.getResponseBodyAsString());
            log.error("Toss 4xx: code={}, message={}", error.getCode(), error.getMessage());
            throw new TossPaymentsException(error.getCode(), error.getMessage());
 
        } catch (final HttpServerErrorException e) {
            // 5xx — PG사 서버 문제. 우리가 할 수 있는 건 없다
            log.error("Toss 5xx: status={}", e.getStatusCode());
            throw new ExternalApiException(ExternalErrorType.SERVER_ERROR);
 
        } catch (final Exception e) {
            // Unknown — 네트워크 장애. 가장 위험한 케이스
            log.error("Toss unknown error", e);
            throw new ExternalApiException(ExternalErrorType.UNKNOWN_ERROR);
        }
    }
}

@Configuration
@RequiredArgsConstructor
public class TossPaymentsRestTemplateConfig {
 
    private final TossPaymentsProps props;
 
    @Bean
    public RestTemplate tossPaymentsRestTemplate() {
        return createRestTemplate(props.getSecretKey());
    }
 
    @Bean
    public RestTemplate tossPaymentKeyInRestTemplate() {
        return createRestTemplate(props.getKeyInSecretKey());
    }
 
    private RestTemplate createRestTemplate(final String secretKey) {
        final RestTemplate restTemplate = new RestTemplate();
        restTemplate.getInterceptors().add((request, body, execution) -> {
            final String encoded = Base64.getEncoder()
                .encodeToString((secretKey + ":").getBytes());
            request.getHeaders().set("Authorization", "Basic " + encoded);
            request.getHeaders().setContentType(MediaType.APPLICATION_JSON);
            return execution.execute(request, body);
        });
        return restTemplate;
    }
}

@Service
@RequiredArgsConstructor
public class TossPaymentsService {
 
    private final TossPaymentsClient client;
    private final TossPaymentDetailMapper detailMapper;
 
    public TossPaymentsResponse confirm(final TossConfirmRequest request) {
        return client.confirmPayment(request);
    }
 
    public PaymentDetail getPaymentDetail(final String paymentKey) {
        final TossPaymentsResponse response = client.getPayment(paymentKey);
        return detailMapper.toPaymentDetail(response);
    }
 
    public void cancel(final String paymentKey, final TossCancelRequest request) {
        client.cancelPayment(paymentKey, request);
    }
}