cable8mm / laravel-portone
Laravel package for PortOne payments.
Requires
- php: ^8.2
- cable8mm/portone-php: ^0.8.0
- illuminate/console: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/queue: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- inertiajs/inertia-laravel: ^2.0
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0 || ^11.0
- orchestra/testbench-dusk: ^10.0 || ^11.0
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.5 || ^12
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.8.0
- v0.7.4
- v0.7.3
- v0.7.2
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.0
- dev-fix-subscription-period-double-charge
- dev-t-049-react-stubs
- dev-add-changing-checkout-force-redirect-flow-in-readme
- dev-fix/mobile-pg-window
- dev-feat/v0.5-app-feedback
- dev-feat/v0.4-app-feedback
- dev-chore/revert-changelog-v0.3.0
- dev-feat/amount-mismatch-auto-cancel
This package is auto-updated.
Last update: 2026-11-17 20:21:11 UTC
README
한국의 PG사 포트원(PortOne) V2 단건 결제, 빌링키 결제와 구독을 위한 Laravel 패키지입니다. Laravel Cashier 스타일의 인터페이스로 어떤 Eloquent 모델에도 결제 기능을 붙일 수 있습니다.
포트원 관리자 콘솔에서 발급받은 API Secret / Store ID / Channel Key / Webhook Secret이 필요합니다. 빌링키 결제와 구독에는 빌링키 발급이 가능한 채널의 Channel Key가 필요합니다.
주요 기능
Billable트레이트로 어떤 모델에도 결제 기능 추가- 결제 사전 생성 (
PENDING), 브라우저 결제 후 검증·확정 (PAID), 웹훅용 결제 ID만으로 확정 - 실결제액이 준비 금액과 다르면 PortOne 결제를 자동 전액 취소 (
AMOUNT_MISMATCH_CANCELLED) - 주문처럼 한 번만 결제되는 모델은 두 번째로 결제된 건을 자동 전액 취소 (
DUPLICATE_CANCELLED) - 전액 / 부분 환불 (
PARTIALLY_CANCELLED/CANCELLED), 콘솔 환불은 취소 웹훅·syncByPaymentId()로 레코드에 반영 - 모델별 결제 내역 조회, PortOne 영수증 URL 저장 (
receipt_url) - 빌링키 발급·확인·삭제와 빌링키로 바로 결제 (
prepareBillingKey()·completeBillingKey()·chargeBillingKey()·deleteBillingKey()), 빌링키는 암호화해 저장 - 빌링키로 기간마다 결제하는 구독 (
subscribe()), 갱신 실패 재시도·만료, 기간 끝 해지 예약·취소, 결제 카드 변경, 구독 이벤트 (portone:charge-subscriptions, v0.8.0) - 포트원 웹훅을 Laravel 이벤트로 수신 (
WebhookReceived), 받은 웹훅을portone_webhooks에 기록하고 같은webhook-id는 한 번만 처리 - 결제 상태가 바뀔 때마다 무엇이 바꿨든 한 번만 발송되는 결제 이벤트 (
PaymentCompleted·PaymentPartiallyRefunded·PaymentRefunded·PaymentAmountMismatched·PaymentDuplicated·PaymentExpired), 빌링키 이벤트 (BillingKeyIssued·BillingKeyDeleted) - 버려진 결제 대기 건을 PortOne에 확인해 만료(
EXPIRED)하고 결과를 이벤트로 알림, 보관 기간 뒤 정리 - 테스트용 가짜 게이트웨이(
FakePaymentGateway)와 서명된 웹훅 도우미, 로컬 웹훅 재전송 명령(portone:webhook-replay) - 수정 가능한 체크아웃·빌링키 등록 출발 파일(뷰·스크립트·컨트롤러·라우트) 발행 (빌링키 등록 화면은 v0.8.0)
- Laravel React 스타터 킷용 Inertia React 체크아웃·빌링키 등록 출발 파일(TSX 페이지·컨트롤러·라우트) 발행 (
portone-stubs-react, v0.7.2, 빌링키 등록 페이지는 v0.8.0) - 출발 파일은 v0.9.0 전까지 카드(
CARD) 결제·카드 등록만 제공합니다. 간편결제(EASY_PAY)는 v0.9.0에서 추가될 예정입니다
요구 사항
- PHP
^8.2 - Laravel 컴포넌트(
illuminate/*)^12.0 || ^13.0 cable8mm/portone-php: ^0.8.0(모든 PortOne API 호출은 이 클라이언트를 통합니다)- 구독: 원자적 잠금(
Cache::lock)을 지원하는 기본 캐시 저장소와 큐 워커·스케줄러(구독) - 프론트엔드 결제창: 애플리케이션에서
@portone/browser-sdk설치 필요 (패키지가 대신 설치하지 않습니다)
설치
composer require cable8mm/laravel-portone
서비스 프로바이더는 자동 등록됩니다 (composer.json의 extra.laravel.providers).
설정
1. 환경 변수
.env에 아래 값을 설정합니다.
PORTONE_API_SECRET= PORTONE_WEBHOOK_SECRET= PORTONE_BASE_URL= PORTONE_WEBHOOK_PATH= PORTONE_STORE_ID= PORTONE_CHANNEL_KEY= PORTONE_BILLING_CHANNEL_KEY= PORTONE_PENDING_EXPIRE_AFTER= PORTONE_EXPIRED_RETENTION_DAYS= PORTONE_WEBHOOK_RETENTION_DAYS= PORTONE_AMOUNT_MISMATCH_CANCEL_REASON= PORTONE_DUPLICATE_CANCEL_REASON= PORTONE_SUBSCRIPTION_RETRY_AFTER=
| 변수 | 설명 | 기본값 |
|---|---|---|
PORTONE_API_SECRET |
포트원 API Secret (결제 조회·취소용) | 없음 (필수) |
PORTONE_WEBHOOK_SECRET |
포트원 웹훅 Secret (웹훅 검증용) | 없음 (필수) |
PORTONE_BASE_URL |
PortOne API 주소 재정의 (비우면 PortOne 기본값 사용) | 없음 |
PORTONE_WEBHOOK_PATH |
웹훅 수신 경로 | portone/webhook |
PORTONE_STORE_ID |
포트원 상점 ID (브라우저 결제창용) | 없음 (필수) |
PORTONE_CHANNEL_KEY |
포트원 채널 키 (브라우저 결제창용) | 없음 (필수) |
PORTONE_BILLING_CHANNEL_KEY |
빌링키 발급이 가능한 포트원 채널 키 (빌링키 등록 스텁용) | 없음 (빌링키 등록 스텁을 쓸 때 필수) |
PORTONE_PENDING_EXPIRE_AFTER |
이 시간(분)보다 오래된 PENDING 결제를 만료 검사 |
1440 (24시간) |
PORTONE_EXPIRED_RETENTION_DAYS |
EXPIRED 결제를 지우기 전까지 보관할 일수 |
90 |
PORTONE_WEBHOOK_RETENTION_DAYS |
처리된 웹훅 기록을 지우기 전까지 보관할 일수 | 90 |
PORTONE_AMOUNT_MISMATCH_CANCEL_REASON |
금액 불일치 자동 취소 때 PortOne에 보낼 취소 사유 | 결제 금액 불일치로 자동 취소 |
PORTONE_DUPLICATE_CANCEL_REASON |
중복 결제 자동 취소 때 PortOne에 보낼 취소 사유 | 중복 결제로 자동 취소 |
PORTONE_SUBSCRIPTION_RETRY_AFTER |
실패한 구독 갱신을 다시 결제하기까지 기다릴 일수, 재시도마다 쉼표로 구분 (마지막 재시도도 실패하면 만료) | 1,3,5 |
2. 설정 / 마이그레이션 발행
php artisan vendor:publish --tag=portone-config php artisan vendor:publish --tag=portone-migrations php artisan migrate
발행되는 설정 파일: config/portone.php
생성되는 테이블:
portone_customers: Billable 모델별customer_id1건 저장portone_payments: 결제 기록 (payment_id전역 유니크, 영수증 URLreceipt_url, 빌링키 결제면billing_key_id, 구독 기간 결제면subscription_id·for_subscription)portone_webhooks: 받은 웹훅 기록 (webhook_id유니크, 웹훅 기록)portone_billing_keys: 빌링키 발급 기록 (issue_id유니크, 빌링키 결제)portone_subscriptions: 구독 기록 (구독)
이미 설치한 앱을 새 버전으로 올릴 때는 업그레이드를 보세요.
업그레이드
v0.7.x에서 v0.8.0으로
v0.8.0은 구독과 빌링키 등록 스텁을 더합니다. 기존 공개 API는 지워지거나 바뀌지 않았지만, 마이그레이션은 반드시 실행해야 합니다. 자세한 내용은 버전별 동작 변경의 v0.8.0 항목에 있습니다.
-
의존성:
cable8mm/portone-php는 v0.7.4부터^0.8.0입니다. v0.7.0~v0.7.3에서 올리면composer update cable8mm/laravel-portone cable8mm/portone-php로 함께 올리세요. 앱이cable8mm/portone-php를 직접^0.7로 고정했다면^0.8.0으로 바꿔야 설치됩니다. -
마이그레이션 3개를 반드시 실행: 새 버전은 결제 레코드를 만들 때
subscription_id·for_subscription을 함께 쓰고, 중복 결제 확인도for_subscription을 읽습니다. 실행하지 않으면 구독을 쓰지 않는 앱도 결제 준비(preparePayment()·chargeBillingKey())가 SQL 오류로 실패하고,allowsOnlyOnePaidPayment()가true인 모델은 결제 확정도 실패합니다.vendor:publish는 앱에 아직 없는 마이그레이션만 복사하므로(마이그레이션) 아래 명령을 그대로 실행하면 됩니다.php artisan vendor:publish --tag=portone-migrations php artisan migrate
마이그레이션 내용 create_portone_subscriptions_table구독 기록 테이블 portone_subscriptions(billing_key_id는portone_billing_keys외래키)add_subscription_to_portone_payments_tableportone_payments.subscription_id(nullable,portone_subscriptions외래키)add_for_subscription_to_portone_payments_tableportone_payments.for_subscription(boolean, 기본값false)기존 결제 레코드는
subscription_id가null,for_subscription이false가 되어 동작이 그대로입니다. -
새 설정 키:
billing_channel_key(PORTONE_BILLING_CHANNEL_KEY, 기본값 없음)와subscription_retry_after(PORTONE_SUBSCRIPTION_RETRY_AFTER, 기본값1,3,5)가 추가되었습니다. 발행한 설정 파일을 고치지 않아도 환경 변수만으로 동작합니다(버전별로 추가된 설정 키). 빌링키 등록 스텁을 쓰면PORTONE_BILLING_CHANNEL_KEY를 설정하세요. 비어 있으면 등록 화면이Error상태이고 버튼이 비활성화됩니다. -
구독을 쓰면 새 명령을 스케줄에 등록: 패키지는 스케줄을 등록하지 않습니다.
portone:charge-subscriptions를 앱의 스케줄러에 넣고 큐 워커를 띄우세요(구독). 구독을 쓰지 않으면 필요 없습니다. -
Billable에 새 메서드:subscribe(),subscriptions()가 추가되었습니다. 모델에 같은 이름의 메서드가 이미 있으면 모델 쪽이 트레이트 메서드를 가려 패키지 동작이 바뀌므로 이름을 바꾸세요. 같은 이름의 메서드가 있는 다른 트레이트와 함께 쓰면 PHP 트레이트 충돌 오류가 납니다. -
빌링키 등록 스텁을 쓰려면 다시 발행: 이미 발행한 컨트롤러·라우트 파일은 앱 것이므로 바뀌지 않습니다.
--force없는vendor:publish는 이미 있는 파일을 건너뛰므로 새 파일(블레이드:billing-key.blade.php·portone-billing-key.js, React:billing-key.tsx)만 복사됩니다. 컨트롤러의 액션 3개(billingKey·prepareBillingKey·billingKeyCompleted)와 라우트 3개(portone.billing-key·.prepare·.completed)는 패키지의stubs/에서 옮겨 붙이세요.--force로 다시 발행하면 고친 컨트롤러·라우트를 덮어씁니다. 빌링키 등록 스텁을 쓰지 않으면 다시 발행하지 않아도 됩니다(빌링키 등록 화면).
다음은 깨지지 않지만 확인할 만한 변경입니다.
- 구독 결제는 중복 결제 규칙에서 빠집니다:
subscribe()의 첫 기간 결제와 갱신 결제는for_subscription이true이고,allowsOnlyOnePaidPayment()가true인 모델에서도 자동 취소되지 않으며 "이미 결제된 건"으로 세지 않습니다(중복 결제 자동 취소). 구독을 쓰지 않으면 동작이 같습니다. deleteBillingKey()의 새 거절:ACTIVE·PAST_DUE구독이 결제하는 빌링키는 PortOne에 요청하지 않고InvalidBillingKeyException으로 거절합니다. 구독을 쓰지 않으면 동작이 같습니다.PaymentOperations::chargeBillingKey()의 새 인자: 기본값이 있는subscriptionId·forSubscription이 추가되었습니다. 기존 호출은 그대로 동작합니다.- 새 결제 이벤트 출처는 없습니다: 구독 결제의 결제 이벤트는 빌링키 결제와 같이
source=charge입니다.
v0.6.x에서 v0.7.0으로
v0.7.0에는 호환성이 깨지는 변경이 있습니다. 아래를 순서대로 확인하세요. 자세한 내용은 버전별 동작 변경의 v0.7.0 항목에 있습니다.
-
의존성:
cable8mm/portone-php가^0.5.0에서^0.7.0으로 올라갔습니다.composer update cable8mm/laravel-portone cable8mm/portone-php로 함께 올리세요. 앱이cable8mm/portone-php를 직접^0.5로 고정했다면^0.7.0으로 바꿔야 설치됩니다. -
마이그레이션 4개를 반드시 실행: 새 버전의 코드는 새 테이블·컬럼을 바로 씁니다. 실행하지 않으면 웹훅 수신(
portone_webhooks), 결제 준비(billing_key_id), 결제 확정·취소 동기화(receipt_url)가 SQL 오류로 실패합니다.php artisan vendor:publish --tag=portone-migrations php artisan migrate
마이그레이션 내용 create_portone_webhooks_table웹훅 기록 테이블 portone_webhooksadd_receipt_url_to_portone_payments_tableportone_payments.receipt_url(nullable)create_portone_billing_keys_table빌링키 기록 테이블 portone_billing_keysadd_billing_key_to_portone_payments_tableportone_payments.billing_key_id(nullable,portone_billing_keys외래키) -
결제 이벤트 교체: 아래 이벤트 클래스가 삭제되었습니다. 리스너를 새 이벤트로 옮기세요.
삭제된 이벤트 대신 쓸 이벤트 PaymentPaidPaymentCompleted(웹훅으로 확정되면source=webhook)PaymentCancelledPaymentRefundedPaymentPartiallyCancelledPaymentPartiallyRefundedPaymentFailed없음. WebhookReceived에서Transaction.Failed를 확인하세요PaymentPaidOnExpiryPaymentCompleted(source=expiry)PaymentAmountMismatchedOnExpiryPaymentAmountMismatched(source=expiry)PaymentWebhookEvent·PaymentExpiryEventPaymentEvent(공통 부모)- 삭제된 웹훅 이벤트의
webhook·webhookId속성은 새 이벤트에 없습니다. 웹훅 내용이 필요하면WebhookReceived를 들으세요. - 새 이벤트는 웹훅이 올 때가 아니라 결제 레코드가 실제로 바뀌어 커밋됐을 때 한 번만 발송됩니다. 이미 반영된 취소의 웹훅,
이미
PAID인 결제의Transaction.Paid웹훅에는 결제 이벤트가 나가지 않습니다.
- 삭제된 웹훅 이벤트의
-
PaymentExpired생성자·부모 변경: 이름은 같지만 부모가PaymentExpiryEvent에서PaymentEvent로 바뀌었고, 생성자가(paymentId, payment, billableType, billableId)에서(payment, source)로 바뀌었습니다.paymentId·billableType·billableId는payment에서 채워지므로 속성 이름으로 읽는 리스너는 그대로 동작하고, 새 속성source가 생겼습니다. 테스트 등에서new PaymentExpired(...)를 위치 인자로 만들던 코드는 고치세요. -
Transaction.Paid웹훅이 결제를 확정: 리스너에서completeByPaymentId()·completePayment()를 부르던 코드는 지우세요. 그대로 둬도 이미PAID인 레코드는 바뀌지 않고 이벤트도 다시 나가지 않습니다. -
WebhookReceived는webhook-id마다 한 번: 이미 처리된webhook-id가 다시 오면200만 응답하고WebhookReceived를 보내지 않습니다. 웹훅 처리(취소 동기화 등)가 실패하면WebhookReceived대신 새 이벤트WebhookFailed가 발송됩니다. 리스너에서webhookId로 직접 중복을 거르던 코드는 지워도 됩니다. -
Billable에 새 메서드:allowsOnlyOnePaidPayment(),prepareBillingKey(),completeBillingKey(),billingKeys(),deleteBillingKey(),chargeBillingKey()가 추가되었습니다. 모델에 같은 이름의 메서드가 이미 있으면 모델 쪽이 트레이트 메서드를 가려 패키지 동작이 바뀌므로 이름을 바꾸세요.allowsOnlyOnePaidPayment()는 일부러 재정의하는 메서드입니다(중복 결제 자동 취소).
다음은 깨지지 않지만 확인할 만한 변경입니다.
- 발행한 체크아웃 컨트롤러: 새 스텁은
DuplicatePaymentException도422로 처리합니다. 구 스텁을 쓰면서allowsOnlyOnePaidPayment()를true로 바꾸면 중복 결제가 처리되지 않은 예외(500)가 되므로,PortOneCheckoutController의complete·completedcatch에 추가하세요. - 새 상태값
DUPLICATE_CANCELLED·DUPLICATE는allowsOnlyOnePaidPayment()가true인 모델에서만 생깁니다. - **
portone:payment --raw**는 빌링키 결제의billingKey값을 가립니다(그 밖의 값은 그대로). PaymentGateway를 직접 구현한 클래스는 바꿀 필요가 없습니다.GatewayPayment의 새 인자receiptUrl을 채우지 않으면receipt_url이 저장되지 않습니다.completeByPaymentId()·syncByPaymentId()에 기본값이 있는source인자가 추가되었습니다. 기존 호출은 그대로 동작합니다.- 새 설정 키
webhook_retention_days·duplicate_cancel_reason은 기본값이 있어 발행한 설정 파일을 고치지 않아도 됩니다(버전별로 추가된 설정 키).
마이그레이션
새 버전에서 마이그레이션이 늘었으면 같은 명령을 다시 실행합니다.
php artisan vendor:publish --tag=portone-migrations php artisan migrate
v0.4.0부터 vendor:publish는 앱의 database/migrations에 이미 있는 마이그레이션을 건너뜁니다.
Laravel은 발행할 때 파일명 앞 날짜를 발행 시각으로 바꾸므로, 날짜를 뺀 이름(예: create_portone_payments_table.php)으로
비교합니다. 새 마이그레이션만 복사되므로 그대로 migrate하면 됩니다.
v0.3.0에서 올리는 경우: v0.3.0의
vendor:publish는 이미 있는create_portone_customers_table·create_portone_payments_table을 새 날짜로 다시 복사했습니다. 그 상태로migrate하다 실패했다면, 새로 복사된 중복 파일(날짜만 다르고 이름이 같은 파일 중 아직 실행되지 않은 것)을 지운 뒤 위 명령을 다시 실행하세요.php artisan migrate:status에서Pending인 것이 중복본입니다.
| 버전 | 추가된 마이그레이션 | 내용 |
|---|---|---|
| v0.3.0 | add_paid_amount_to_portone_payments_table |
paid_amount 컬럼 추가 |
| v0.4.0 | backfill_paid_amount_on_portone_payments_table |
이미 결제된(PAID·PARTIALLY_CANCELLED·CANCELLED) 레코드의 paid_amount를 amount로 채움 |
| v0.7.0 | create_portone_webhooks_table |
웹훅 기록 테이블 portone_webhooks 추가 |
| v0.7.0 | add_receipt_url_to_portone_payments_table |
receipt_url 컬럼 추가 |
| v0.7.0 | create_portone_billing_keys_table |
빌링키 기록 테이블 portone_billing_keys 추가 |
| v0.7.0 | add_billing_key_to_portone_payments_table |
billing_key_id 컬럼(portone_billing_keys 외래키) 추가 |
| v0.8.0 | create_portone_subscriptions_table |
구독 기록 테이블 portone_subscriptions 추가 |
| v0.8.0 | add_subscription_to_portone_payments_table |
subscription_id 컬럼(portone_subscriptions 외래키) 추가 |
| v0.8.0 | add_for_subscription_to_portone_payments_table |
for_subscription 컬럼(기본값 false) 추가 |
버전별로 추가된 설정 키
이미 발행한 config/portone.php에는 새 키가 없습니다. 기본값이 있어 그대로도 동작하지만, 값을 바꾸려면 아래 줄을
config/portone.php에 추가하거나 환경 변수만 설정하세요.
| 버전 | 설정 키 | 환경 변수 | 기본값 |
|---|---|---|---|
| v0.3.0 | amount_mismatch_cancel_reason |
PORTONE_AMOUNT_MISMATCH_CANCEL_REASON |
결제 금액 불일치로 자동 취소 |
| v0.7.0 | webhook_retention_days |
PORTONE_WEBHOOK_RETENTION_DAYS |
90 |
| v0.7.0 | duplicate_cancel_reason |
PORTONE_DUPLICATE_CANCEL_REASON |
중복 결제로 자동 취소 |
| v0.8.0 | billing_channel_key |
PORTONE_BILLING_CHANNEL_KEY |
없음 |
| v0.8.0 | subscription_retry_after |
PORTONE_SUBSCRIPTION_RETRY_AFTER |
1,3,5 |
// config/portone.php (v0.3.0에서 추가) 'amount_mismatch_cancel_reason' => env('PORTONE_AMOUNT_MISMATCH_CANCEL_REASON') ?: '결제 금액 불일치로 자동 취소', // config/portone.php (v0.7.0에서 추가) 'webhook_retention_days' => (int) (env('PORTONE_WEBHOOK_RETENTION_DAYS') ?: 90), 'duplicate_cancel_reason' => env('PORTONE_DUPLICATE_CANCEL_REASON') ?: '중복 결제로 자동 취소', // config/portone.php (v0.8.0에서 추가) 'billing_channel_key' => env('PORTONE_BILLING_CHANNEL_KEY'), 'subscription_retry_after' => env('PORTONE_SUBSCRIPTION_RETRY_AFTER') ?: '1,3,5',
버전별 동작 변경
앱 코드에 영향이 있을 수 있는 변경입니다.
- v0.8.0
- 구독: 새 공개 API
Billable::subscribe()·subscriptions(), 구독 기록 모델Models\Subscription(cancel()·resume()·changeBillingKey()), 새 명령portone:charge-subscriptions와 큐 잡Jobs\ChargeSubscription, 새 이벤트SubscriptionStarted·SubscriptionRenewed·SubscriptionRenewalFailed·SubscriptionExpired·SubscriptionCancelled·SubscriptionResumed·SubscriptionEnded(공통 부모SubscriptionEvent), 새 예외InvalidSubscriptionStatusException, 새 설정 키subscription_retry_after(구독). 마이그레이션을 다시 발행하세요. - 결제 레코드의 새 필드:
subscription_id(구독 기간을 낸 결제면 그 구독),for_subscription(구독 첫 기간·갱신 결제면true, 만들 때 정하고 바꾸지 않음). - 구독 결제의 중복 결제 규칙 제외(동작 변경):
for_subscription이true인 결제는 어느 경로로 확정되든 중복 결제로 취소되지 않고, 다른 결제의 중복 판단에서 "이미 결제된 건"으로 세지 않습니다. 구독을 쓰지 않는 앱은 그대로입니다. deleteBillingKey()의 새 거절(동작 변경):ACTIVE·PAST_DUE구독이 결제하는 빌링키는InvalidBillingKeyException으로 거절합니다(PortOne 요청·기록 변경 없음). PortOne 콘솔 등에서 지운 빌링키의BillingKey.Deleted웹훅은 그대로 기록을DELETED로 바꿉니다.- 빌링키 등록 스텁:
portone-stubs가billing-key.blade.php·portone-billing-key.js를,portone-stubs-react가billing-key.tsx를 더 발행하고, 두 스텁의 컨트롤러·라우트에 빌링키 등록 액션·라우트 3개가 생겼습니다. 새 설정 키billing_channel_key(빌링키 등록 화면). - 출발 파일은 카드 결제·카드 등록만 제공합니다. 간편결제는 v0.9.0에서 추가될 예정입니다.
- 구독: 새 공개 API
- v0.7.4
- 체크아웃 스텁이 로그인 사용자의
name을customer.fullName으로 보냅니다. 의존성:cable8mm/portone-php^0.8.0.
- 체크아웃 스텁이 로그인 사용자의
- v0.7.0
- 웹훅 기록과 중복 무시(동작 변경): 검증된 웹훅은 처리 전에
portone_webhooks에webhook-id별로 기록됩니다. 이미 처리된webhook-id가 다시 오면200만 응답하고 레코드 변경·PortOne 조회·이벤트 발송을 하지 않습니다. 이전에는 같은 웹훅이 다시 올 때마다WebhookReceived가 다시 발송됐습니다. 리스너에서webhookId로 직접 중복을 거르던 코드는 지워도 됩니다. 마이그레이션을 다시 발행하세요. - 새 이벤트
WebhookFailed: 설정 누락이나 PortOne 오류로 웹훅 처리가 실패하면 웹훅 기록을 실패로 표시하고WebhookFailed만 발송한 뒤 요청을 오류로 끝냅니다. PortOne이 다시 보내면 다시 처리합니다. - 결제 이벤트 교체(호환성 깨짐): 결제 상태가 바뀔 때마다 무엇이 바꿨든(브라우저 복귀, 웹훅, 만료 확인, 동기화, 환불, 빌링키 결제) 커밋 뒤 한 번만 발송되는 이벤트로 바뀌었습니다(결제 이벤트). 삭제된 이벤트와 대신 쓸 이벤트는 v0.6.x에서 v0.7.0으로의 표를 보세요. 같은 결제를 브라우저 복귀와 웹훅에서 두 번 처리하지 않도록 직접 막던 코드(잠금, 상태 확인)는 지워도 됩니다.
Transaction.Paid웹훅으로 결제 확정(동작 변경): 패키지가Transaction.Paid웹훅을 받으면completeByPaymentId()와 같은 규칙으로 결제를 확정합니다.PaymentPaid·WebhookReceived리스너에서completeByPaymentId()·completePayment()를 부르던 코드는 지우세요. 그대로 둬도 이미PAID인 레코드는 바뀌지 않고 이벤트도 다시 나가지 않습니다.- 새 상태값
DUPLICATE_CANCELLED·DUPLICATE:allowsOnlyOnePaidPayment()가true인 모델에 이미 결제된 레코드가 있으면 두 번째로 결제된 건은PAID가 되지 않고 자동 전액 취소됩니다(중복 결제 자동 취소). 기본값은false라 기존 모델은 그대로입니다.status로 분기하던 코드는 두 상태를 처리하세요. 새 예외DuplicatePaymentException, 새 설정 키duplicate_cancel_reason. - 처리된 웹훅 기록을 정리하려면
model:prune에Cable8mm\LaravelPortone\Models\Webhook을 추가하세요(웹훅 기록). - 영수증 URL: PortOne 조회를 반영하는 저장(결제 확정, 금액 불일치·중복 결제, 취소 동기화, 빌링키 결제)이 조회의
receiptUrl을receipt_url에 저장합니다(영수증 URL). 테스트에서는FakePaymentGateway::payment(..., receiptUrl: ...)로 지정합니다. - 빌링키 결제: 새 공개 API
prepareBillingKey()·completeBillingKey()·billingKeys()·deleteBillingKey()·chargeBillingKey(), 새 이벤트BillingKeyIssued·BillingKeyDeleted, 새 예외BillingKeyNotFoundException·BillingKeyNotIssuedException·InvalidBillingKeyException, 새 결제 이벤트source값charge,BillingKey.Issued·BillingKey.Deleted웹훅 처리(빌링키 결제). - 의존성:
cable8mm/portone-php^0.7.0.
- 웹훅 기록과 중복 무시(동작 변경): 검증된 웹훅은 처리 전에
- v0.6.0
- 체크아웃 단일 리다이렉트 흐름(동작 변경):
requestPayment에redirectUrl과forceRedirect: true를 넣어 PC·모바일이 같은 흐름으로 동작합니다.prepare응답이 기존checkoutParameters배열에서 브라우저 결제 요청값(storeId,channelKey,paymentId,orderName,totalAmount,redirectUrl,customer,forceRedirect)으로 바뀌었습니다. 스텁 JS는complete라우트를 호출하지 않고, 주문서의 Success 상태는 없어졌습니다. 구 스텁을 발행한 앱은 스텁 5종을 다시 발행하거나,prepare응답 사용처와 완료 처리를 새 흐름에 맞게 고치세요. completed가 복귀 겸용: 실패 복귀(?code=)는 레코드를 건드리지 않고 실패 화면을 보여 줍니다.PENDING·EXPIRED결제는 서버에서 먼저 확정한 뒤 Paid·Failed·404 중 하나로 응답합니다.- 의존성:
cable8mm/portone-php^0.5.0.composer update로 함께 올라갑니다.
- 체크아웃 단일 리다이렉트 흐름(동작 변경):
- v0.5.0
- 취소 웹훅 때 결제 레코드 갱신(동작 변경):
Transaction.Cancelled·Transaction.PartialCancelled웹훅을 받으면 이벤트를 보내기 전에 PortOne에 결제를 조회해status와cancelled_amount를 맞춥니다(CANCELLED·PARTIALLY_CANCELLED, 콘솔에서 취소한AMOUNT_MISMATCH는AMOUNT_MISMATCH_CANCELLED). 이전에는 웹훅이 레코드를 바꾸지 않았습니다. 취소 웹훅을 받아 직접 레코드를 고치던 코드는 지우거나, 이미 맞춰진 레코드를 다시 고치지 않는지 확인하세요. 자세한 규칙은 취소 웹훅과 결제 레코드 동기화. - 취소 웹훅을 처리하려면
PORTONE_API_SECRET이 필요합니다. 조회가 실패하면 웹훅 요청이 오류로 끝나고(이벤트 없음) PortOne이 다시 보냅니다. - 새 이벤트: 만료 확인 잡이 결과마다
PaymentExpired·PaymentPaidOnExpiry·PaymentAmountMismatchedOnExpiry를 보냅니다. 만료 결과를 따로 다시 훑던 스케줄은 이 이벤트로 바꿀 수 있습니다. - 새 공개 API:
PaymentOperations::syncByPaymentId(),GatewayPayment::$cancelledAmount, 테스트용Testing\FakePaymentGateway·Testing\InteractsWithPortOneWebhooks, 로컬 확인용php artisan portone:webhook-replay. - 의존성:
cable8mm/portone-php^0.4.1(웹훅 서명기WebhookSigner),illuminate/http가 추가로 필요합니다.composer update로 함께 올라갑니다. PaymentGateway를 직접 구현한 클래스는 바꿀 필요가 없습니다. 다만cancelledAmount를 채우지 않으면(null) 취소 동기화가 레코드를 바꾸지 않습니다.
- 취소 웹훅 때 결제 레코드 갱신(동작 변경):
- v0.4.0
paid_amount의미 변경: 금액 불일치 때만이 아니라 PAID로 확정하는 모든 경우에 PortOne이 알려 준 실결제액을 저장합니다.PENDING·EXPIRED만null입니다.paid_amount !== null을 "금액 불일치"로 판단하던 코드는status로 바꾸세요.- 새 이벤트: 거래 웹훅이면
WebhookReceived다음에PaymentPaid·PaymentCancelled·PaymentPartiallyCancelled·PaymentFailed중 하나가 추가로 발송됩니다.WebhookReceived는 그대로입니다. 두 이벤트를 모두 들으면 같은 웹훅을 두 번 처리하지 않게 하세요. - 새 공개 API:
PaymentOperations::completeByPaymentId(),PortOneGateway::paymentResponse(),php artisan portone:payment.
- v0.3.0
- 새 상태값
AMOUNT_MISMATCH_CANCELLED·AMOUNT_MISMATCH. 금액 불일치 결제는 PortOne에서 자동 전액 취소됩니다.
- 새 상태값
빠른 시작
아래 순서대로 따라 하면 로그인한 사용자가 브라우저에서 결제하고 서버에서 PAID로 확정하는 화면까지 한 번에 동작합니다. 아직 결제 화면이 없으니 체크아웃 출발 파일(스텁)로 만들고, .env 키만 넣으면 실제 포트원 결제창까지 실행해 볼 수 있습니다.
1. 모델에 Billable 추가
use Cable8mm\LaravelPortone\Concerns\Billable; use Illuminate\Foundation\Auth\User as Authenticatable; class User extends Authenticatable { use Billable; }
2. 체크아웃 화면 설치 (스텁 발행)
결제 화면 출발점이 필요하면 스텁 7종(체크아웃 5종과 v0.8.0의 빌링키 등록 2종)을 발행합니다.
php artisan vendor:publish --tag=portone-stubs
| 발행 파일 | 설명 |
|---|---|
resources/views/portone/checkout.blade.php |
주문서(상품명·금액) + 결제 버튼 + 상태 표시 뷰 |
resources/views/portone/completed.blade.php |
리다이렉트 복귀 화면 (결제 성공 시 주문 완료, 실패 시 실패 안내) |
resources/js/portone-checkout.js |
prepare → requestPayment(forceRedirect) → 리다이렉트 복귀 흐름의 ES 모듈 스크립트 |
resources/views/portone/billing-key.blade.php |
카드 등록 버튼 + 상태 표시 뷰, 리다이렉트 복귀 뒤 등록 결과 화면 (빌링키 등록 화면) |
resources/js/portone-billing-key.js |
prepare → requestIssueBillingKey(forceRedirect) → 리다이렉트 복귀 흐름의 ES 모듈 스크립트 |
app/Http/Controllers/PortOneCheckoutController.php |
show / prepare / complete / completed 액션과 상품 조회 product() (샘플 상품 Order A, 10,000원), 빌링키 등록 액션 billingKey / prepareBillingKey / billingKeyCompleted |
routes/portone.php |
auth 미들웨어의 체크아웃 라우트 4종과 빌링키 등록 라우트 3종 |
발행한 파일을 애플리케이션에 연결합니다.
-
라우트 등록 — 발행된 라우트 파일을 애플리케이션 라우트에 포함합니다.
// routes/web.php require __DIR__.'/portone.php';
-
브라우저 SDK 설치 — 애플리케이션에서 직접 설치합니다 (패키지가 설치하지 않습니다).
npm install @portone/browser-sdk
-
프론트엔드 빌드 — 블레이드가
@vite('resources/js/portone-checkout.js')·@vite('resources/js/portone-billing-key.js')로 발행된 스크립트를 참조합니다. Laravel 기본vite.config.js의input에는 이 파일이 없으므로 엔트리로 추가합니다. 추가하지 않으면npm run dev에서는 동작해도npm run build의 manifest에 없어 프로덕션에서 오류가 납니다.// vite.config.js laravel({ input: [ 'resources/css/app.css', 'resources/js/app.js', 'resources/js/portone-checkout.js', 'resources/js/portone-billing-key.js', ], refresh: true, }),
npm run dev # 개발 서버 (프로덕션은 npm run build)
Inertia React 스텁 (Laravel React 스타터 킷)
Laravel React 스타터 킷(Inertia + React + TypeScript)을 쓰는 애플리케이션은 블레이드 스텁 대신 React 스텁을 발행합니다 (v0.7.2부터).
php artisan vendor:publish --tag=portone-stubs-react
| 발행 파일 | 설명 |
|---|---|
resources/js/pages/portone/checkout.tsx |
블레이드 주문서와 같은 상태(initial·loading·error)와 흐름의 React 페이지 |
resources/js/pages/portone/completed.tsx |
리다이렉트 복귀 화면 (결제 성공 시 주문 완료, 실패 시 실패 안내) |
resources/js/pages/portone/billing-key.tsx |
블레이드 빌링키 등록 화면과 같은 상태·흐름의 React 페이지 (v0.8.0) |
app/Http/Controllers/PortOneCheckoutController.php |
블레이드 스텁과 같은 액션이 뷰 대신 Inertia::render('portone/checkout' | 'portone/completed' | 'portone/billing-key') |
routes/portone.php |
블레이드 스텁과 같은 라우트 파일 |
- 컨트롤러와 라우트는
portone-stubs와 같은 경로에 발행되므로 둘 중 하나만 씁니다. - 애플리케이션에
inertiajs/inertia-laravel,react,@inertiajs/react,@portone/browser-sdk가 있어야 합니다. 스타터 킷에는 앞의 셋이 들어 있으니 SDK만 설치합니다 (npm install @portone/browser-sdk). - 스타터 킷은
resources/js/pages/**/*.tsx를 자동으로 찾으므로vite.config.js에 엔트리를 더할 필요가 없습니다. - 주문서와 빌링키 등록 페이지는
prepare라우트(JSON 응답)에 Inertia 방문이 아닌fetch로 요청하고, 페이지 propcsrfToken을X-CSRF-TOKEN헤더로 보냅니다. - 빌링키 등록 페이지(
billing-key.tsx)는 v0.8.0에서 추가되었습니다. Inertia 페이지는 자기 URL을 들고 다니므로, 복귀 액션은 쿼리의 빌링키로 발급을 확정한 뒤 쿼리 없는 같은 주소로 리다이렉트하고 결과(Issued·Failed)를 세션 플래시로 넘깁니다. 빌링키 값은 페이지 prop과 주소에 남지 않습니다. - React 스텁은 v0.9.0 전까지 카드 결제(
checkout.tsx)와 카드 등록(billing-key.tsx)만 제공합니다.
3. 환경 변수 설정
브라우저 결제창에는 PORTONE_STORE_ID·PORTONE_CHANNEL_KEY가, 서버 검증에는 PORTONE_API_SECRET이 필요합니다. .env에 값을 채웁니다 (전체 항목은 설정 참고).
PORTONE_API_SECRET= PORTONE_STORE_ID= PORTONE_CHANNEL_KEY=
4. 화면 확인
체크아웃 라우트는 auth 미들웨어 뒤에 있으므로 로그인 후 /portone/checkout에 접속합니다. PORTONE_STORE_ID·PORTONE_CHANNEL_KEY가 설정되어 있어야 Start payment 버튼이 활성화되고, 클릭하면 실제 포트원 결제창이 열립니다.
체크아웃 흐름 (단일 리다이렉트 방식: PC·모바일 동일):
- 구매자가
Start payment클릭 →POST portone.checkout.prepare(상품 ID만 전송) →PENDING레코드 생성 @portone/browser-sdk/v2의requestPayment호출 (prepare응답값 +CARD,KRW,redirectUrl,forceRedirect: true, 로그인 사용자name을 담은customer.fullName) → 브라우저가 포트원으로 이동했다가redirectUrl(GET portone.checkout.completed/{paymentId}?paymentId=...)로 복귀- 복귀 시
completed액션이 서버에서 결제를 확정(completePayment)하고 주문 완료 화면을 렌더. 실패 복귀(?code=)나 확정 실패면 실패 화면, 레코드는PENDING유지 - 준비 실패·SDK 호출 실패·결제창을 닫은 뒤 뒤로가기는 주문서의
Error상태로 끝남 - 주문 완료 화면은 내 결제이면서 결제된 적 있는 건(
PAID·PARTIALLY_CANCELLED·CANCELLED)만 보여 주고, 결제 전·알 수 없는 건은404
로컬에서 모바일 흐름을 확인할 때는
redirectUrl이 휴대폰에서 닿는 주소여야 합니다.127.0.0.1대신 ngrok 공개 URL이나 LAN 호스트로 serve하세요.
PC 크롬에서
127.0.0.1·localhost로 띄운 앱을 결제하면, 크롬의 로컬 네트워크 접근 검사(Local Network Access) 때문에 승인 뒤 KCP 결제창이 "결제가 진행중입니다"에서 멈추고redirectUrl로 돌아오지 않을 수 있습니다(크롬 157에서 확인, 결제 자체는PAID). ngrok 공개 URL로 serve하거나, 개발용 크롬을--disable-features=LocalNetworkAccessChecks로 실행하세요. 로컬 주소로 띄울 때만 생기는 현상으로 보이며, 공개 도메인 운영 환경에서는 확인하지 않았습니다.
5. 화면 커스터마이징
발행된 파일은 이제 애플리케이션 것이므로 자유롭게 고칩니다. 주문서(show)와 결제 준비(prepare)는
컨트롤러의 product() 하나에서 상품을 가져옵니다. 주석이 달린 샘플 상품을 데이터베이스 조회로 바꾸면 됩니다.
// app/Http/Controllers/PortOneCheckoutController.php private function product(Request $request): object { // Replace this sample product with your product from the database, // e.g. return Product::findOrFail($request->input('product')); return (object) ['id' => 1, 'name' => 'Order A', 'price' => 10000]; }
상품 상세 화면에서 route('portone.checkout', ['product' => $product->id])로 링크하면 주문서가 그 상품을 보여 주고,
Start payment 클릭 시 상품 ID만 prepare로 전송됩니다. 금액·주문명은 언제나 서버의 상품에서 정해집니다.
composer serve의 워크벤치 샘플 상점이 이 한 곳만 고친 예시입니다(docs/TESTING.md §1.2).
complete액션은 요청의 금액을 무시하고 서버 레코드 기준으로 검증하므로, 클라이언트 값을 조작해도 안전합니다.
서버 API
자신만의 UI·플로우를 만들거나 스텁 없이 직접 제어할 때 Billable이 제공하는 메서드를 사용합니다.
결제 준비 → 확정
// 1) 결제 레코드 사전 생성 (PortOne 호출 없음, 상태 PENDING) $payment = $user->preparePayment(10000, 'Order A'); // 2) 브라우저 SDK에 전달할 값 $params = $payment->checkoutParameters(); // [ // 'paymentId' => '...', // PortOne 결제 식별자로 그대로 사용 // 'orderName' => 'Order A', // 'totalAmount' => 10000, // 'customerId' => '...', // ] // 3) 구매자가 브라우저에서 결제한 뒤 서버에서 검증·확정 $paid = $user->completePayment($payment->payment_id); // $paid->status === 'PAID'
실결제액이 준비 금액과 다르면 completePayment()는 결제를 자동으로 전액 취소하고
AmountMismatchException을 던집니다(결제 금액 불일치 자동 취소).
환불
// 전액 환불 $user->refund($payment->payment_id, '구매자 요청'); // 부분 환불 (금액 지정) $user->refund($payment->payment_id, '부분 환불', 3000);
전액 환불되면 CANCELLED, 일부만 환불되면 PARTIALLY_CANCELLED가 되며
cancelled_amount에 누적 환불액이 저장됩니다.
결제 내역 조회
// 최신순 결제 목록 $payments = $user->payments()->latest()->get(); // 단건 조회 (다른 사용자의 payment_id는 조회되지 않음) $payment = $user->findPayment($paymentId);
고객 ID
$user->hasPortOneId(); // bool $user->portOneId(); // ?string $user->createOrGetPortOneCustomerId(); // string (없으면 생성)
preparePayment()를 호출하면 고객 레코드는 자동으로 생성되므로
보통은 직접 호출하지 않아도 됩니다.
웹훅
웹훅 라우트는 패키지가 자동 등록합니다 (기본 POST portone/webhook, CSRF 제외).
서명은 cable8mm/portone-php의 검증기로 확인하며, 검증 성공 시에만 이벤트가 발생합니다.
use Cable8mm\LaravelPortone\Events\WebhookReceived; use Illuminate\Support\Facades\Event; Event::listen(WebhookReceived::class, function (WebhookReceived $event) { $webhook = $event->webhook; // 포트원 웹훅 객체 $webhookId = $event->webhookId; // webhook-id 헤더 });
동작 요약:
- 서명 유효, 처음 받은
webhook-id→ 웹훅 기록 → 처리 → (레코드가 바뀌었으면 결제 이벤트) →WebhookReceived1건 발송 +200빈 응답 - 서명 유효, 이미 처리된
webhook-id→200빈 응답만. 레코드 변경·PortOne 조회·이벤트 없음 - 처리 실패(설정 누락·PortOne 오류) → 웹훅 기록을 실패로 표시,
WebhookFailed만 발송, 요청은 오류로 끝나 PortOne이 다시 보냄 - 서명 무효·헤더 누락·타임스탬프 범위 초과 →
400, 이벤트 없음 PORTONE_WEBHOOK_SECRET미설정 →500, 이벤트 없음Transaction.Paid는 결제를 확정하고(아래), 취소 웹훅(Transaction.Cancelled·Transaction.PartialCancelled)은 결제 레코드를 PortOne과 맞춥니다(아래).BillingKey.Issued·BillingKey.Deleted는 빌링키 기록을ISSUED·DELETED로 바꿉니다(빌링키 웹훅). 그 밖의 웹훅은 고객·결제·빌링키 레코드를 읽거나 쓰지 않습니다- 빌링키 웹훅의
WebhookReceivedwebhook객체에는 빌링키 값이 그대로 들어 있습니다. 로그에 남기지 마세요
웹훅 기록
검증된 웹훅은 어떤 처리보다 먼저 portone_webhooks(Cable8mm\LaravelPortone\Models\Webhook)에 webhook-id마다 1건 기록됩니다.
| 컬럼 | 내용 |
|---|---|
webhook_id |
webhook-id 헤더 값 (유니크) |
type |
웹훅 종류 (예: Transaction.Cancelled) |
body |
받은 그대로의 요청 본문 (data.billingKey 값만 [REDACTED]) |
attempts |
이 webhook-id를 받은 횟수 |
received_at |
처음 받은 시각 |
processed_at |
처리를 마친 시각. 있으면 같은 webhook-id는 무시합니다 |
failed_at |
마지막 처리 실패 시각 |
failure |
마지막 처리 실패의 예외 클래스와 메시지 |
- 처리(취소 웹훅의 레코드 동기화 등)와
processed_at표시는 한 트랜잭션입니다. 같은webhook-id가 동시에 오면 나중 요청은 앞 요청이 끝날 때까지 기다린 뒤 아무것도 하지 않습니다. - 처리가 실패하면 처리 내용은 롤백되고
failed_at·failure가 남으며,WebhookFailed(webhookId,type,exception)가 발송됩니다. 다음 전달 때 다시 처리하고, 성공하면failed_at·failure를 지웁니다. - 리스너 예외는 처리 완료 뒤에 일어나므로 기록은 처리된 상태로 남습니다(같은
webhook-id는 다시 처리되지 않음).
처리된 기록은 PORTONE_WEBHOOK_RETENTION_DAYS(기본 90일)이 지나면 model:prune으로 지울 수 있습니다. 처리되지 않았거나 실패한 기록은 지우지 않습니다.
패키지는 스케줄을 등록하지 않으므로 앱에서 등록하세요.
use Cable8mm\LaravelPortone\Models\Webhook; Schedule::command('model:prune', ['--model' => [Webhook::class]])->daily();
결제 이벤트
결제 레코드의 상태가 바뀌면, 무엇이 바꿨든 커밋 뒤에 한 번만 아래 이벤트(Cable8mm\LaravelPortone\Events\*) 중 하나가 발송됩니다.
저장이 롤백되거나 바뀐 것이 없으면(이미 PAID인 결제의 재확정, 같은 상태의 재동기화, 다시 온 웹훅) 발송되지 않습니다.
| 이벤트 | 언제 | 추가 속성 |
|---|---|---|
PaymentCompleted |
PAID가 됨 |
|
PaymentPartiallyRefunded |
cancelled_amount가 늘어 PARTIALLY_CANCELLED가 됨 |
refundedAmount (늘어난 금액) |
PaymentRefunded |
PAID·PARTIALLY_CANCELLED가 CANCELLED가 됨 |
refundedAmount |
PaymentAmountMismatched |
AMOUNT_MISMATCH_CANCELLED(wasCancelled true)·AMOUNT_MISMATCH(false)가 됨 |
wasCancelled |
PaymentDuplicated |
DUPLICATE_CANCELLED·DUPLICATE가 됨 |
wasCancelled |
PaymentExpired |
EXPIRED가 됨 |
모든 결제 이벤트(공통 부모 PaymentEvent)에는 저장 뒤의 payment, paymentId, 소유 모델 참조 billableType·billableId,
바꾼 진입점 source(PaymentEventSource)가 들어 있습니다.
source |
진입점 |
|---|---|
complete |
completePayment(), completeByPaymentId(), 발행한 체크아웃(브라우저 복귀) |
webhook |
Transaction.Paid 웹훅의 결제 확정, 취소 웹훅의 동기화 |
expiry |
만료 확인 잡 |
sync |
syncByPaymentId() |
refund |
refund() |
charge |
chargeBillingKey(), 구독의 첫 기간·갱신 결제(subscribe(), portone:charge-subscriptions) |
use Cable8mm\LaravelPortone\Events\PaymentCompleted; Event::listen(PaymentCompleted::class, function (PaymentCompleted $event) { Order::firstWhere('payment_id', $event->paymentId)?->markPaid(); });
웹훅 요청에서는 결제 이벤트가 WebhookReceived보다 먼저 발송됩니다. 웹훅 종류 자체에 반응하려면 WebhookReceived의 webhook을 보세요.
취소 웹훅과 결제 레코드 동기화
PortOne 콘솔이나 다른 시스템에서 환불하면 Transaction.Cancelled·Transaction.PartialCancelled 웹훅이 옵니다. 패키지는 서명을 검증한 뒤
이벤트를 보내기 전에 PortOne에 결제를 다시 조회해 레코드를 맞춥니다. 레코드가 바뀌면 PaymentRefunded·PaymentPartiallyRefunded
(AMOUNT_MISMATCH였으면 PaymentAmountMismatched, DUPLICATE였으면 PaymentDuplicated)가 source = webhook으로 발송되고, WebhookReceived 리스너는 이미 갱신된 레코드를 읽습니다. 웹훅 내용이 아니라 PortOne 조회 결과(amount.cancelled)를 기준으로 합니다.
| 로컬 상태 | PortOne 조회 결과 | 결과 |
|---|---|---|
PAID·PARTIALLY_CANCELLED |
CANCELLED, 취소 총액 = amount |
CANCELLED, cancelled_amount = 취소 총액 |
PAID·PARTIALLY_CANCELLED |
PARTIAL_CANCELLED, 0 < 취소 총액 < amount |
PARTIALLY_CANCELLED, cancelled_amount = 취소 총액 |
AMOUNT_MISMATCH |
CANCELLED, 취소 총액 = paid_amount |
AMOUNT_MISMATCH_CANCELLED |
DUPLICATE |
CANCELLED, 취소 총액 = paid_amount |
DUPLICATE_CANCELLED |
| 그 밖 | 그 밖(아직 PAID 등) |
그대로. 결제 이벤트 없음, WebhookReceived만 |
refund()와 같은 잠금을 쓰고 절대값으로 저장하므로 같은 웹훅이 여러 번 와도 결과가 같습니다.PENDING·EXPIRED·CANCELLED레코드나 이 패키지가 만들지 않은 결제는 PortOne을 조회하지 않고WebhookReceived만 보냅니다.refund()로 이미 반영한 취소의 웹훅은 레코드를 바꾸지 않으므로 결제 이벤트가 다시 나가지 않습니다.- PortOne 조회가 실패하면(설정 누락 포함)
WebhookFailed만 발송하고 웹훅 요청이 오류로 끝나 PortOne이 다시 보냅니다. 레코드는 그대로입니다. amount·paid_at·paid_amount는 바꾸지 않습니다.
웹훅 없이 같은 동기화를 하려면 syncByPaymentId()를 부르세요. 결제 ID만으로 레코드를 찾으며, 없으면 PaymentNotFoundException입니다.
use Cable8mm\LaravelPortone\PaymentOperations; $payment = app(PaymentOperations::class)->syncByPaymentId($paymentId);
웹훅으로 결제 확정
Transaction.Paid 웹훅을 받으면 패키지가 웹훅 데이터의 결제 ID로 결제를 확정합니다. completeByPaymentId()와 같은 규칙(잠금, 이미 확정된
결제는 그대로, 금액 불일치 자동 취소)이며, PortOne에 다시 조회해 검증하므로 웹훅 내용만 믿고 상태를 바꾸지 않습니다. 앱 코드는 필요 없습니다.
PENDING·EXPIRED레코드가 결제·금액 일치면PAID,PaymentCompleted(source=webhook)- 이미 브라우저 복귀로 확정된 결제면 바뀌는 것이 없어
PaymentCompleted가 다시 나가지 않음 - PortOne이 아직 결제되지 않았다고 하거나 이 패키지가 만들지 않은 결제면 그대로 두고 웹훅 처리는 성공
- 금액이 다르면 금액 불일치 규칙대로 저장하고 웹훅 처리는 성공
- 한 번만 결제되는 모델의 두 번째 결제면 중복 결제 규칙대로 저장하고 웹훅 처리는 성공
- PortOne 조회 실패·설정 누락이면
WebhookFailed, 요청 실패, PortOne이 다시 보냄
웹훅 없이 결제 ID만으로 확정하려면 PaymentOperations::completeByPaymentId()를 부르세요. 결제가 없으면 PaymentNotFoundException입니다.
결제 상태
portone_payments.status는 다음 중 하나입니다.
PENDING→PAID→PARTIALLY_CANCELLED→CANCELLEDPAID에서 바로CANCELLED(전액 환불)도 가능CANCELLED는 최종 상태입니다- 버려진 결제:
PENDING→EXPIRED. 만료 뒤에 결제되면completePayment()로EXPIRED→PAID복구 EXPIRED는 환불할 수 없습니다 (InvalidPaymentStatusException)- 금액 불일치:
PENDING·EXPIRED→AMOUNT_MISMATCH_CANCELLED(자동 취소 성공) 또는AMOUNT_MISMATCH(자동 취소 실패). 두 상태는 환불할 수 없습니다.AMOUNT_MISMATCH를 PortOne 콘솔에서 취소하면 취소 동기화가AMOUNT_MISMATCH_CANCELLED로 바꿉니다 - 중복 결제: 한 번만 결제되는 모델의
PENDING·EXPIRED→DUPLICATE_CANCELLED(자동 취소 성공) 또는DUPLICATE(자동 취소 실패). 두 상태는 환불할 수 없습니다.DUPLICATE를 PortOne 콘솔에서 취소하면 취소 동기화가DUPLICATE_CANCELLED로 바꿉니다 - PortOne 콘솔 등에서 환불한 결제는 취소 웹훅이나
syncByPaymentId()로PARTIALLY_CANCELLED·CANCELLED가 됩니다
paid_amount는 PortOne이 알려 준 실결제액입니다. PAID로 확정할 때와 금액 불일치·중복 결제 때 저장하므로, 상태와 상관없이
paid_amount 하나로 실결제액을 볼 수 있습니다. PENDING·EXPIRED처럼 PortOne이 아직 실결제액을 알려 주지 않은 결제만 null입니다.
환불해도 paid_amount는 바뀌지 않고, 환불액은 cancelled_amount에 쌓입니다.
영수증 URL
receipt_url은 그 레코드에 마지막으로 쓴 PortOne 조회가 알려 준 영수증 URL(receiptUrl)입니다. 결제 확정, 금액 불일치·중복 결제 저장,
취소 동기화(취소 웹훅·syncByPaymentId()), 빌링키 결제가 조회 결과와 함께 저장합니다. 조회에 영수증 URL이 없으면 이전 값을 그대로 두고,
조회 없이 쓰는 refund()는 바꾸지 않습니다. 저장되기 전(PENDING·EXPIRED)에는 null입니다.
$payment = $user->findPayment($paymentId); $payment->receipt_url; // ?string, 구매자에게 보여 줄 PortOne 영수증 링크
PortOne 원본 결제 응답 보기
자동 테스트에 쓸 실제 PortOne 응답을 기록하거나 결제를 들여다볼 때 씁니다.
php artisan portone:payment {paymentId} # 개인정보·카드·계좌 정보를 가린 JSON
php artisan portone:payment {paymentId} --raw # 가리지 않은 원본 JSON
기본 출력은 다음 키의 값을 깊이와 상관없이 [REDACTED]로 바꿉니다. 키는 남겨 두므로 응답 구조는 실제와 같습니다.
- 고객 개인정보:
name,birthYear,birthMonth,birthDay,gender,email,phoneNumber,address,zipcode,customerIdentityNumber - 카드 식별 정보:
number,bin,approvalNumber - 계좌 식별 정보:
accountNumber,remitteeName,remitterName,depositorName - PG 원본 응답:
pgResponse(JSON 문자열이라 통째로 가림. 카드번호·승인번호 포함) - 접속·전달 기록:
ipAddress,userAgent,receiptUrl,webhooks(웹훅 전달 기록, 서명 헤더 포함) - 빌링키 결제의 빌링키:
billingKey(--raw에서도 가립니다)
name은 키 이름으로 가리므로 카드사 상품명처럼 개인정보가 아닌 name도 가려집니다. --raw 출력은 기록·공유하지 마세요.
--raw가 가리는 것은 billingKey뿐이며, 코드에서는 PaymentResponseRedactor::redactBillingKey()가 같은 일을 합니다.
코드에서는 PortOneGateway::paymentResponse($paymentId)가 원본 배열을 돌려주고, PaymentResponseRedactor::redact()로 같은 방식으로 가릴 수 있습니다.
use Cable8mm\LaravelPortone\PaymentResponseRedactor; use Cable8mm\LaravelPortone\PortOneGateway; $response = app(PortOneGateway::class)->paymentResponse($paymentId); $safe = app(PaymentResponseRedactor::class)->redact($response);
결제 금액 불일치 자동 취소
브라우저가 requestPayment()에 넣는 금액은 구매자가 바꿀 수 있습니다. 그러면 PortOne에서는 결제가 PAID인데
금액이 서버가 준비한 금액(amount)과 다릅니다. 패키지는 이 결제를 그냥 두지 않고 PortOne에서 실결제액 전액을
취소합니다. 앱 코드가 PortOne API를 직접 부를 필요가 없습니다.
completePayment()가 PortOne 조회 결과 PAID이면서 금액이 다른 결제를 만나면:
-
PortOne에 전액 취소를 요청합니다. 사유는
PORTONE_AMOUNT_MISMATCH_CANCEL_REASON(기본값결제 금액 불일치로 자동 취소)입니다. -
결과를 레코드에 저장합니다. 준비 금액(
amount)과paid_at은 바꾸지 않습니다.결과 statuspaid_amountcancelled_amount취소 성공 AMOUNT_MISMATCH_CANCELLED실결제액 실결제액 취소 실패 AMOUNT_MISMATCH실결제액 0 -
AmountMismatchException을 던집니다.
use Cable8mm\LaravelPortone\Exceptions\AmountMismatchException; try { $user->completePayment($paymentId); } catch (AmountMismatchException $e) { $e->paidAmount(); // PortOne 실결제액 (원) $e->wasCancelled(); // 자동 취소 성공 여부 $e->getPrevious(); // 취소 실패 때 PortOne 예외, 성공이면 null }
-
같은 결제를 다시 완료 요청하면(브라우저와 웹훅이 겹칠 때 등) PortOne을 다시 부르지 않고 저장된 레코드로 같은 예외를 던집니다.
-
만료 검사 잡(
portone:expire-pending)도 같은 결제를 만나면 똑같이 자동 취소합니다. 취소가 성공하면 잡은 정상 종료하고, 실패하면AMOUNT_MISMATCH를 저장한 뒤 PortOne 예외로 실패 잡이 됩니다. -
AMOUNT_MISMATCH는 운영자가 처리해야 하는 건입니다. 패키지는 다시 시도하지 않습니다. 포트원 콘솔에서 결제를 확인해 직접 취소하고 레코드를 정리하세요.Payment::query()->where('status', 'AMOUNT_MISMATCH')->get();
중복 결제 자동 취소
주문처럼 한 번만 결제되어야 하는 모델은 구매자가 결제 창을 두 번 열어 둘 다 결제할 수 있습니다. 모델에서
allowsOnlyOnePaidPayment()가 true를 반환하게 하면 패키지가 두 번째로 결제된 건을 PortOne에서 전액 취소합니다.
기본값은 false입니다(사용자처럼 결제가 여러 번인 모델).
class Order extends Model { use Billable; public function allowsOnlyOnePaidPayment(): bool { return true; } }
결제 확정(completePayment(), completeByPaymentId(), Transaction.Paid 웹훅, 만료 검사 잡)이 결제·금액 일치인 결제를 만났을 때,
같은 모델에 이미 PAID·PARTIALLY_CANCELLED·CANCELLED인 결제가 있으면:
-
PAID로 바꾸지 않고 PortOne에 전액 취소를 요청합니다. 사유는PORTONE_DUPLICATE_CANCEL_REASON(기본값중복 결제로 자동 취소)입니다. -
결과를 레코드에 저장하고
PaymentDuplicated(wasCancelled)를 보냅니다.결과 statuspaid_amountcancelled_amountpaid_at취소 성공 DUPLICATE_CANCELLED실결제액 실결제액 현재 시각 취소 실패 DUPLICATE실결제액 0현재 시각 -
completePayment()·completeByPaymentId()는DuplicatePaymentException을 던집니다. 웹훅 처리는 성공으로 끝나고, 만료 검사 잡은 금액 불일치와 같이 취소가 실패했을 때만 PortOne 예외로 실패합니다.
use Cable8mm\LaravelPortone\Exceptions\DuplicatePaymentException; try { $order->completePayment($paymentId); } catch (DuplicatePaymentException $e) { $e->paidAmount(); // PortOne 실결제액 (원) $e->wasCancelled(); // 자동 취소 성공 여부 $e->getPrevious(); // 취소 실패 때 PortOne 예외, 성공이면 null }
- 같은 모델의 결제 확정은 모델 단위로 잠가 차례로 처리하므로, 두 결제가 동시에 확정돼도
PAID는 하나뿐입니다. - 웹훅·만료 검사처럼 결제 ID만으로 확정할 때는 결제 레코드의
billable_type·billable_id로 모델을 조회해allowsOnlyOnePaidPayment()를 부릅니다. 모델을 찾을 수 없으면false로 봅니다. - 이미
DUPLICATE_CANCELLED·DUPLICATE인 결제를 다시 확정하면 PortOne을 부르지 않고 레코드를 그대로 반환합니다. - 구독 결제(
for_subscription이true, v0.8.0)는 이 규칙에서 빠집니다. 어느 경로로 확정되든PAID가 되고, 다른 결제의 판단에서 "이미 결제된 건"으로 세지 않습니다(구독). DUPLICATE는AMOUNT_MISMATCH처럼 운영자가 처리해야 하는 건입니다. 포트원 콘솔에서 취소하면 취소 웹훅이나syncByPaymentId()가DUPLICATE_CANCELLED로 기록합니다.
빌링키 결제
구매자가 카드를 한 번 등록하면 받은 빌링키로 결제창 없이 서버에서 결제합니다. 빌링키 발급이 가능한 PortOne 채널이 필요합니다.
패키지는 서버 쪽 기록·확인·결제를 맡습니다. 브라우저의 발급 화면(requestIssueBillingKey)은 v0.8.0의 빌링키 등록 스텁으로
시작하거나 아래 1~3단계로 직접 만듭니다.
빌링키 등록 화면 (스텁)
portone-stubs(블레이드)와 portone-stubs-react(Inertia React)는 v0.8.0부터 로그인한 사용자가 카드를 등록하는 화면도 발행합니다(스텁 발행).
빌링키 발급이 가능한 채널 키를 PORTONE_BILLING_CHANNEL_KEY에 설정하고 로그인 후 /portone/billing-key에 접속합니다.
라우트 (auth 미들웨어) |
경로 | 액션 |
|---|---|---|
portone.billing-key |
GET /portone/billing-key |
billingKey |
portone.billing-key.prepare |
POST /portone/billing-key/prepare |
prepareBillingKey |
portone.billing-key.completed |
GET /portone/billing-key/completed/{issueId} |
billingKeyCompleted |
- 화면은
Register card버튼과 상태(Idle)를 보여 줍니다.PORTONE_STORE_ID나PORTONE_BILLING_CHANNEL_KEY가 비어 있으면Error상태이고 버튼이 비활성화됩니다. - 버튼을 누르면
Loading상태가 되고POST portone.billing-key.prepare가prepareBillingKey()로PENDING기록을 만들어BrowserBillingKeyRequest값 (billingKeyMethodCARD,forceRedirect: true, 이 Issue ID의portone.billing-key.completed주소를 담은redirectUrl)을 JSON으로 응답합니다. - 스크립트가 그 값을 그대로
requestIssueBillingKey()에 넘깁니다. 준비 요청이나 SDK 호출이 실패하거나 결제창을 닫고 돌아오면Error상태로 끝납니다. - 복귀하면
billingKeyCompleted가 쿼리를BillingKeyRedirectResult로 읽습니다. 실패 복귀면 아무 기록도 건드리지 않고Failed, 아니면completeBillingKey()를 불러Issued(확정이 예외면Failed)를 보여 줍니다. - 화면은 빌링키 값을 보여 주지 않습니다. 등록 이름은 컨트롤러 상수
BILLING_KEY_ISSUE_NAME(Card registration)이고, 바꿔서 쓰면 됩니다.
등록 화면은 v0.9.0 전까지 카드(BILLING_KEY_METHOD = CARD)만 등록합니다. 등록한 빌링키로 결제하거나 구독을 시작하는 코드는 앱이 부릅니다(아래 4단계, 구독).
1. 발급 준비
$record = $user->prepareBillingKey('정기 결제 카드'); // PortOne 호출 없음, 상태 PENDING $record->issueParameters(); // ['issueId' => '...', 'issueName' => '정기 결제 카드', 'customerId' => '...']
issue_id는 패키지가 만든 고유 값(결제 ID와도 겹치지 않음)이고, 고객 레코드가 없으면 함께 만듭니다.
2. 브라우저에서 발급
issueParameters()를 @portone/browser-sdk/v2의 requestIssueBillingKey()에 넘깁니다. cable8mm/portone-php의
BrowserBillingKeyRequest로 값을 만들 수 있습니다.
use Cable8mm\PortonePhp\Browser\BrowserBillingKeyRequest; $issuance = $record->issueParameters(); $request = (new BrowserBillingKeyRequest( storeId: config('portone.store_id'), channelKey: $billingChannelKey, // 빌링키 발급이 가능한 채널 billingKeyMethod: 'CARD', issueId: $issuance['issueId'], issueName: $issuance['issueName'], redirectUrl: route('billing-key.completed', ['issueId' => $issuance['issueId']]), customerId: $issuance['customerId'], forceRedirect: true, ))->toArray(); // 브라우저에서 PortOne.requestIssueBillingKey(request)로 호출
3. 발급 확정
리다이렉트 복귀에서 쿼리의 billingKey로 확정합니다. 실패 복귀에도 발급되지 않은 billingKey가 함께 오므로 code를 먼저 확인하세요.
cable8mm/portone-php의 BillingKeyRedirectResult가 실패면 billingKey를 null로 돌려줍니다.
use Cable8mm\LaravelPortone\Exceptions\BillingKeyNotIssuedException; use Cable8mm\PortonePhp\Browser\BillingKeyRedirectResult; $redirect = BillingKeyRedirectResult::fromQuery($request->query()); if ($redirect->isFailure() || $redirect->billingKey === null) { // 발급 실패: $redirect->code, $redirect->message } else { try { $record = $user->completeBillingKey($issueId, $redirect->billingKey); // ISSUED } catch (BillingKeyNotIssuedException $e) { // PortOne이 이 고객에게 발급하지 않았다고 함. 기록은 FAILED } }
PENDING·FAILED기록만 PortOne에 빌링키를 조회합니다. PortOne이 그 기록의 고객·Issue ID로 발급했다고 하면 빌링키를 애플리케이션 키로 암호화해 저장하고ISSUED(issued_at)가 됩니다. 아니면FAILED가 되고BillingKeyNotIssuedException입니다.FAILED기록은 다시 확정할 수 있습니다.- 같은 빌링키로 이미
ISSUED인 기록은 PortOne을 부르지 않고 그대로 돌려줍니다. 다른 빌링키를 넘기면 아무것도 바꾸지 않고BillingKeyNotIssuedException입니다. - 내 범위에 그 Issue ID의
PENDING·FAILED·ISSUED기록이 없으면BillingKeyNotFoundException(PortOne 호출 없음)입니다. - 빌링키는
APP_KEY로 암호화되므로APP_KEY를 바꾸면 저장된 빌링키를 꺼낼 수 없습니다. 키를 교체할 때는APP_PREVIOUS_KEYS를 설정하세요.
4. 빌링키로 결제
$payment = $user->chargeBillingKey($issueId, 9900, '3월 이용료'); // PAID인 결제 레코드 $payment->billingKey; // 결제한 빌링키 기록 (Payment::billingKey() 관계, billing_key_id)
preparePayment()처럼PENDING결제 레코드를 만들어 커밋한 뒤 PortOnepayWithBillingKey(원화)를 요청하고, 성공하면completeByPaymentId()와 같은 규칙으로 확정합니다. 결제 이벤트의source는charge이고 영수증 URL도 저장됩니다.- PortOne이 결제를 거절하면(PG 거절 등) 레코드는
PENDING으로 남고 PortOne 예외가 그대로 전달됩니다. 남은PENDING은 만료 검사가 정리합니다. - 금액이 0 이하이거나 주문명이 비면
InvalidArgumentException,ISSUED가 아니거나 내 것이 아닌 빌링키면InvalidBillingKeyException입니다(둘 다 PortOne 호출·레코드 생성 없음). API Secret이 없으면 레코드를 만들기 전에ConfigurationException입니다. AmountMismatchException·DuplicatePaymentException·PaymentNotPaidException은completePayment()와 같습니다. 환불은refund()로 같습니다.
5. 빌링키 삭제와 조회
$record = $user->deleteBillingKey($issueId, '구매자 요청'); // PortOne에서 삭제 후 DELETED $user->billingKeys()->where('status', 'ISSUED')->get(); // 최신순 빌링키 기록
ISSUED가 아니거나 내 것이 아닌 기록, ACTIVE·PAST_DUE 구독이 결제하는 기록(v0.8.0)이면 InvalidBillingKeyException(PortOne 호출 없음)입니다.
빌링키 기록과 이벤트
portone_billing_keys(Cable8mm\LaravelPortone\Models\BillingKey)는 발급 1건입니다.
| 컬럼 | 내용 |
|---|---|
issue_id |
Issue ID (유니크, PortOne issueId) |
billable_type·billable_id |
소유 모델 |
customer_id |
발급한 고객 ID |
issue_name |
발급 이름 |
billing_key |
암호화한 빌링키. 발급 전에는 null, 배열·JSON 변환에서 숨김 |
status |
PENDING → ISSUED → DELETED, PENDING → FAILED → ISSUED |
issued_at·deleted_at |
발급·삭제 시각 |
기록이 ISSUED·DELETED가 되어 커밋되면 BillingKeyIssued·BillingKeyDeleted가 한 번 발송됩니다. 속성은 저장 뒤의 billingKey(기록, 평문 빌링키 없음)와
source(BillingKeyEventSource: 메서드 호출이면 call, 웹훅이면 webhook)입니다.
use Cable8mm\LaravelPortone\Events\BillingKeyDeleted; Event::listen(BillingKeyDeleted::class, function (BillingKeyDeleted $event) { // $event->billingKey->issue_id, $event->source });
패키지는 빌링키 값을 로그, 이벤트, portone:payment 출력, issueParameters(), 웹훅 기록 어디에도 남기지 않습니다.
빌링키 웹훅
BillingKey.Issued: PortOne에 빌링키를 조회해 Issue ID로 기록을 찾고,PENDING이면completeBillingKey()와 같은 규칙으로ISSUED(또는FAILED)가 됩니다. 브라우저 복귀가 앱에 닿지 않아도 기록이 맞춰집니다.BillingKey.Deleted: PortOne 콘솔 등에서 삭제한 빌링키의ISSUED기록이DELETED가 됩니다. 구독이 결제하는 기록도 마찬가지입니다(구독).- 그 밖의 빌링키 웹훅(
BillingKey.Ready등)이나 맞는 기록이 없는 웹훅은 아무것도 바꾸지 않습니다. 조회 실패는 다른 웹훅처럼WebhookFailed로 끝나고 PortOne이 다시 보냅니다.
테스트
FakePaymentGateway는 빌링키 API를 다루지 않습니다. 빌링키 흐름을 테스트하려면 Cable8mm\LaravelPortone\BillingKeyGateway 인터페이스를
구현한 가짜를 컨테이너에 바인딩하세요(billingKeyInfo(), deleteBillingKey(), payWithBillingKey(), assertConfigured()). 빌링키 결제의 확정 조회는
PaymentGateway(예: FakePaymentGateway)로 합니다.
구독
v0.8.0부터 ISSUED 빌링키로 기간마다 같은 금액을 결제하는 구독을 만들 수 있습니다. 결제는 빌링키로 결제와 같은 규칙입니다.
1. 구독 시작
$subscription = $user->subscribe($issueId, '프리미엄', 9900, '프리미엄 월 이용료', '1m'); // ACTIVE 구독 기록
- 인자는 Issue ID, 구독 이름, 기간마다 결제할 금액(원), 주문명, 기간입니다. 기간은
<n>d(일)·<n>m(월)·<n>y(년),n은 1 이상입니다. 월·년은 날짜를 유지하되 그 달의 말일을 넘기지 않습니다(1월 31일 +1m= 2월 말일). - 첫 기간을 바로 결제하고, 그 결제가
PAID가 될 때만 구독 기록을 만듭니다. 현재 기간은 첫 결제 시각(paid_at)부터 기간 하나이고, 기간 끝이 다음 결제 시각입니다. - 기간·금액·이름·주문명이 규칙에 맞지 않으면
InvalidArgumentException(PortOne 요청·기록 없음), 내ISSUED빌링키가 아니면InvalidBillingKeyException입니다. 첫 결제가 거절되거나PAID가 되지 않으면 구독 기록을 만들지 않고 그 결제의 예외(PortOneException,PaymentNotPaidException등)를 그대로 던집니다. - 첫 결제가
PAID가 된 뒤 구독 기록을 만들기 전에 작업이 중단되면 결제만 남습니다. 패키지는 나중에 구독을 만들거나 결제를 취소하지 않으므로 결제 이벤트(PaymentCompleted,source=charge)로 처리하세요.
2. 갱신 결제 스케줄
패키지는 스케줄을 등록하지 않습니다. 앱의 스케줄러에 등록하고 큐 워커를 띄우세요.
// routes/console.php use Illuminate\Support\Facades\Schedule; Schedule::command('portone:charge-subscriptions')->hourly();
portone:charge-subscriptions는ACTIVE·PAST_DUE이고next_charge_at이 지난 구독마다 결제 잡(Jobs\ChargeSubscription)을 큐에 넣습니다(PortOne 호출 없음). 결제는next_charge_at뒤 첫 명령 실행에서 일어나므로, 실행 간격이 결제가 늦어질 수 있는 최대 시간입니다.- 잡은 실행 시점에 결제할 때가 아니면 아무것도 하지 않습니다. 해지 예약된 구독은 결제하지 않고
ENDED가 됩니다. - 그 밖에는 이번 기간을 결제합니다. 이 구독의 이번 기간
PENDING결제가 있으면(이전 실행이 결제 요청 뒤 중단된 경우) 먼저 PortOne에 확인해 확정하고, 결제되지 않았을 때만 다시 결제합니다. 그래서 중단 뒤 다시 실행해도 한 기간을 두 번 결제하지 않습니다. - 갱신 결제가
PAID가 되면 다음 기간으로 넘어가고(ACTIVE,failed_attempts0)SubscriptionRenewed가 발송됩니다. - 갱신 결제가 거절되거나
PAID가 되지 않으면failed_attempts가 1 늘고,PORTONE_SUBSCRIPTION_RETRY_AFTER(기본1,3,5)의 그 순번 일수 뒤로next_charge_at을 미뤄PAST_DUE가 됩니다(SubscriptionRenewalFailed). 마지막 재시도도 실패하면EXPIRED가 됩니다(SubscriptionExpired). 거절된 갱신 결제 레코드는PENDING으로 남고 만료 검사가 정리합니다. - 설정 누락(
ConfigurationException), 이번 기간PENDING결제의 PortOne 조회 실패, 저장 실패는 구독을 바꾸지 않고 잡을 실패시킵니다. 구독은 여전히 결제할 때이므로 큐 재시도나 다음 명령 실행이 다시 처리합니다. - 같은 구독의 작업은 앱의 기본 캐시 저장소의 원자적 잠금(
Cache::lock, 300초)으로 차례로 실행합니다. 기본 캐시 저장소가 잠금을 지원해야 하며, 다른 작업의 잠금을 120초 넘게 기다리면LockTimeoutException입니다.
3. 해지 예약·취소, 결제 카드 변경
$subscription = $user->subscriptions()->where('status', 'ACTIVE')->first(); // 최신순 구독 기록 $subscription->cancel(); // 현재 기간이 끝나면 ENDED (cancel_at_period_end = true) $subscription->resume(); // 기간이 끝나기 전에 해지 예약 취소 $subscription->changeBillingKey($newIssueId); // 다음 결제부터 같은 모델의 다른 ISSUED 빌링키로 결제
cancel():ACTIVE면 해지 예약만 하고 기간 끝까지 유지합니다. 이미 예약됐으면 아무것도 바꾸지 않습니다.PAST_DUE면 재시도를 기다리지 않고 바로ENDED입니다. 결제한 금액은 환불하지 않습니다. 환불은refund()로 하세요.resume(): 해지 예약된ACTIVE구독만 받습니다.changeBillingKey():ACTIVE·PAST_DUE구독만 받습니다. 같은 모델의ISSUED빌링키가 아니면InvalidBillingKeyException입니다.- 받지 않는 상태에서 부르면
InvalidSubscriptionStatusException이고 아무것도 바꾸지 않습니다. ACTIVE·PAST_DUE구독이 결제하는 빌링키는deleteBillingKey()로 지울 수 없습니다(InvalidBillingKeyException). 먼저 해지하거나 결제 카드를 바꾸세요. PortOne 콘솔 등에서 지워BillingKey.Deleted웹훅이 오면 빌링키 기록은DELETED가 되고, 그 뒤 갱신 결제는 실패해 결제 카드를 바꾸지 않는 한 재시도 끝에EXPIRED가 됩니다.
구독 기록과 이벤트
portone_subscriptions(Cable8mm\LaravelPortone\Models\Subscription)는 구독 1건입니다. 패키지는 구독 기록과 빌링키 기록을 지우지 않습니다.
| 컬럼 | 내용 |
|---|---|
billable_type·billable_id |
소유 모델 (billable() 관계) |
billing_key_id |
결제할 빌링키 기록 (billingKey() 관계) |
name·amount·order_name·interval |
구독 이름, 기간마다 결제할 금액(원), 주문명, 기간 |
status |
ACTIVE·PAST_DUE·ENDED·EXPIRED |
cancel_at_period_end |
현재 기간이 끝나면 끝낼지 (해지 예약) |
current_period_start·current_period_end |
현재 기간 |
next_charge_at |
다음 결제(갱신 또는 재시도) 시각 |
failed_attempts |
연속으로 실패한 갱신 결제 횟수 |
ended_at |
ENDED·EXPIRED가 된 시각 |
상태는 ACTIVE ↔ PAST_DUE, ACTIVE·PAST_DUE → ENDED, PAST_DUE → EXPIRED로 바뀝니다. 기간마다 결제 레코드 하나가 subscription_id로 구독을 가리키며,
구독 결제 레코드는 for_subscription이 true입니다. 이런 결제는 allowsOnlyOnePaidPayment()가 true인 모델에서도 중복 결제로 취소되지 않고, 다른 결제의
중복 판단에서 "이미 결제된 건"으로 세지 않습니다(중복 결제 자동 취소).
구독 기록이 바뀌어 커밋되면 아래 이벤트(Cable8mm\LaravelPortone\Events\*, 공통 부모 SubscriptionEvent)가 한 번씩 발송됩니다. 모두 저장 뒤의 subscription을 가집니다.
구독 결제 자체는 결제 이벤트(PaymentCompleted 등, source = charge)로도 알려집니다.
| 이벤트 | 언제 | 추가 속성 |
|---|---|---|
SubscriptionStarted |
첫 기간이 결제되어 ACTIVE 구독이 만들어짐 |
|
SubscriptionRenewed |
다음 기간이 결제됨 | |
SubscriptionRenewalFailed |
갱신 결제가 실패해 PAST_DUE가 됨 |
attempt, nextChargeAt |
SubscriptionExpired |
마지막 재시도까지 실패해 EXPIRED가 됨 |
|
SubscriptionCancelled |
해지 예약됨 (cancel()) |
|
SubscriptionResumed |
해지 예약이 취소됨 (resume()) |
|
SubscriptionEnded |
ENDED가 됨 (해지 예약된 기간 끝, PAST_DUE의 cancel()) |
use Cable8mm\LaravelPortone\Events\SubscriptionRenewalFailed; Event::listen(SubscriptionRenewalFailed::class, function (SubscriptionRenewalFailed $event) { // $event->subscription, $event->attempt, $event->nextChargeAt });
결제 대기 건 만료와 정리
결제를 시작(prepare)하고 끝내지 않은 PENDING 결제는 그대로 쌓입니다. 패키지는 스케줄을
등록하지 않으므로, 앱의 스케줄러와 큐 워커로 정리합니다.
// routes/console.php use Cable8mm\LaravelPortone\Models\Payment; use Illuminate\Support\Facades\Schedule; Schedule::command('portone:expire-pending')->everyTenMinutes(); Schedule::command('model:prune', ['--model' => [Payment::class]])->daily();
-
portone:expire-pending은PORTONE_PENDING_EXPIRE_AFTER분보다 오래된PENDING결제마다 확인 잡을 큐에 넣습니다(PortOne 호출 없음). 앱의 기본 큐 연결을 쓰므로queue:work가 떠 있어야 합니다. -
잡은 PortOne에 결제를 조회해 결제·금액 일치면
PAID, 결제되지 않았으면(READY·FAILED·PAYMENT_NOT_FOUND)EXPIRED로 바꾸고, 그 밖에는 그대로 둬서 다음 검사에서 다시 확인합니다. 설정 누락이나 PortOne 실패는 실패 잡으로 남습니다. -
EXPIRED는 "확인 시점에 결제되지 않음"입니다. 같은 결제 ID로 나중에 결제될 수 있으므로 (실제 관측),completePayment()를 부르거나Transaction.Paid웹훅이 오면PAID로 복구됩니다. -
잡은 레코드를 바꾼 뒤(커밋 뒤) 결과를
source=expiry인 결제 이벤트로 알립니다. 바꾼 것이 없으면 보내지 않습니다.결과 이벤트 미결제 확정 → EXPIREDPaymentExpired뒤늦은 결제(금액 일치) → PAIDPaymentCompleted다른 금액으로 결제 → 자동 취소 규칙 PaymentAmountMismatched(wasCancelled)한 번만 결제되는 모델의 두 번째 결제 PaymentDuplicated(wasCancelled)자동 취소가 실패하면(
wasCancelledfalse,AMOUNT_MISMATCH) 이벤트를 보낸 다음 잡이 PortOne 예외로 실패합니다.use Cable8mm\LaravelPortone\Events\PaymentExpired; Event::listen(PaymentExpired::class, function (PaymentExpired $event) { $order = Order::firstWhere('payment_id', $event->paymentId); $order?->markAbandoned(); });
-
model:prune은PORTONE_EXPIRED_RETENTION_DAYS일이 지난EXPIRED결제만 지웁니다. 결제된(PAID·PARTIALLY_CANCELLED·CANCELLED) 기록과 금액 불일치(AMOUNT_MISMATCH_CANCELLED·AMOUNT_MISMATCH)·중복 결제(DUPLICATE_CANCELLED·DUPLICATE) 기록은 절대 지우지 않습니다. -
웹 요청(예: 관리자 화면의 버튼)에서 만료 검사를 바로 돌리려면
Artisan::queue('portone:expire-pending')를 쓰세요. 패키지 명령은 콘솔에서만 등록되므로 웹 요청 안의Artisan::call()은 "command does not exist"로 실패합니다.
예외
| 예외 | HTTP (스텁 기준) | 의미 |
|---|---|---|
PaymentNotFoundException |
422 |
내 범위에 해당 payment_id 없음 |
PaymentNotPaidException |
422 |
PortOne에서 미결제 상태 |
AmountMismatchException |
422 |
서버 금액과 PortOne 실결제액 불일치. 결제는 자동 전액 취소됨(wasCancelled()) |
DuplicatePaymentException |
422 |
한 번만 결제되는 모델에 이미 결제된 건이 있음. 결제는 자동 전액 취소됨(wasCancelled()) |
InvalidPaymentStatusException |
— | 결제되지 않았거나(PENDING·EXPIRED) 이미 전액 취소됐거나 금액 불일치·중복 결제를 환불 |
InvalidRefundAmountException |
— | 환불 금액이 0 이하이거나 환불 가능액 초과 |
BillingKeyNotFoundException |
— | completeBillingKey()에 내 범위의 발급 기록이 없는 Issue ID |
BillingKeyNotIssuedException |
— | PortOne이 이 고객에게 빌링키를 발급하지 않았다고 함(기록은 FAILED), 또는 다른 빌링키 |
InvalidBillingKeyException |
— | ISSUED가 아니거나 내 것이 아닌 빌링키를 삭제·결제·구독, ACTIVE·PAST_DUE 구독이 결제하는 빌링키를 삭제 |
InvalidSubscriptionStatusException |
— | 받지 않는 상태의 구독에 cancel()·resume()·changeBillingKey() |
ConfigurationException |
500 |
api_secret 등 필수 설정 누락 |
PortOneException (cable8mm/portone-php) |
500 |
PortOne API 실패 (원문 그대로 전달) |
테스트 도우미
앱의 테스트에서 PortOne 대신 쓸 가짜 게이트웨이입니다. PortOne에 요청하지 않고, 지정한 조회 응답을 돌려주며 호출을 기록합니다.
use Cable8mm\LaravelPortone\Testing\FakePaymentGateway; $gateway = FakePaymentGateway::bind() // 컨테이너의 PaymentGateway로 바인딩 ->payment($paymentId, 'PAID', totalAmount: 10000, cancelledAmount: 0); $user->completePayment($paymentId); $user->refund($paymentId, '구매자 요청', 3000); $gateway->assertLookedUp($paymentId, times: 1); $gateway->assertCancelled($paymentId, fn (string $reason, ?int $amount) => $amount === 3000); $gateway->assertNothingCancelled(); // 취소 요청이 없어야 할 때
payment($id, $status, $totalAmount, $cancelledAmount, $receiptUrl): 결제 ID별 조회 응답.$status는 PortOne 값(PAID,PARTIAL_CANCELLED,CANCELLED,READY,FAILED등)입니다.receiptUrl:을 주면 조회 결과에 영수증 URL이 실려 결제 완료·취소 동기화가receipt_url에 저장합니다. 주지 않으면 영수증 URL이 없는 조회입니다.- 지정하지 않은 결제 ID는 PortOne이 모르는 결제로 봅니다.
lookup()은PAYMENT_NOT_FOUND예외, 만료 확인 조회는foundfalse입니다. failLookup($id, $exception),failCancel($id, $exception): 조회·취소 실패. 실패한 취소 요청도 기록됩니다.cancel()은 기록만 하고 응답을 바꾸지 않습니다. 취소 뒤의 조회 결과가 필요하면payment()로 다시 지정하세요.- 확인 메서드:
assertLookedUp($id, ?times),assertNotLookedUp($id),assertNothingLookedUp(),assertCancelled($id, ?callback),assertNotCancelled($id),assertNothingCancelled(). 기록은lookupCount(?id),cancellations()로 읽습니다. - PHPUnit이 필요하므로 테스트에서만 쓰세요.
서명된 웹훅 보내기
InteractsWithPortOneWebhooks를 테스트 케이스에 넣으면 설정된 PORTONE_WEBHOOK_SECRET으로 서명한 웹훅을 패키지 웹훅 경로로 보냅니다.
서명은 cable8mm/portone-php의 WebhookSigner로 만들므로 실제 웹훅처럼 검증, 이벤트 발송, 취소 동기화를 모두 거칩니다.
use Cable8mm\LaravelPortone\Testing\InteractsWithPortOneWebhooks; class RefundListenerTest extends TestCase { use InteractsWithPortOneWebhooks; public function test_cancelled_webhook(): void { $this->postPortOneWebhook('Transaction.Cancelled', $paymentId, ['cancellationId' => 'c-1'])->assertOk(); } }
본문의 data에는 결제 ID와 PORTONE_STORE_ID가 들어가고, 세 번째 인자가 같은 키를 덮어씁니다.
로컬에서 웹훅 재전송
공개 주소(ngrok 등) 없이 로컬 앱의 웹훅 흐름을 확인할 때 씁니다. 서명한 웹훅을 APP_URL 아래 웹훅 경로로 HTTP 전송하므로 앱이 떠 있어야 합니다.
php artisan portone:webhook-replay Transaction.Cancelled <paymentId> php artisan portone:webhook-replay Transaction.PartialCancelled <paymentId> --data='{"cancellationId":"c-1"}'
transactionId는 PortOne 결제 조회로 가져오므로PORTONE_API_SECRET이 필요합니다.--data의 JSON 객체는data에 더해집니다.- 응답 상태를 출력하며, 2xx가 아니면 실패 코드로 끝납니다.
- 운영(
production) 환경에서는--force없이 실행되지 않습니다.
실서비스 적용 전 확인 사항
검증된 범위
포트원 테스트 채널(NHN KCP), 결제 수단 카드(CARD), 통화 원화(KRW), @portone/browser-sdk 0.1.13에서
사람이 결제창을 직접 조작하는 live 테스트로 확인했습니다.
- 체크아웃 스텁: 주문서 → 결제창 → 결제 완료 → 주문 완료 화면 / 결제창 닫기 →
Error - 서버 검증: 금액·주문명은 서버의 상품에서만 정해지고,
completePayment()가 PortOne 조회로 상태와 금액을 확인 - 전액 취소, 여러 번 나눠 하는 부분 취소, PortOne이 거절한 취소
- 금액 불일치 자동 취소:
completePayment()와 만료 검사 모두 PortOne에서CANCELLED로 바뀜 - 웹훅 서명 검증과
WebhookReceived발송 (ngrok 공개 URL) - 포트원 콘솔에서 한 부분 취소·전액 취소가 웹훅으로 결제 레코드에 반영됨(
PARTIALLY_CANCELLED300원 →CANCELLED1,000원, 이벤트 전에 갱신) portone:webhook-replay로 보낸 서명 웹훅이 앱의 검증을 통과하고 취소 동기화가 실행됨- 결제 대기 건 만료: 결제창을 연 적 없음
PAYMENT_NOT_FOUND, 결제창이 열려 있음READY, 닫음FAILED, 같은 결제 ID로 나중에 결제됨PAID - 만료 확인 결과 이벤트: 뒤늦은 결제
PaymentCompleted, 창 닫기·결제창 미오픈PaymentExpired(source=expiry) - 브라우저 복귀로 확정한 결제에
Transaction.Paid웹훅이 다시 와도PaymentCompleted는 한 번만 발송됨, 웹훅만 온 결제는source=webhook으로 확정됨 - 한 번만 결제되는 모델의 두 번째 결제가 PortOne에서 자동 취소됨
- 결제된 건과 그 취소 건의
receipt_url이 저장됨 - 빌링키(카드) 발급 → 확정 → 빌링키 결제 1회 → 삭제, PortOne에서 삭제한 빌링키의
BillingKey.Deleted웹훅으로 기록이DELETED가 됨, PG가 거절하는 빌링키 결제의 PortOne 응답 - 빌링키 등록 스텁: 발행한 블레이드 화면으로 카드 등록 →
Issued(기록ISSUED) / 결제창 닫기 →Failed, 발행한 React 페이지로 카드 등록 →Issued - React 체크아웃 스텁으로 결제 완료
- 구독(기간
1m): 시작(첫 결제PAID,ACTIVE), 구독이 결제하는 빌링키 삭제 거절, 결제 시각을 앞당긴 갱신 1회(PAID, 다음 기간), 거절되는 갱신 결제 →PAST_DUE(재시도 1일 뒤),PAST_DUE구독의cancel()→ENDED
검증하지 않은 것: 운영(live) 채널, KCP 외 PG, 카드 외 결제 수단(가상계좌·간편결제 등)과 카드 외 빌링키 발급 수단, 원화 외 통화.
결제 수단·통화 바꾸기
발행된 resources/js/portone-checkout.js 맨 위의 상수를 바꿉니다.
const PAYMENT_METHOD = "CARD"; const CURRENCY = "KRW";
바꾸면 위의 검증 범위를 벗어납니다. 특히 가상계좌처럼 결제창을 닫은 뒤에 입금되는 수단은 스텁 흐름
(리다이렉트 복귀 → completed에서 바로 확정)과 만료 규칙이 그 수단에 맞는지 확인되지 않았습니다. 테스트 채널에서
그 수단으로 결제·취소·만료 흐름을 먼저 돌려 보세요.
운영 전환 체크리스트
- 운영 채널의
PORTONE_STORE_ID·PORTONE_CHANNEL_KEY와PORTONE_API_SECRET으로 바꿉니다. - 포트원 콘솔에 웹훅 URL(
https://<도메인>/portone/webhook, 또는PORTONE_WEBHOOK_PATH)을 등록하고PORTONE_WEBHOOK_SECRET을 설정합니다. - Vite
input에resources/js/portone-checkout.js(빌링키 등록 화면을 쓰면resources/js/portone-billing-key.js도)를 넣고npm run build합니다(프론트엔드 빌드). 빌링키 등록 화면을 쓰면 운영 채널의PORTONE_BILLING_CHANNEL_KEY도 설정합니다. - 큐 워커와 스케줄러(
portone:expire-pending,model:prune, 구독을 쓰면portone:charge-subscriptions)를 운영합니다(결제 대기 건 만료와 정리, 구독). - 소액으로 실결제 → 주문 완료 화면 → 부분 취소 → 전액 취소를 직접 해 보고, 웹훅이 도착하는지 확인합니다.
알려진 제약
- 출발 파일은 카드만 제공합니다. 체크아웃과 빌링키 등록 화면(블레이드·React)은 v0.9.0 전까지 카드(
CARD) 결제·카드 등록만 있습니다. - 구독은 기간마다 같은 금액만 결제합니다. 구독 중 금액·기간 변경, 일할 계산, 해지 때 환불은 없습니다. 환불은
refund()로 직접 하세요. - 구독 관리·결제 카드 변경 화면(스텁)은 없습니다.
subscribe()·cancel()·resume()·changeBillingKey()는 앱이 부릅니다(구독). - 환불(취소) 화면은 없습니다. 관리자 화면에서
refund()를 직접 호출하세요. - 같은 초에 만들어진 결제는
payments()결과에서 순서가 정해지지 않습니다. - 같은
webhook-id는 한 번만 처리하지만, PortOne이 같은 사건을 다른webhook-id로 보내면WebhookReceived는 그때마다 발생합니다.WebhookReceived리스너는 여러 번 실행돼도 안전하게 만드세요. 결제·빌링키 이벤트는 레코드가 바뀔 때만 발송되므로 이 문제가 없습니다. - 취소 직후 로컬 저장 실패: PortOne이 취소를 받아들인 뒤 DB 저장이 3번 연속 실패하면 예외가 발생하고,
레코드는 취소 전 상태로 남아 PortOne과 어긋납니다. 이때
refund()를 다시 부르면 취소 요청이 다시 가므로(PortOne이 거절할 것으로 예상), 레코드를 직접 바로잡아야 합니다. - 패키지 명령은 콘솔에서만 등록되므로 웹 요청에서는
Artisan::queue()를 쓰세요.
개발 및 테스트
이 패키지에 기여하거나 live/e2e 테스트를 직접 돌려보려면 docs/를 참고하세요.
docs/CONVENTIONS.md— 명령·CI·PR 체크리스트·코딩 규칙docs/TESTING.md— 단위 테스트와 실제 포트원 연동(live/e2e) 실행법
composer analyse && composer test # 오프라인 검증
라이선스
MIT