페이플 결제

Overview

페이플(Payple) 앱카드 결제를 연동한 카드결제 시스템이다. 클라이언트에서 페이플 SDK로 인증을 받고, 서버에서 승인 API를 호출하는 2단계 구조로 동작한다.

핵심 도메인 객체

클래스	역할
`Payment`	결제 금액, 타입, 고객 정보를 담는 결제 엔티티
`PaymentRequest`	결제/환불 요청의 상태를 추적하는 엔티티 (PENDING → APPROVED / DECLINED)
`PayplePaymentMethod`	결제 준비(SDK 설정값 생성)와 승인(API 호출)을 담당
`PaypleRefundMethod`	환불 준비(원본 결제 추적)와 승인(취소 API 호출)을 담당
`PaypleApiClient`	페이플 REST API 통신 (승인, 파트너 인증, 취소)
`PaypleClientConfig`	클라이언트 SDK 호출에 필요한 설정값 DTO

결제 흐름

클라이언트                       서버                          페이플
   │                             │                             │
   │  1. POST /payments          │                             │
   │  (금액, 결제수단)            │                             │
   │ ──────────────────────────> │                             │
   │                             │  PaymentRequest 생성         │
   │                             │  (PENDING, thirdPartyData)  │
   │  PaypleClientConfig 응답    │                             │
   │ <────────────────────────── │                             │
   │                             │                             │
   │  2. PaypleCpayAuthCheck()   │                             │
   │     SDK 호출 (설정값 전달)   │                             │
   │ ──────────────────────────────────────────────────────>   │
   │                             │                             │
   │  PCD_AUTH_KEY, PCD_PAY_REQKEY 콜백                        │
   │ <──────────────────────────────────────────────────────   │
   │                             │                             │
   │  3. PATCH /payments/{id}    │                             │
   │  (token: authKey:reqKey)    │                             │
   │ ──────────────────────────> │                             │
   │                             │  token 저장                  │
   │         OK                  │                             │
   │ <────────────────────────── │                             │
   │                             │                             │
   │  4. POST /v3/orders         │                             │
   │  (주문 생성)                │                             │
   │ ──────────────────────────> │                             │
   │                             │  5. 결제 승인 API 호출       │
   │                             │  (authKey, reqKey)          │
   │                             │ ──────────────────────────> │
   │                             │                             │
   │                             │  승인 결과 응답              │
   │                             │ <────────────────────────── │
   │                             │                             │
   │                             │  PaymentRequest → APPROVED  │
   │       주문 완료 응답         │                             │
   │ <────────────────────────── │                             │

1단계: 결제 준비 (`POST /payments`)

PayplePaymentMethod.prepareWith()가 호출된다.

Payment 엔티티를 기반으로 PaypleClientConfig를 생성한다.
PaymentRequest를 PENDING 상태로 저장한다.
thirdPartyData에 PaypleClientConfig JSON을 저장하여 클라이언트에 반환한다.

2단계: 클라이언트 SDK 인증

클라이언트에서 PaypleCpayAuthCheck() SDK를 호출한다.

thirdPartyData를 파싱하여 SDK 설정값으로 사용
SPA인 경우 callbackFunction을 추가하여 SDK 호출
SDK 인증 완료 시 PCD_AUTH_KEY와 PCD_PAY_REQKEY를 콜백으로 수신

3단계: 토큰 전달 (`PATCH /payments/{paymentId}`)

클라이언트가 인증 결과를 서버에 전달한다.

token 형식: {PCD_AUTH_KEY}:{PCD_PAY_REQKEY}
PaymentRequest.approveByCustomer(token) 호출로 토큰만 저장
이 단계에서는 실제 결제 승인이 일어나지 않는다

4~5단계: 주문 생성 및 결제 승인

주문 생성(POST /v3/orders) 시 서버가 자동으로 결제를 승인한다.

PayplePaymentMethod.approve()가 호출되면:

PaymentRequest에서 저장된 토큰을 :로 분리하여 authKey와 reqKey를 추출
PaypleApiClient.approve(authKey, reqKey) 호출
페이플 API에서 payRst == "success" 응답 시 PaymentRequest를 APPROVED로 전환
실패 시 PaymentRequestException(APPROVAL_FAILURE) 발생

결제 취소(환불) 흐름

클라이언트                       서버                          페이플
   │                             │                             │
   │  1. DELETE /v3/orders/{id}  │                             │
   │ ──────────────────────────> │                             │
   │                             │  2. 환불 준비                │
   │                             │  원본 PaymentRequest 조회    │
   │                             │  REFUND PaymentRequest 생성  │
   │                             │                             │
   │                             │  3. 파트너 인증              │
   │                             │ ──────────────────────────> │
   │                             │  authKey 응답               │
   │                             │ <────────────────────────── │
   │                             │                             │
   │                             │  4. 결제 취소 API 호출       │
   │                             │  (payOid, payDate, 환불금액) │
   │                             │ ──────────────────────────> │
   │                             │  취소 결과 응답              │
   │                             │ <────────────────────────── │
   │                             │                             │
   │                             │  PaymentRequest → APPROVED  │
   │       취소 완료 응답         │                             │
   │ <────────────────────────── │                             │

1단계: 주문 취소 요청

클라이언트가 DELETE /v3/orders/{orderId}를 호출하면 서버가 환불 프로세스를 시작한다.

2단계: 환불 준비

PaypleRefundMethod.prepareWith()가 호출된다.

Payment.originalPaymentId로 원본 PaymentRequest를 조회
원본의 referenceId를 복사하여 REFUND 타입의 PaymentRequest를 생성
원본 결제가 존재하지 않으면 PaymentRequestException 발생

3~4단계: 환불 승인

PaypleRefundMethod.approve()가 호출된다.

환불 PaymentRequest의 referenceId로 원본 PAY 요청을 조회
원본 결제의 updatedAt (또는 createdAt)에서 결제 일자를 yyyyMMdd 형식으로 추출
PaypleApiClient가 파트너 인증 후 취소 API를 호출:
- payOid: 원본 결제의 referenceId
- payDate: 원본 결제 일자
- refundTotal: 환불 금액
성공 시 PaymentRequest를 APPROVED로 전환

PaymentRequest 상태 흐름

PENDING ──(approve)──> APPROVED
   │
   └───(decline)──> DECLINED

PENDING: 결제/환불 요청 생성 직후
APPROVED: 결제사 API 승인 완료
DECLINED: 승인 거절

설정

결제 대행 설정값은 payment-gateway.yml에서 관리한다.