결제 (Laravel Cashier Stripe)

번역일: 2026년 7월 2일

결제 (Laravel Cashier Stripe)

소개
Cashier 업그레이드
설치
설정
빠른 시작
- 단일 상품 판매
- 구독 판매
고객
결제 수단
구독
구독 체험 기간
Stripe 웹훅 처리
- 웹훅 이벤트 핸들러 정의
- 웹훅 서명 검증
단건 결제
체크아웃
인보이스
결제 실패 처리
- 결제 확인
강력한 고객 인증 (SCA)
- 추가 확인이 필요한 결제
- 오프세션 결제 알림
Stripe SDK
테스트

소개

Laravel Cashier Stripe는 Stripe의 구독 결제 서비스를 직관적이고 유연하게 사용할 수 있는 인터페이스를 제공합니다. 반복적으로 작성하게 되는 구독 결제 관련 보일러플레이트 코드를 대부분 대신 처리해 줍니다. 기본적인 구독 관리 외에도 쿠폰 적용, 구독 요금제 변경, 구독 "수량" 관리, 구독 취소 유예 기간, 인보이스 PDF 생성 등 다양한 기능을 제공합니다.

Cashier 업그레이드

Cashier를 새 버전으로 업그레이드할 때는 반드시 업그레이드 가이드를 꼼꼼히 확인하세요.

WARNING

브레이킹 체인지를 방지하기 위해 Cashier는 고정된 Stripe API 버전을 사용합니다. Cashier 15는 Stripe API 버전 2023-10-16을 사용합니다. Stripe의 새 기능이나 개선 사항을 활용하기 위해 Cashier 마이너 릴리스에서 Stripe API 버전이 업데이트될 수 있습니다.

설치

Composer로 Cashier 패키지를 설치합니다.

composer require laravel/cashier

패키지 설치 후, vendor:publish Artisan 명령으로 Cashier 마이그레이션 파일을 퍼블리시합니다.

php artisan vendor:publish --tag="cashier-migrations"

그런 다음 마이그레이션을 실행합니다.

php artisan migrate

Cashier 마이그레이션은 users 테이블에 여러 컬럼을 추가하고, 고객의 구독 정보를 저장하기 위한 subscriptions 테이블과 복수 요금제 구독을 위한 subscription_items 테이블을 새로 생성합니다.

필요하다면 vendor:publish 명령으로 Cashier 설정 파일도 퍼블리시할 수 있습니다.

php artisan vendor:publish --tag="cashier-config"

마지막으로, Stripe가 모든 결제 이벤트를 올바르게 처리하도록 Cashier의 웹훅 설정을 완료하세요. 웹훅 설정에 대한 자세한 내용은 웹훅 처리 섹션을 참고하세요.

WARNING

Stripe는 Stripe 고객 식별자를 저장하는 컬럼이 대소문자를 구분하도록 권장합니다. MySQL을 사용하는 경우 stripe_id 컬럼의 콜레이션이 utf8_bin으로 설정되어 있는지 확인하세요. 자세한 내용은 Stripe 공식 문서를 참고하세요.

설정

청구 가능 모델

Cashier를 사용하기 전에 청구 대상이 될 모델에 Billable 트레이트를 추가해야 합니다. 일반적으로 App\Models\User 모델에 추가합니다. 이 트레이트는 구독 생성, 쿠폰 적용, 결제 수단 정보 업데이트 등 다양한 결제 관련 메서드를 제공합니다.

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier는 기본적으로 App\Models\User 클래스를 청구 가능 모델로 사용합니다. 변경이 필요하다면 useCustomerModel 메서드로 다른 모델을 지정할 수 있습니다. 이 메서드는 보통 서비스 프로바이더의 boot 메서드에서 호출합니다.

use App\Models\Cashier\User;
use Laravel\Cashier\Cashier;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

WARNING

App\Models\User가 아닌 다른 모델을 사용하는 경우, Cashier 마이그레이션을 퍼블리시하고 해당 모델의 테이블 이름에 맞게 수정해야 합니다.

API 키

다음으로 애플리케이션의 .env 파일에 Stripe API 키를 설정해야 합니다. Stripe API 키는 Stripe 관리자 콘솔에서 확인할 수 있습니다.

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret

WARNING

STRIPE_WEBHOOK_SECRET 환경 변수가 반드시 설정되어 있어야 합니다. 이 값은 Cashier가 수신하는 웹훅 요청이 실제로 Stripe에서 보낸 것인지 검증하는 데 사용됩니다.

통화 설정

Cashier의 기본 통화는 미국 달러(USD)입니다. .env 파일에서 CASHIER_CURRENCY 환경 변수를 설정하면 기본 통화를 변경할 수 있습니다.

CASHIER_CURRENCY=krw

통화 설정 외에도, 인보이스에 금액을 표시할 때 사용할 로케일도 지정할 수 있습니다. Cashier는 내부적으로 PHP의 NumberFormatter 클래스를 사용하여 통화 형식을 지정합니다.

CASHIER_CURRENCY_LOCALE=ko_KR

WARNING

en 이외의 로케일을 사용하려면 서버에 ext-intl PHP 익스텐션이 설치 및 활성화되어 있어야 합니다.

세금 설정

Stripe Tax를 사용하면 Stripe가 생성하는 모든 인보이스의 세금을 자동으로 계산할 수 있습니다. App\Providers\AppServiceProvider 클래스의 boot 메서드에서 calculateTaxes 메서드를 호출하면 자동 세금 계산이 활성화됩니다.

use Laravel\Cashier\Cashier;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::calculateTaxes();
}

세금 자동 계산이 활성화되면 새로 생성되는 구독과 단건 인보이스 모두에 자동으로 세금이 계산됩니다.

이 기능이 올바르게 동작하려면 고객의 이름, 주소, 세금 ID 등의 청구 정보가 Stripe에 동기화되어 있어야 합니다. Cashier가 제공하는 고객 데이터 동기화와 세금 ID 메서드를 활용할 수 있습니다.

WARNING

단건 결제나 단건 결제 체크아웃에는 세금 자동 계산이 적용되지 않습니다.

로깅

Cashier에서 Stripe 관련 치명적 오류가 발생할 때 사용할 로그 채널을 지정할 수 있습니다. .env 파일에 CASHIER_LOGGER 환경 변수를 설정하면 됩니다.

CASHIER_LOGGER=stack

Stripe API 호출에서 발생하는 예외는 애플리케이션의 기본 로그 채널로 기록됩니다.

커스텀 모델 사용

Cashier 내부적으로 사용하는 모델을 직접 확장하여 사용할 수 있습니다. 원하는 모델 클래스를 만들고 해당 Cashier 모델을 상속하면 됩니다.

use Laravel\Cashier\Subscription as CashierSubscription;

class Subscription extends CashierSubscription
{
    // ...
}

모델을 정의한 후, Laravel\Cashier\Cashier 클래스를 통해 Cashier가 커스텀 모델을 사용하도록 지정합니다. 보통 애플리케이션의 서비스 프로바이더 boot 메서드에서 등록합니다.

use App\Models\Cashier\Subscription;
use App\Models\Cashier\SubscriptionItem;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useSubscriptionItemModel(SubscriptionItem::class);
}

빠른 시작

단일 상품 판매

NOTE

Stripe 체크아웃을 사용하기 전에 Stripe 대시보드에서 가격이 고정된 상품을 먼저 등록해야 합니다. 또한 Cashier 웹훅 처리 설정도 완료해야 합니다.

애플리케이션에서 단일 상품이나 일회성 결제를 제공하는 경우 Cashier를 통해 Stripe 체크아웃으로 고객을 안내할 수 있습니다. 고객이 결제 버튼을 클릭하면 Stripe의 체크아웃 페이지로 이동해 결제를 완료하게 됩니다.

use Illuminate\Http\Request;

Route::get('/checkout', function (Request $request) {
    $stripePriceId = 'price_deluxe_album';

    $quantity = 1;

    return $request->user()->checkout([$stripePriceId => $quantity], [
        'success_url' => route('checkout-success'),
        'cancel_url' => route('checkout-cancel'),
    ]);
})->name('checkout');

Route::view('/checkout/success', 'checkout.success')->name('checkout-success');
Route::view('/checkout/cancel', 'checkout.cancel')->name('checkout-cancel');

위 예제에서 checkout 메서드는 고객을 Stripe 체크아웃 페이지로 리다이렉트합니다. 결제 성공 또는 취소 후에는 success_url과 cancel_url로 각각 이동합니다.

필요하다면 checkout 메서드에 Stripe가 지원하는 체크아웃 세션 옵션을 추가로 전달할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/checkout', function (Request $request) {
    return $request->user()->checkout(['price_deluxe_album' => 1], [
        'success_url' => route('checkout-success'),
        'cancel_url' => route('checkout-cancel'),
        'allow_promotion_codes' => true,
    ]);
})->name('checkout');

WARNING

checkout 메서드 내부적으로 고객을 Stripe에 생성하고 Customer ID를 로컬 데이터베이스에 저장합니다. 결제가 완료된 후에는 Stripe 대시보드에서 주문 및 결제 내역을 확인할 수 있습니다.

체크아웃 결과 화면 제공

체크아웃 완료 후 보여줄 화면은 직접 구성할 수 있습니다. 예를 들어 아래와 같이 간단한 Blade 뷰를 사용할 수 있습니다.

<html>
    <head>
        <title>결제 완료</title>
    </head>
    <body>
        <h1>결제가 완료되었습니다!</h1>
        <p>구매해 주셔서 감사합니다.</p>
    </body>
</html>

Stripe 체크아웃으로 생성된 주문 객체(Checkout\Session)는 다양한 정보를 포함합니다. 결제 완료 라우트에서 체크아웃 세션을 조회하여 고객에게 필요한 정보를 보여줄 수 있습니다.

use Illuminate\Http\Request;
use Laravel\Cashier\Cashier;

Route::get('/checkout/success', function (Request $request) {
    $sessionId = $request->get('session_id');

    if ($sessionId === null) {
        return;
    }

    $session = Cashier::stripe()->checkout->sessions->retrieve($sessionId);

    if ($session->payment_status !== 'paid') {
        throw new \Exception('결제가 완료되지 않았습니다.');
    }

    $orderId = $session['metadata']['order_id'] ?? null;

    // 주문 처리 로직...
})->name('checkout-success');

Stripe 체크아웃 세션 객체의 전체 데이터에 대한 내용은 Stripe 공식 문서를 참고하세요.

구독 판매

NOTE

Stripe 체크아웃을 사용하기 전에 Stripe 대시보드에서 가격이 고정된 상품을 먼저 등록해야 합니다. 또한 Cashier 웹훅 처리 설정도 완료해야 합니다.

애플리케이션에서 구독 서비스를 제공하는 경우에도 Cashier와 Stripe 체크아웃을 함께 사용할 수 있습니다. 아래 예제를 참고하세요.

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->checkout([
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

구독 체크아웃 완료 후에는 Cashier가 웹훅을 통해 구독 상태를 자동으로 업데이트합니다. 웹훅 설정이 올바르게 되어 있어야 구독 상태가 정확히 반영됩니다.

구독 생성이 완료되면 subscribed 메서드로 구독 여부를 확인할 수 있습니다.

@if ($user->subscribed('default'))
    <p>현재 구독 중입니다.</p>
@endif

구독 여부에 따라 특정 라우트나 컨트롤러에 대한 접근을 제어하는 미들웨어도 손쉽게 만들 수 있습니다.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserIsSubscribed
{
    /**
     * 요청을 처리합니다.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user() && ! $request->user()->subscribed('default')) {
            // 구독하지 않은 사용자는 리다이렉트합니다...
            return redirect('/billing');
        }

        return $next($request);
    }
}

이미 체험 기간 중인 사용자가 구독을 완료하면 Cashier가 자동으로 체험 기간을 종료하고 정식 구독을 시작합니다. 구독이 완료된 후 구독 요금제 변경, 취소 등의 관리 기능도 모두 Cashier를 통해 처리할 수 있습니다.

// 구독 요금제 변경...
$user->subscription('default')->swap('price_premium');

// 구독 취소...
$user->subscription('default')->cancel();

구독 관리에 대한 자세한 내용은 구독 섹션을 참고하세요.

고객

고객 조회

Cashier::findBillable 메서드를 사용하면 Stripe Customer ID로 고객을 조회할 수 있습니다. 이 메서드는 청구 가능 모델 인스턴스를 반환합니다.

use Laravel\Cashier\Cashier;

$user = Cashier::findBillable($stripeId);

고객 생성

구독을 시작하지 않고 Stripe에 고객만 먼저 생성하고 싶을 때가 있습니다. 이럴 때 createAsStripeCustomer 메서드를 사용할 수 있습니다.

$stripeCustomer = $user->createAsStripeCustomer();

Stripe에 고객이 생성된 이후에 구독을 시작할 수 있습니다. Stripe API가 지원하는 추가 파라미터를 배열로 전달할 수도 있습니다.

$stripeCustomer = $user->createAsStripeCustomer($options);

이미 Stripe 고객으로 등록된 경우 반환하고, 등록되지 않은 경우 새로 생성하려면 createOrGetStripeCustomer 메서드를 사용합니다.

$stripeCustomer = $user->createOrGetStripeCustomer();

고객 정보 수정

Stripe의 고객 정보를 직접 업데이트하고 싶을 때 updateStripeCustomer 메서드를 사용합니다. Stripe API가 지원하는 고객 업데이트 옵션을 배열로 전달합니다.

$stripeCustomer = $user->updateStripeCustomer($options);

잔액

Stripe는 고객의 잔액(credit/debit)을 관리할 수 있습니다. 잔액은 새 인보이스에서 자동으로 적용됩니다. 고객의 총 잔액을 조회하려면 balance 메서드를 사용합니다. 이 메서드는 통화에 맞게 포맷된 문자열을 반환합니다.

$balance = $user->balance();

잔액을 충전하려면 creditBalance 메서드를 사용합니다. 설명(description)은 선택 사항입니다.

$user->creditBalance(500, '프리미엄 서비스 크레딧');

잔액을 차감하려면 debitBalance 메서드를 사용합니다.

$user->debitBalance(300, '잘못된 결제 환불');

applyBalance 메서드는 고객의 새 잔액 거래 내역을 생성합니다. 해당 거래 내역은 balanceTransactions 메서드로 조회할 수 있어, 고객에게 크레딧/디비트 내역을 보여줄 때 유용합니다.

// 모든 거래 내역 조회...
$transactions = $user->balanceTransactions();

foreach ($transactions as $transaction) {
    // 거래 금액 (포맷된 문자열)...
    $amount = $transaction->amount();

    // 관련 인보이스 조회 (있는 경우)...
    $invoice = $transaction->invoice();
}

세금 ID

Cashier는 고객의 세금 ID를 관리하는 기능을 제공합니다. 예를 들어, taxIds 메서드로 Stripe에 등록된 모든 세금 ID를 컬렉션으로 조회할 수 있습니다.

$taxIds = $user->taxIds();

식별자로 특정 세금 ID를 조회할 수도 있습니다.

$taxId = $user->findTaxId('txi_belgium');

새 세금 ID를 추가하려면 createTaxId 메서드에 유효한 타입 값을 전달합니다.

$taxId = $user->createTaxId('kr_brn', '123-45-67890');

createTaxId 메서드는 Stripe API를 통해 즉시 세금 ID를 등록합니다. 더 이상 필요하지 않은 세금 ID는 deleteTaxId 메서드로 삭제할 수 있습니다.

$user->deleteTaxId('txi_korea');

Stripe와 고객 데이터 동기화

일반적으로 애플리케이션에서 사용자 이름, 이메일 주소 등의 정보가 변경될 때 Stripe에도 동일하게 업데이트해야 합니다. 이렇게 하면 Stripe의 고객 정보가 애플리케이션과 항상 동기화됩니다.

자동으로 동기화하려면 청구 가능 모델에 customer.updated 이벤트에 반응하는 이벤트 리스너를 등록하면 됩니다. 예를 들어 User 모델의 updated 이벤트를 통해 자동으로 Stripe 정보를 업데이트할 수 있습니다.

use function Illuminate\Events\queueable;

protected static function booted(): void
{
    static::updated(queueable(function ($customer) {
        if ($customer->hasStripeId()) {
            $customer->syncStripeCustomerDetails();
        }
    }));
}

이제 고객 모델이 업데이트될 때마다 Stripe의 고객 정보도 자동으로 갱신됩니다. 주의할 점은 초기 고객 생성 시에도 Stripe에 고객 정보가 동기화되므로, 생성 시점에도 동기화 처리를 고려하세요.

Stripe에 동기화할 컬럼을 커스터마이즈하려면 Cashier의 stripeName, stripeEmail, stripePhone, stripeAddress, stripePreferredLocales 메서드를 오버라이드합니다.

/**
 * Stripe에 동기화할 고객 이름을 반환합니다.
 */
public function stripeName(): string|null
{
    return $this->company_name;
}

/**
 * Stripe에 동기화할 고객 이메일을 반환합니다.
 */
public function stripeEmail(): string|null
{
    return $this->email;
}

/**
 * Stripe에 동기화할 고객 전화번호를 반환합니다.
 */
public function stripePhone(): string|null
{
    return $this->phone_number;
}

/**
 * Stripe에 동기화할 고객 주소를 반환합니다.
 */
public function stripeAddress(): array|null
{
    return [
        'city' => $this->city,
        'country' => $this->country,
        'line1' => $this->line1,
        'line2' => $this->line2,
        'postal_code' => $this->postal_code,
        'state' => $this->state,
    ];
}

/**
 * Stripe에 동기화할 고객 선호 로케일을 반환합니다.
 */
public function stripePreferredLocales(): array|null
{
    return [$this->preferred_locale];
}

NOTE

Stripe Tax를 사용하는 경우 stripeAddress가 반드시 올바르게 반환되어야 합니다.

결제 포털

Stripe는 고객이 구독 관리, 결제 수단 변경, 인보이스 확인 등을 직접 할 수 있는 결제 포털을 제공합니다. 컨트롤러나 라우트에서 redirectToBillingPortal 메서드를 호출하여 고객을 포털로 안내할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('dashboard'));
});

기본적으로 포털 이용을 마치면 Cashier가 자동으로 route('home')으로 리다이렉트합니다. 다른 URL로 돌아오게 하려면 redirectToBillingPortal 메서드에 URL을 인자로 전달하세요.

결제 포털로의 리다이렉션 대신 URL만 가져오려면 billingPortalUrl 메서드를 사용합니다.

$url = $request->user()->billingPortalUrl(route('dashboard'));

결제 수단

결제 수단 저장

Stripe로 구독을 생성하거나 단건 결제를 처리하려면 결제 수단을 저장하고 Stripe에서 해당 ID를 가져와야 합니다. 구독 결제와 단건 결제는 저장 방식이 다르므로, 두 가지를 구분하여 살펴보겠습니다.

구독 결제를 위한 결제 수단 저장

나중에 사용하기 위해 고객의 신용카드 정보를 저장할 때는 Stripe의 "Setup Intent" API를 사용합니다. Setup Intent는 Stripe에게 고객의 결제 수단 정보를 저장하겠다는 의사를 알립니다. Cashier의 Billable 트레이트에는 Setup Intent를 쉽게 생성하는 createSetupIntent 메서드가 포함되어 있습니다. 결제 수단 저장 폼을 렌더링하는 라우트나 컨트롤러에서 이 메서드를 호출하세요.

return view('update-payment-method', [
    'intent' => $user->createSetupIntent(),
]);

Setup Intent를 뷰에 전달한 뒤, Stripe.js를 사용해 결제 수단 입력 UI를 구성합니다. 예를 들어 아래와 같이 Blade 뷰에서 사용할 수 있습니다.

<input id="card-holder-name" type="text">

<!-- Stripe Elements 플레이스홀더 -->
<div id="card-element"></div>

<button id="card-button" data-secret="{{ $intent->client_secret }}">
    결제 수단 저장
</button>

이제 Stripe.js 라이브러리를 이용해 Stripe Elements를 초기화하고 카드 정보를 수집합니다.

<script src="https://js.stripe.com/v3/"></script>

<script>
    const stripe = Stripe('stripe-public-key');

    const elements = stripe.elements();
    const cardElement = elements.create('card');

    cardElement.mount('#card-element');

    const cardHolderName = document.getElementById('card-holder-name');
    const cardButton = document.getElementById('card-button');
    const clientSecret = cardButton.dataset.secret;

    cardButton.addEventListener('click', async (e) => {
        const { setupIntent, error } = await stripe.confirmCardSetup(
            clientSecret, {
                payment_method: {
                    card: cardElement,
                    billing_details: { name: cardHolderName.value }
                }
            }
        );

        if (error) {
            // 오류 메시지를 사용자에게 보여줍니다...
        } else {
            // 카드 정보가 성공적으로 저장되었습니다...
        }
    });
</script>

Stripe에서 카드 정보가 확인되면 setupIntent.payment_method 값(결제 수단 ID)을 애플리케이션 서버로 전달하여 사용자에게 저장합니다.

$paymentMethod = $request->input('payment_method');

$user->addPaymentMethod($paymentMethod);

NOTE

Setup Intent와 결제 수단 저장에 대한 자세한 내용은 Stripe 공식 문서를 참고하세요.

단건 결제를 위한 결제 수단 저장

단건 결제만을 목적으로 결제 수단을 저장하는 경우에는 Setup Intent가 필요 없습니다. Stripe와 Cashier를 이용한 단건 결제 방법에 대한 자세한 내용은 단건 결제 섹션을 참고하세요.

결제 수단 조회

청구 가능 모델 인스턴스의 paymentMethods 메서드는 Laravel\Cashier\PaymentMethod 인스턴스 컬렉션을 반환합니다.

$paymentMethods = $user->paymentMethods();

기본적으로 이 메서드는 모든 타입의 결제 수단을 반환합니다. 특정 타입만 조회하려면 type 값을 인자로 전달합니다.

$paymentMethods = $user->paymentMethods('sepa_debit');

기본 결제 수단을 조회하려면 defaultPaymentMethod 메서드를 사용합니다.

$paymentMethod = $user->defaultPaymentMethod();

findPaymentMethod 메서드를 사용하면 특정 결제 수단 ID로 조회할 수 있습니다.

$paymentMethod = $user->findPaymentMethod($paymentMethodId);

결제 수단 존재 여부 확인

청구 가능 모델에 기본 결제 수단이 등록되어 있는지 확인하려면 hasDefaultPaymentMethod 메서드를 사용합니다.

if ($user->hasDefaultPaymentMethod()) {
    // ...
}

하나 이상의 결제 수단이 등록되어 있는지 확인하려면 hasPaymentMethod 메서드를 사용합니다.

if ($user->hasPaymentMethod()) {
    // ...
}

기본 결제 수단 변경

updateDefaultPaymentMethod 메서드를 사용하면 고객의 기본 결제 수단을 변경할 수 있습니다. 이 메서드는 Stripe 결제 수단 ID를 인자로 받으며, 고객의 Stripe 기본 결제 수단도 함께 업데이트합니다.

$user->updateDefaultPaymentMethod($paymentMethod);

Stripe의 기본 결제 수단 정보를 로컬 데이터베이스와 동기화하려면 updateDefaultPaymentMethodFromStripe 메서드를 사용합니다.

$user->updateDefaultPaymentMethodFromStripe();

WARNING

고객의 기본 결제 수단은 구독 청구 및 새 인보이스 생성에만 사용됩니다. Stripe의 제한으로 인해, 단건 결제에는 기본 결제 수단을 사용할 수 없습니다.

결제 수단 추가

새 결제 수단을 추가하려면 청구 가능 모델의 addPaymentMethod 메서드에 Stripe 결제 수단 ID를 전달합니다.

$user->addPaymentMethod($paymentMethod);

NOTE

결제 수단 ID를 얻는 방법에 대해서는 결제 수단 저장 섹션을 참고하세요.

결제 수단 삭제

결제 수단을 삭제하려면 삭제할 Laravel\Cashier\PaymentMethod 인스턴스의 delete 메서드를 호출합니다.

$paymentMethod->delete();

deletePaymentMethod 메서드를 사용하면 청구 가능 모델에서 특정 결제 수단을 삭제할 수 있습니다.

$user->deletePaymentMethod('pm_visa');

deletePaymentMethods 메서드를 사용하면 고객의 모든 결제 수단을 삭제합니다.

$user->deletePaymentMethods();

특정 타입의 결제 수단만 삭제하려면 타입을 인자로 전달합니다.

$user->deletePaymentMethods('sepa_debit');

WARNING

현재 활성 구독이 있는 고객의 결제 수단을 삭제하면 구독 갱신 시 결제가 실패할 수 있습니다. 구독이 있는 경우에는 결제 수단 삭제 전 사용자에게 반드시 안내하세요.

구독을 사용하면 고객에게 정기 결제 서비스를 제공할 수 있습니다. Cashier로 관리하는 Stripe 구독은 복수의 요금제를 가질 수 있고, 구독 수량 관리, 체험 기간 등 다양한 기능을 지원합니다.

구독 생성

구독을 생성하려면 먼저 청구 가능 모델(일반적으로 App\Models\User)의 인스턴스를 가져옵니다. 그런 다음 newSubscription 메서드로 구독을 생성할 수 있습니다.

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription(
        'default', 'price_monthly'
    )->create($request->paymentMethodId);

    // ...
});

newSubscription 메서드의 첫 번째 인자는 구독의 내부 이름입니다. 애플리케이션에서 구독이 하나뿐이라면 default나 primary로 지정하면 됩니다. 이 이름은 내부적으로만 사용되며 사용자에게 노출되지 않습니다. 또한 공백이 포함되어서는 안 되며, 구독 생성 후 변경할 수 없습니다. 두 번째 인자는 Stripe에서 사용자가 구독할 요금제의 가격 ID입니다.

create 메서드는 Stripe 결제 수단 ID 또는 Stripe PaymentMethod 객체를 받아 구독을 시작하고, 데이터베이스에 고객의 Stripe Customer ID 및 관련 결제 정보를 업데이트합니다.

WARNING

구독 create 메서드에 결제 수단 ID를 직접 전달하면 자동으로 해당 결제 수단이 저장된 결제 수단 목록에 추가됩니다.

인보이스 이메일을 통한 반복 결제 수집

고객의 결제 수단을 직접 저장하는 대신, Stripe이 고객에게 인보이스 이메일을 발송하도록 설정할 수도 있습니다. 이 방식에서는 고객이 이메일에 포함된 링크를 통해 직접 결제합니다. 인보이스를 통한 결제는 사전에 결제 수단을 등록할 필요가 없습니다.

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice();

인보이스 발송 후 고객이 결제를 완료해야 하는 기한은 days_until_due 옵션으로 설정합니다.

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice([], [
    'days_until_due' => 30,
]);

수량 지정

구독 생성 시 요금제의 특정 수량을 지정하려면 구독 빌더에서 quantity 메서드를 체이닝합니다.

$user->newSubscription('default', 'price_monthly')
     ->quantity(5)
     ->create($paymentMethod);

추가 옵션 전달

Stripe API가 지원하는 추가 옵션이 필요하다면 create 메서드의 두 번째 인자로 배열을 전달할 수 있습니다.

$user->newSubscription('default', 'price_monthly')->create($paymentMethod, [
    'email' => $email,
]);

Stripe 구독 객체에 메타데이터를 추가하려면 세 번째 인자로 배열을 전달합니다.

$user->newSubscription('default', 'price_monthly')->create($paymentMethod, [], [
    'metadata' => ['note' => '한국 고객 구독'],
]);

쿠폰 적용

구독 생성 시 쿠폰을 적용하려면 withCoupon 또는 withPromotionCode 메서드를 사용합니다.

$user->newSubscription('default', 'price_monthly')
     ->withCoupon('code')
     ->create($paymentMethod);

또는 Stripe 프로모션 코드를 적용하려면 withPromotionCode 메서드를 사용합니다. 프로모션 코드 ID는 고객에게 보여주는 코드가 아닌 Stripe API에서 사용하는 ID입니다.

$user->newSubscription('default', 'price_monthly')
     ->withPromotionCode('promo_code_id')
     ->create($paymentMethod);

고객에게 보여주는 프로모션 코드로 Stripe 프로모션 코드 ID를 얻으려면 findPromotionCode 메서드를 사용합니다.

// 프로모션 코드(고객용 코드)로 ID 조회...
$promotionCode = $user->findPromotionCode('SUMMER');

// 활성화된 프로모션 코드만 조회...
$promotionCode = $user->findActivePromotionCode('SUMMER');

위 예에서 반환된 $promotionCode 객체는 Laravel\Cashier\PromotionCode 인스턴스로, 내부적으로 Stripe PromotionCode 객체를 래핑합니다. 쿠폰 정보는 coupon 메서드로 접근할 수 있습니다.

$coupon = $promotionCode->coupon();

고객이 아닌 전체 적용 가능한 프로모션 코드를 조회하려면 아래 메서드를 사용합니다.

$promotionCode = Cashier::findPromotionCode('SUMMER');

$promotionCode = Cashier::findActivePromotionCode('SUMMER');

구독 추가 옵션

Stripe에서 지원하는 체험 기간을 설정하려면 trialDays 메서드를 사용합니다.

$user->newSubscription('default', 'price_monthly')
     ->trialDays(10)
     ->create($paymentMethod);

구독 상태 확인

구독이 생성되면 다양한 편의 메서드로 구독 상태를 쉽게 확인할 수 있습니다.

subscribed 메서드는 현재 활성 구독(체험 기간 포함)이 있으면 true를 반환합니다.

if ($user->subscribed('default')) {
    // ...
}

이를 활용해 미들웨어를 구성하면 구독 여부에 따라 라우트 및 컨트롤러 접근을 제어할 수 있습니다.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserIsSubscribed
{
    /**
     * 요청을 처리합니다.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user() && ! $request->user()->subscribed('default')) {
            // 구독하지 않은 사용자 처리...
            return redirect('/billing');
        }

        return $next($request);
    }
}

사용자가 현재 체험 기간 중인지 확인하려면 onTrial 메서드를 사용합니다. 이 메서드는 체험 기간 중임을 사용자에게 알리는 배너를 표시하는 등의 용도로 유용합니다.

if ($user->subscription('default')->onTrial()) {
    // ...
}

subscribedToProduct 메서드는 주어진 Stripe 상품 ID로 구독 여부를 확인합니다.

if ($user->subscribedToProduct('prod_premium', 'default')) {
    // ...
}

subscribedToPrice 메서드는 특정 가격 ID로 구독 여부를 확인합니다.

if ($user->subscribedToPrice('price_monthly', 'default')) {
    // ...
}

recurring 메서드는 현재 유료 구독 중(체험 기간이 아닌)인지 확인합니다.

if ($user->subscription('default')->recurring()) {
    // ...
}

WARNING

동일한 이름의 구독이 두 개 이상 있을 경우, subscription 메서드는 항상 가장 최근 구독을 반환합니다.

구독 취소 상태 확인

사용자가 한번 구독 취소를 요청했지만 아직 "유예 기간" 중인 경우를 확인하려면 onGracePeriod 메서드를 사용합니다.

if ($user->subscription('default')->onGracePeriod()) {
    // ...
}

구독이 완전히 취소되었는지 확인하려면 canceled 메서드를 사용합니다.

if ($user->subscription('default')->canceled()) {
    // ...
}

구독이 완전히 만료되었는지 확인하려면 ended 메서드를 사용합니다.

if ($user->subscription('default')->ended()) {
    // ...
}

Stripe 구독 상태 직접 확인

Stripe에서 제공하는 구독 상태값을 직접 확인하고 싶다면 status 속성이나 stripeStatus 메서드를 사용합니다.

$stripeStatus = $user->subscription('default')->status;

Stripe가 정의하는 구독 상태값 목록은 공식 문서에서 확인할 수 있습니다.

active, past_due, incomplete, trialing, canceled 등 Stripe 구독 상태값을 직접 확인하는 메서드도 제공합니다.

if ($user->subscription('default')->active()) {
    // ...
}

if ($user->subscription('default')->pastDue()) {
    // ...
}

if ($user->subscription('default')->trialing()) {
    // ...
}

요금제 변경

구독을 생성한 후 다른 요금제로 변경하고 싶다면 swap 메서드에 Stripe 가격 ID를 전달합니다.

use App\Models\User;

$user = App\Models\User::find(1);

$user->subscription('default')->swap('price_yearly');

체험 기간 중인 경우에도 체험 기간을 유지하면서 요금제를 변경할 수 있습니다. 또한 수량이 있는 구독의 경우 수량도 유지됩니다.

즉시 인보이스를 발행하여 요금제를 변경하려면 swapAndInvoice 메서드를 사용합니다.

$user = App\Models\User::find(1);

$user->subscription('default')->swapAndInvoice('price_yearly');

비례 배분(Proration) 설정

기본적으로 Stripe는 요금제 변경 시 금액을 비례 배분합니다. 비례 배분 없이 요금제를 변경하려면 noProrate 메서드를 체이닝합니다.

$user->subscription('default')->noProrate()->swap('price_yearly');

구독 비례 배분에 대한 자세한 내용은 Stripe 공식 문서를 참고하세요.

WARNING

swapAndInvoice 전에 noProrate를 사용해도 비례 배분에 영향을 주지 않습니다. 인보이스는 항상 발행됩니다.

구독 수량

구독에 "수량" 개념이 있는 경우(예: 사용자 수에 따라 월 ₩10,000씩 청구) incrementQuantity와 decrementQuantity 메서드로 수량을 조정할 수 있습니다.

use App\Models\User;

$user = App\Models\User::find(1);

$user->subscription('default')->incrementQuantity();

// 현재 수량에 5를 추가합니다...
$user->subscription('default')->incrementQuantity(5);

$user->subscription('default')->decrementQuantity();

// 현재 수량에서 5를 차감합니다...
$user->subscription('default')->decrementQuantity(5);

특정 수량으로 직접 설정하려면 updateQuantity 메서드를 사용합니다.

$user->subscription('default')->updateQuantity(10);

비례 배분 없이 수량을 변경하려면 noProrate 메서드를 체이닝합니다.

$user->subscription('default')->noProrate()->updateQuantity(10);

구독 수량에 대한 자세한 내용은 Stripe 공식 문서를 참고하세요.

복수 상품 구독

복수 상품 구독을 사용하면 하나의 구독에 여러 요금제를 연결할 수 있습니다. 예를 들어 기본 요금제에 추가 기능 요금제를 함께 구독하는 방식입니다.

use App\Models\User;

$user = App\Models\User::find(1);

$user->newSubscription('default', [
    'price_monthly',
    'price_chat',
])->create($paymentMethod);

위 예에서 default 구독에 두 가지 요금제가 모두 포함됩니다. 각 요금제는 청구 주기가 동일해야 합니다.

구독에 포함된 요금제를 변경하려면 swap 메서드를 사용합니다. swap 메서드에 교체할 가격 ID들을 배열로 전달하면 해당 요금제들로 교체됩니다. 기존에 없던 요금제는 추가되고, 배열에 포함되지 않은 요금제는 제거됩니다.

$user->subscription('default')->swap(['price_yearly', 'price_chat']);

특정 요금제만 추가하거나 제거할 수도 있습니다.

// 새 요금제 추가...
$user->subscription('default')->addPrice('price_chat');

// 요금제 추가와 동시에 인보이스 발행...
$user->subscription('default')->addPriceAndInvoice('price_chat');

// 특정 수량으로 요금제 추가...
$user->subscription('default')->addPrice('price_chat', ['quantity

<h1 id="changing-prices">결제 (Laravel Cashier Stripe)</h1>

<h2 id="prorations">소개</h2>

[Laravel Cashier Stripe](https://github.com/laravel/cashier-stripe)는 [Stripe](https://stripe.com)의 구독 결제 서비스를 간결하고 유창한 인터페이스로 제공합니다. 구독 결제에 필요한 반복적인 보일러플레이트 코드를 대부분 처리해 주기 때문에, 개발자는 핵심 비즈니스 로직에만 집중할 수 있습니다. 기본적인 구독 관리 외에도 쿠폰 적용, 구독 플랜 변경, 구독 수량(quantity) 관리, 해지 유예 기간(grace period) 설정, 인보이스 PDF 생성 등의 기능을 제공합니다.

<h1 id="subscription-quantity">결제 (Laravel Cashier Stripe)</h1>

<h2 id="quantities-for-subscription-with-multiple-products">Cashier 업그레이드</h2>

새 버전의 Cashier로 업그레이드할 때는 반드시 [업그레이드 가이드](https://github.com/laravel/cashier-stripe/blob/master/UPGRADE.md)를 꼼꼼히 확인하세요.

> [!WARNING]
> 예기치 않은 변경을 방지하기 위해 Cashier는 고정된 Stripe API 버전을 사용합니다. Cashier 15는 Stripe API 버전 `2023-10-16`을 사용하며, Stripe의 새로운 기능과 개선 사항을 반영하기 위해 마이너 릴리즈 시 API 버전이 업데이트될 수 있습니다.

<h1 id="subscriptions-with-multiple-products">결제 (Laravel Cashier Stripe)</h1>

<h2 id="swapping-prices">설치</h2>

먼저 Composer 패키지 매니저를 사용해 Stripe용 Cashier 패키지를 설치합니다:

```shell
composer require laravel/cashier

설치가 완료되면 vendor:publish Artisan 명령어로 Cashier의 마이그레이션 파일을 퍼블리시합니다:

php artisan vendor:publish --tag="cashier-migrations"

이후 데이터베이스 마이그레이션을 실행합니다:

php artisan migrate

마이그레이션이 실행되면 users 테이블에 여러 컬럼이 추가됩니다. 또한 고객의 구독 정보를 저장하는 subscriptions 테이블과, 복수 요금제를 지원하는 subscription_items 테이블이 새로 생성됩니다.

필요에 따라 아래 명령어로 Cashier의 설정 파일도 퍼블리시할 수 있습니다:

php artisan vendor:publish --tag="cashier-config"

마지막으로, Stripe에서 발생하는 모든 이벤트를 Cashier가 올바르게 처리할 수 있도록 Cashier의 웹훅 설정을 반드시 완료하세요.

WARNING

Stripe는 Stripe 식별자를 저장하는 컬럼에 대소문자를 구분하는 콜레이션(case-sensitive collation) 사용을 권장합니다. MySQL을 사용하는 경우, stripe_id 컬럼의 콜레이션을 utf8_bin으로 설정해야 합니다. 자세한 내용은 Stripe 공식 문서를 참고하세요.

설정

Billable 모델

Cashier를 사용하려면 먼저 결제 대상이 되는 모델에 Billable 트레이트를 추가해야 합니다. 일반적으로 App\Models\User 모델에 추가합니다. 이 트레이트는 구독 생성, 쿠폰 적용, 결제 수단 변경 등 자주 사용하는 결제 관련 메서드를 제공합니다:

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier는 기본적으로 Laravel이 제공하는 App\Models\User 클래스를 Billable 모델로 간주합니다. 다른 모델을 사용하려면 AppServiceProvider의 boot 메서드에서 useCustomerModel 메서드로 지정합니다:

use App\Models\Cashier\User;
use Laravel\Cashier\Cashier;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

WARNING

Laravel 기본 App\Models\User 모델 외의 모델을 사용한다면, Cashier 마이그레이션을 퍼블리시한 뒤 해당 모델의 테이블명에 맞게 수정해야 합니다.

API 키 설정

다음으로 애플리케이션의 .env 파일에 Stripe API 키를 설정합니다. Stripe API 키는 Stripe 대시보드에서 확인할 수 있습니다:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret

WARNING

STRIPE_WEBHOOK_SECRET 환경 변수는 반드시 설정해야 합니다. 이 값은 수신된 웹훅 요청이 실제로 Stripe에서 보낸 것인지 검증하는 데 사용됩니다.

통화 설정

Cashier의 기본 통화는 미국 달러(USD)입니다. 한국 원화(KRW) 등 다른 통화를 사용하려면 .env 파일에서 CASHIER_CURRENCY 환경 변수를 지정합니다:

CASHIER_CURRENCY=krw

통화와 함께, 인보이스에 금액을 표시할 때 사용할 로케일도 지정할 수 있습니다. Cashier는 내부적으로 PHP의 NumberFormatter 클래스를 활용해 통화 형식을 처리합니다:

CASHIER_CURRENCY_LOCALE=ko_KR

WARNING

en 외의 로케일을 사용하려면 서버에 ext-intl PHP 익스텐션이 설치 및 활성화되어 있어야 합니다.

세금 설정

Stripe Tax를 활용하면 Stripe가 생성하는 모든 인보이스에 대해 세금을 자동으로 계산할 수 있습니다. App\Providers\AppServiceProvider의 boot 메서드에서 calculateTaxes 메서드를 호출해 이 기능을 활성화합니다:

use Laravel\Cashier\Cashier;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::calculateTaxes();
}

자동 세금 계산을 활성화하면 이후 생성되는 신규 구독과 단건 인보이스 모두에 세금이 자동 적용됩니다.

이 기능이 올바르게 동작하려면 고객의 이름, 주소, 세금 ID 등 결제 정보가 Stripe에 동기화되어 있어야 합니다. Cashier가 제공하는 고객 데이터 동기화 및 세금 ID 관련 메서드를 활용하세요.

로깅

Cashier는 치명적인 Stripe 오류를 로깅할 때 사용할 로그 채널을 별도로 지정할 수 있습니다. .env 파일에 CASHIER_LOGGER 환경 변수를 정의하면 됩니다:

CASHIER_LOGGER=stack

Stripe API 호출 중 발생하는 예외는 애플리케이션의 기본 로그 채널을 통해 기록됩니다.

커스텀 모델 사용

Cashier가 내부적으로 사용하는 모델을 직접 확장할 수 있습니다. 커스텀 모델을 정의한 뒤 해당 Cashier 모델을 상속하면 됩니다:

use Laravel\Cashier\Subscription as CashierSubscription;

class Subscription extends CashierSubscription
{
    // 커스텀 로직 추가
}

모델을 정의한 후에는 AppServiceProvider의 boot 메서드에서 Cashier에 커스텀 모델을 등록합니다:

use App\Models\Cashier\Subscription;
use App\Models\Cashier\SubscriptionItem;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useSubscriptionItemModel(SubscriptionItem::class);
}

결제 (Laravel Cashier Stripe)

빠른 시작

단일 상품 판매

NOTE

Stripe Checkout을 사용하기 전에, Stripe 대시보드에서 고정 가격이 설정된 상품(Product)을 먼저 등록해야 합니다. 또한 Cashier의 웹훅 처리도 설정해 두어야 합니다.

결제 기능을 직접 구현하는 일은 생각보다 복잡하게 느껴질 수 있습니다. 하지만 Cashier와 Stripe Checkout을 함께 사용하면, 견고하고 현대적인 결제 플로우를 손쉽게 구축할 수 있습니다.

정기 구독이 아닌 일회성 상품 판매에는 Cashier의 checkout 메서드를 사용합니다. 이 메서드는 고객을 Stripe Checkout 페이지로 리디렉션하고, 결제가 완료되면 애플리케이션 내의 지정된 성공 URL로 다시 돌아오게 합니다.

use Illuminate\Http\Request;

Route::get('/checkout', function (Request $request) {
    $stripePriceId = 'price_deluxe_album';

    $quantity = 1;

    return $request->user()->checkout([$stripePriceId => $quantity], [
        'success_url' => route('checkout-success'),
        'cancel_url' => route('checkout-cancel'),
    ]);
})->name('checkout');

Route::view('/checkout/success', 'checkout.success')->name('checkout-success');
Route::view('/checkout/cancel', 'checkout.cancel')->name('checkout-cancel');

checkout 메서드에 전달하는 첫 번째 인자는 Stripe의 가격 식별자(price ID) 입니다. Stripe에서 "가격(price)"이란 특정 상품에 설정된 판매 단가를 의미합니다.

checkout 메서드는 필요한 경우 Stripe에 고객을 자동으로 생성하고, 해당 Stripe 고객 레코드를 애플리케이션 데이터베이스의 사용자와 연결합니다. 결제 세션이 완료되면 고객은 성공 또는 취소 페이지로 리디렉션되며, 여기서 적절한 안내 메시지를 표시할 수 있습니다.

Stripe Checkout에 메타데이터 전달하기

실제 서비스에서는 결제 완료 후 어떤 주문에 해당하는 결제인지 추적해야 할 때가 많습니다. 예를 들어 Cart(장바구니)와 Order(주문) 모델을 직접 만들어 관리하는 경우, Stripe Checkout 세션에 주문 ID를 함께 전달하면, 결제 완료 후 애플리케이션으로 돌아왔을 때 해당 주문을 정확히 찾아 상태를 업데이트할 수 있습니다.

아래 예시에서 Cart와 Order 모델은 직접 구현해야 하는 예시 모델입니다. Cashier가 제공하는 것이 아닙니다.

use App\Models\Cart;
use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/cart/{cart}/checkout', function (Request $request, Cart $cart) {
    $order = Order::create([
        'cart_id' => $cart->id,
        'price_ids' => $cart->price_ids,
        'status' => 'incomplete',
    ]);

    return $request->user()->checkout($order->price_ids, [
        'success_url' => route('checkout-success').'?session_id={CHECKOUT_SESSION_ID}',
        'cancel_url' => route('checkout-cancel'),
        'metadata' => ['order_id' => $order->id],
    ]);
})->name('checkout');

success_url에 포함된 {CHECKOUT_SESSION_ID}는 Stripe가 자동으로 실제 세션 ID로 치환해 줍니다. 이를 통해 성공 라우트에서 세션 정보를 조회하고 주문 상태를 갱신할 수 있습니다.

use App\Models\Order;
use Illuminate\Http\Request;
use Laravel\Cashier\Cashier;

Route::get('/checkout/success', function (Request $request) {
    $sessionId = $request->get('session_id');

    if ($sessionId === null) {
        return;
    }

    $session = Cashier::stripe()->checkout->sessions->retrieve($sessionId);

    if ($session->payment_status !== 'paid') {
        return;
    }

    $orderId = $session['metadata']['order_id'] ?? null;

    $order = Order::findOrFail($orderId);

    $order->update(['status' => 'completed']);

    return view('checkout-success', ['order' => $order]);
})->name('checkout-success');

전체 흐름을 정리하면 다음과 같습니다.

Checkout 세션 객체에 포함된 전체 데이터 구조는 Stripe 공식 문서를 참고하세요.

구독 판매

NOTE

구독 기반 서비스도 Cashier와 Stripe Checkout을 활용하면 간결하게 구현할 수 있습니다.

예를 들어, 다음과 같은 구독 플랜이 있다고 가정해 보겠습니다.

플랜	가격 ID	주기
Basic 월간	`price_basic_monthly`	매월
Basic 연간	`price_basic_yearly`	매년
Expert	`pro_expert`	—

이 두 Basic 가격은 Stripe 대시보드에서 pro_basic이라는 하나의 상품 아래에 묶여 있습니다.

가격 페이지에서 사용자가 "Basic 월간 구독" 버튼을 클릭하면 아래 라우트로 이동해 Stripe Checkout 세션을 생성합니다.

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_basic_monthly')
        ->trialDays(5)
        ->allowPromotionCodes()
        ->checkout([
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

결제 완료 또는 취소 시, 고객은 checkout 메서드에 전달한 URL로 돌아옵니다. 일부 결제 수단은 처리에 수 초가 소요될 수 있으므로, 구독 시작 시점을 정확히 파악하려면 Cashier의 웹훅 처리를 반드시 설정해야 합니다.

구독 여부 확인하기

구독이 시작된 이후에는 Cashier의 Billable 트레이트가 제공하는 subscribed 메서드로 구독 상태를 간편하게 확인할 수 있습니다.

@if ($user->subscribed())
    <p>현재 구독 중입니다.</p>
@endif

특정 상품이나 가격을 기준으로도 확인할 수 있습니다.

@if ($user->subscribedToProduct('pro_basic'))
    <p>Basic 상품을 구독 중입니다.</p>
@endif

@if ($user->subscribedToPrice('price_basic_monthly'))
    <p>Basic 월간 플랜을 구독 중입니다.</p>
@endif

구독 전용 미들웨어 만들기

구독하지 않은 사용자가 특정 라우트에 접근하지 못하도록 미들웨어를 만들어 두면 편리합니다.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class Subscribed
{
    /**
     * 요청을 처리합니다.
     */
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed()) {
            // 구독 안내 페이지로 리디렉션
            return redirect('/billing');
        }

        return $next($request);
    }
}

미들웨어를 정의했다면 라우트에 적용합니다.

use App\Http\Middleware\Subscribed;

Route::get('/dashboard', function () {
    // ...
})->middleware([Subscribed::class]);

고객이 구독 플랜을 직접 관리하도록 허용하기

고객이 구독 플랜을 변경하거나, 결제 수단을 업데이트하거나, 인보이스를 다운로드할 수 있도록 하려면 Stripe의 Customer Billing Portal을 활용하는 것이 가장 간단합니다. Stripe가 제공하는 호스팅 UI를 통해 이러한 기능을 별도 개발 없이 제공할 수 있습니다.

먼저 애플리케이션 어딘가에 결제 관리 페이지로 이동하는 링크를 추가합니다.

<a href="{{ route('billing') }}">
    결제 관리
</a>

그런 다음, Stripe Customer Billing Portal 세션을 시작하고 해당 포털로 리디렉션하는 라우트를 정의합니다. redirectToBillingPortal 메서드에는 포털을 나온 후 돌아올 URL을 전달합니다.

use Illuminate\Http\Request;

Route::get('/billing', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('dashboard'));
})->middleware(['auth'])->name('billing');

NOTE

Cashier의 웹훅 처리가 설정되어 있으면, Stripe로부터 수신한 웹훅을 분석해 애플리케이션의 데이터베이스를 자동으로 동기화합니다. 예를 들어 고객이 Stripe Customer Billing Portal에서 구독을 취소하면, Cashier는 해당 웹훅을 수신하여 데이터베이스의 구독 상태를 "취소됨"으로 자동 업데이트합니다.

결제 (Laravel Cashier Stripe)

고객(Customers)

고객 조회

Stripe ID로 청구 가능한 모델(billable model)을 조회하려면 Cashier::findBillable 메서드를 사용합니다. 이 메서드는 해당 billable 모델 인스턴스를 반환합니다.

use Laravel\Cashier\Cashier;

$user = Cashier::findBillable($stripeId);

고객 생성

구독을 시작하지 않고 Stripe 고객만 먼저 생성하고 싶을 때는 createAsStripeCustomer 메서드를 사용합니다.

$stripeCustomer = $user->createAsStripeCustomer();

Stripe에 고객이 생성된 후에는 나중에 언제든지 구독을 시작할 수 있습니다. Stripe API가 지원하는 고객 생성 파라미터를 $options 배열로 추가로 전달할 수도 있습니다.

$stripeCustomer = $user->createAsStripeCustomer($options);

billable 모델에 대응하는 Stripe 고객 객체를 반환하고 싶다면 asStripeCustomer 메서드를 사용합니다.

$stripeCustomer = $user->asStripeCustomer();

해당 billable 모델이 이미 Stripe 고객으로 등록되어 있는지 확실하지 않을 때는 createOrGetStripeCustomer 메서드를 사용하면 편리합니다. 아직 고객이 존재하지 않으면 새로 생성하고, 이미 있으면 기존 고객 객체를 반환합니다.

$stripeCustomer = $user->createOrGetStripeCustomer();

고객 정보 업데이트

Stripe 고객 정보를 직접 수정해야 할 때는 updateStripeCustomer 메서드를 사용합니다. Stripe API가 지원하는 고객 업데이트 옵션 배열을 인자로 전달합니다.

$stripeCustomer = $user->updateStripeCustomer($options);

잔액(Balances)

Stripe는 고객의 "잔액"에 크레딧을 추가하거나 차감할 수 있습니다. 이 잔액은 이후 새 인보이스에 자동으로 반영됩니다. billable 모델의 balance 메서드로 현재 총 잔액을 조회할 수 있으며, 해당 고객의 통화에 맞게 포맷된 문자열로 반환됩니다.

$balance = $user->balance();

고객 잔액에 크레딧을 추가하려면 creditBalance 메서드를 사용합니다. 설명(description)도 함께 전달할 수 있습니다.

$user->creditBalance(500, '프리미엄 고객 잔액 충전');

잔액을 차감하려면 debitBalance 메서드를 사용합니다.

$user->debitBalance(300, '이용 정책 위반 패널티');

applyBalance 메서드는 고객에 대한 새 잔액 트랜잭션을 생성합니다. balanceTransactions 메서드로 해당 트랜잭션 목록을 조회할 수 있어, 고객에게 크레딧/차감 내역 로그를 보여줄 때 유용합니다.

// 모든 트랜잭션 조회
$transactions = $user->balanceTransactions();

foreach ($transactions as $transaction) {
    // 트랜잭션 금액
    $amount = $transaction->amount(); // 예: $2.31

    // 관련 인보이스가 있을 경우 조회
    $invoice = $transaction->invoice();
}

세금 ID(Tax IDs)

Cashier는 고객의 세금 ID를 편리하게 관리할 수 있는 방법을 제공합니다. 예를 들어, taxIds 메서드로 고객에게 등록된 모든 세금 ID를 컬렉션으로 조회할 수 있습니다.

$taxIds = $user->taxIds();

식별자로 특정 세금 ID를 조회할 수도 있습니다.

$taxId = $user->findTaxId('txi_belgium');

새 세금 ID를 생성하려면 유효한 type과 값을 createTaxId 메서드에 전달합니다.

$taxId = $user->createTaxId('eu_vat', 'BE0123456789');

createTaxId 메서드를 호출하면 VAT ID가 즉시 고객 계정에 추가됩니다. VAT ID 검증은 Stripe가 비동기적으로 처리합니다. 검증 결과를 알림으로 받으려면 customer.tax_id.updated 웹훅 이벤트를 구독하고 VAT ID의 verification 파라미터를 확인하면 됩니다. 웹훅 처리에 대한 자세한 내용은 웹훅 핸들러 정의 문서를 참고하세요.

세금 ID를 삭제하려면 deleteTaxId 메서드를 사용합니다.

$user->deleteTaxId('txi_belgium');

Stripe와 고객 데이터 동기화

애플리케이션 사용자가 이름, 이메일 주소 등 Stripe에도 저장된 정보를 수정하면, Stripe 쪽 데이터도 함께 갱신해야 합니다. 이렇게 해야 양쪽 데이터가 일치하게 됩니다.

이를 자동화하려면 billable 모델의 updated 이벤트에 반응하는 이벤트 리스너를 정의하고, 그 안에서 syncStripeCustomerDetails 메서드를 호출합니다.

use App\Models\User;
use function Illuminate\Events\queueable;

/**
 * 모델의 "booted" 메서드
 */
protected static function booted(): void
{
    static::updated(queueable(function (User $customer) {
        if ($customer->hasStripeId()) {
            $customer->syncStripeCustomerDetails();
        }
    }));
}

이제 고객 모델이 업데이트될 때마다 Stripe와 자동으로 정보가 동기화됩니다. 참고로 Cashier는 고객이 처음 생성될 때도 자동으로 Stripe와 동기화를 수행합니다.

Stripe로 동기화할 컬럼을 직접 지정하고 싶다면 Cashier가 제공하는 여러 메서드를 오버라이드하면 됩니다. 예를 들어, stripeName 메서드를 오버라이드하면 Cashier가 Stripe에 동기화할 때 "고객 이름"으로 사용할 속성을 변경할 수 있습니다.

/**
 * Stripe에 동기화할 고객 이름을 반환합니다.
 */
public function stripeName(): string|null
{
    return $this->company_name;
}

마찬가지로 stripeEmail, stripePhone, stripeAddress, stripePreferredLocales 메서드도 오버라이드할 수 있습니다. 이 메서드들은 Stripe 고객 객체 업데이트 시 해당 파라미터에 매핑되어 동기화됩니다. 동기화 과정 전체를 직접 제어하고 싶다면 syncStripeCustomerDetails 메서드 자체를 오버라이드하면 됩니다.

청구 포털(Billing Portal)

Stripe는 고객이 구독, 결제 수단, 청구 내역을 스스로 관리할 수 있는 청구 포털을 제공합니다. billable 모델의 redirectToBillingPortal 메서드를 컨트롤러나 라우트에서 호출하면 사용자를 청구 포털로 리디렉션할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal();
});

기본적으로 사용자가 구독 관리를 마치면 Stripe 청구 포털의 링크를 통해 애플리케이션의 home 라우트로 돌아오게 됩니다. 돌아올 URL을 직접 지정하려면 redirectToBillingPortal 메서드에 URL을 인자로 전달합니다.

use Illuminate\Http\Request;

Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('billing'));
});

HTTP 리디렉션 응답 대신 청구 포털 URL만 생성하려면 billingPortalUrl 메서드를 사용합니다.

$url = $request->user()->billingPortalUrl(route('billing'));

결제 수단 (Payment Methods)

결제 수단 저장

구독을 생성하거나 일회성 결제를 처리하려면 Stripe에 결제 수단을 저장하고 해당 식별자를 가져와야 합니다. 결제 수단을 사용하는 목적(구독 vs. 단건 결제)에 따라 접근 방식이 달라지므로, 아래에서 각각 살펴봅니다.

구독을 위한 결제 수단

구독에 사용할 신용카드 정보를 저장할 때는 Stripe의 "Setup Intents" API를 사용해 고객의 결제 수단 정보를 안전하게 수집해야 합니다. Setup Intent는 Stripe에 "이 결제 수단으로 나중에 청구할 예정"이라는 의도를 전달하는 객체입니다.

Cashier의 Billable 트레이트에는 createSetupIntent 메서드가 포함되어 있어 손쉽게 Setup Intent를 생성할 수 있습니다. 결제 수단 입력 폼을 렌더링하는 라우트 또는 컨트롤러에서 이 메서드를 호출하세요.

return view('update-payment-method', [
    'intent' => $user->createSetupIntent()
]);

Setup Intent를 생성해 뷰에 전달했다면, client_secret 값을 결제 수단을 수집하는 버튼 등의 요소에 연결해야 합니다. 예를 들어 "결제 수단 변경" 폼은 다음과 같이 구성할 수 있습니다.

<input id="card-holder-name" type="text">

<!-- Stripe Elements 플레이스홀더 -->
<div id="card-element"></div>

<button id="card-button" data-secret="{{ $intent->client_secret }}">
    결제 수단 변경
</button>

이어서 Stripe.js 라이브러리를 사용해 Stripe Element를 폼에 연결하고 고객의 카드 정보를 안전하게 수집합니다.

<script src="https://js.stripe.com/v3/"></script>

<script>
    const stripe = Stripe('stripe-public-key');

    const elements = stripe.elements();
    const cardElement = elements.create('card');

    cardElement.mount('#card-element');
</script>

다음으로 Stripe의 confirmCardSetup 메서드를 사용해 카드를 검증하고 안전한 "결제 수단 식별자"를 가져옵니다.

const cardHolderName = document.getElementById('card-holder-name');
const cardButton = document.getElementById('card-button');
const clientSecret = cardButton.dataset.secret;

cardButton.addEventListener('click', async (e) => {
    const { setupIntent, error } = await stripe.confirmCardSetup(
        clientSecret, {
            payment_method: {
                card: cardElement,
                billing_details: { name: cardHolderName.value }
            }
        }
    );

    if (error) {
        // error.message를 사용자에게 표시...
    } else {
        // 카드 검증 성공...
    }
});

Stripe에서 카드 검증이 완료되면 setupIntent.payment_method 식별자를 Laravel 애플리케이션으로 전달할 수 있습니다. 이 식별자는 새 결제 수단 추가, 기본 결제 수단 업데이트, 또는 새 구독 생성에 바로 사용할 수 있습니다.

NOTE

Setup Intent와 결제 수단 수집에 대한 더 자세한 내용은 Stripe 공식 문서를 참고하세요.

단건 결제를 위한 결제 수단

단건 결제를 처리할 때는 결제 수단 식별자를 한 번만 사용합니다. Stripe의 제한으로 인해 단건 결제에는 고객의 저장된 기본 결제 수단을 사용할 수 없으며, 고객이 직접 Stripe.js를 통해 카드 정보를 입력해야 합니다. 예시 폼은 다음과 같습니다.

<input id="card-holder-name" type="text">

<!-- Stripe Elements 플레이스홀더 -->
<div id="card-element"></div>

<button id="card-button">
    결제 처리
</button>

Stripe.js 라이브러리를 사용해 Stripe Element를 폼에 연결합니다.

<script src="https://js.stripe.com/v3/"></script>

<script>
    const stripe = Stripe('stripe-public-key');

    const elements = stripe.elements();
    const cardElement = elements.create('card');

    cardElement.mount('#card-element');
</script>

이어서 Stripe의 createPaymentMethod 메서드를 사용해 카드를 검증하고 결제 수단 식별자를 가져옵니다.

const cardHolderName = document.getElementById('card-holder-name');
const cardButton = document.getElementById('card-button');

cardButton.addEventListener('click', async (e) => {
    const { paymentMethod, error } = await stripe.createPaymentMethod(
        'card', cardElement, {
            billing_details: { name: cardHolderName.value }
        }
    );

    if (error) {
        // error.message를 사용자에게 표시...
    } else {
        // 카드 검증 성공...
    }
});

카드 검증에 성공하면 paymentMethod.id를 Laravel 애플리케이션으로 전달해 단건 결제를 처리할 수 있습니다.

결제 수단 조회

청구 가능 모델 인스턴스의 paymentMethods 메서드는 Laravel\Cashier\PaymentMethod 인스턴스 컬렉션을 반환합니다.

$paymentMethods = $user->paymentMethods();

기본적으로 모든 타입의 결제 수단을 반환합니다. 특정 타입만 조회하려면 type을 인수로 전달하세요.

$paymentMethods = $user->paymentMethods('sepa_debit');

기본 결제 수단을 가져오려면 defaultPaymentMethod 메서드를 사용합니다.

$paymentMethod = $user->defaultPaymentMethod();

청구 가능 모델에 연결된 특정 결제 수단을 조회하려면 findPaymentMethod 메서드를 사용합니다.

$paymentMethod = $user->findPaymentMethod($paymentMethodId);

결제 수단 존재 여부 확인

청구 가능 모델에 기본 결제 수단이 연결되어 있는지 확인하려면 hasDefaultPaymentMethod 메서드를 사용합니다.

if ($user->hasDefaultPaymentMethod()) {
    // ...
}

결제 수단이 하나 이상 연결되어 있는지 확인하려면 hasPaymentMethod 메서드를 사용합니다.

if ($user->hasPaymentMethod()) {
    // ...
}

특정 타입의 결제 수단이 존재하는지 확인할 때는 type을 인수로 전달하세요.

if ($user->hasPaymentMethod('sepa_debit')) {
    // ...
}

기본 결제 수단 변경

updateDefaultPaymentMethod 메서드는 고객의 기본 결제 수단을 변경합니다. Stripe 결제 수단 식별자를 전달하면 해당 결제 수단이 새 기본 결제 수단으로 설정됩니다.

$user->updateDefaultPaymentMethod($paymentMethod);

애플리케이션의 기본 결제 수단 정보를 Stripe에 저장된 정보와 동기화하려면 updateDefaultPaymentMethodFromStripe 메서드를 사용합니다.

$user->updateDefaultPaymentMethodFromStripe();

WARNING

기본 결제 수단은 청구서 발행과 새 구독 생성에만 사용할 수 있습니다. Stripe의 제한으로 인해 단건 결제에는 사용할 수 없습니다.

결제 수단 추가

청구 가능 모델에 새 결제 수단을 추가하려면 addPaymentMethod 메서드에 결제 수단 식별자를 전달해 호출하세요.

$user->addPaymentMethod($paymentMethod);

NOTE

결제 수단 식별자를 가져오는 방법은 결제 수단 저장 문서를 참고하세요.

결제 수단 삭제

특정 결제 수단을 삭제하려면 Laravel\Cashier\PaymentMethod 인스턴스의 delete 메서드를 호출하세요.

$paymentMethod->delete();

deletePaymentMethod 메서드는 청구 가능 모델에서 특정 결제 수단을 삭제합니다.

$user->deletePaymentMethod('pm_visa');

deletePaymentMethods 메서드는 청구 가능 모델의 모든 결제 수단을 삭제합니다.

$user->deletePaymentMethods();

기본적으로 모든 타입의 결제 수단을 삭제합니다. 특정 타입만 삭제하려면 type을 인수로 전달하세요.

$user->deletePaymentMethods('sepa_debit');

WARNING

활성 구독이 있는 사용자는 기본 결제 수단을 삭제할 수 없도록 애플리케이션에서 반드시 제한해야 합니다.

구독 (Subscriptions)

구독은 고객에게 정기 결제를 설정하는 방법입니다. Cashier가 관리하는 Stripe 구독은 여러 구독 가격, 수량, 체험 기간 등 다양한 기능을 지원합니다.

구독 생성

구독을 생성하려면 먼저 청구 가능 모델 인스턴스(일반적으로 App\Models\User)를 조회한 뒤, newSubscription 메서드로 구독을 생성합니다.

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription(
        'default', 'price_monthly'
    )->create($request->paymentMethodId);

    // ...
});

newSubscription의 첫 번째 인수는 구독의 내부 타입 이름입니다. 애플리케이션에서 구독이 하나뿐이라면 default 또는 primary로 지정하면 됩니다. 이 타입은 애플리케이션 내부용이며 사용자에게 노출되지 않습니다. 공백을 포함하면 안 되고, 구독 생성 후에는 변경해서는 안 됩니다. 두 번째 인수는 사용자가 구독할 Stripe 가격 ID입니다.

create 메서드는 Stripe 결제 수단 식별자 또는 Stripe PaymentMethod 객체를 인수로 받아 구독을 시작하고, 데이터베이스에 고객 ID 등 관련 정보를 저장합니다.

WARNING

결제 수단 식별자를 create 메서드에 직접 전달하면 해당 결제 수단이 사용자의 저장된 결제 수단 목록에 자동으로 추가됩니다.

인보이스 이메일로 정기 결제 수집

자동 결제 대신, 정기 결제일마다 Stripe가 고객에게 인보이스를 이메일로 발송하도록 설정할 수 있습니다. 고객은 이메일을 받은 후 직접 인보이스를 결제합니다. 이 방식은 구독 시작 시 결제 수단을 미리 등록할 필요가 없습니다.

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice();

인보이스 미결제 시 구독이 취소되기까지의 기간은 days_until_due 옵션으로 설정합니다. 기본값은 30일이며, 필요에 따라 변경할 수 있습니다.

$user->newSubscription('default', 'price_monthly')->createAndSendInvoice([], [
    'days_until_due' => 30
]);

수량 지정

구독 생성 시 특정 수량을 지정하려면 quantity 메서드를 체이닝합니다.

$user->newSubscription('default', 'price_monthly')
    ->quantity(5)
    ->create($paymentMethod);

추가 옵션 전달

Stripe가 지원하는 추가 고객 또는 구독 옵션은 create 메서드의 두 번째, 세 번째 인수로 전달할 수 있습니다.

$user->newSubscription('default', 'price_monthly')->create($paymentMethod, [
    'email' => $email,
], [
    'metadata' => ['note' => '추가 정보입니다.'],
]);

쿠폰

구독 생성 시 쿠폰을 적용하려면 withCoupon 메서드를 사용합니다.

$user->newSubscription('default', 'price_monthly')
    ->withCoupon('code')
    ->create($paymentMethod);

Stripe 프로모션 코드를 적용하려면 withPromotionCode 메서드를 사용합니다.

$user->newSubscription('default', 'price_monthly')
    ->withPromotionCode('promo_code_id')
    ->create($paymentMethod);

NOTE

여기서 전달하는 프로모션 코드 ID는 Stripe API ID(내부 ID)입니다. 고객이 입력하는 코드 문자열(예: SUMMERSALE)과 다릅니다. 고객용 코드 문자열로 API ID를 조회하려면 아래 메서드를 사용하세요.

// 고객용 코드로 프로모션 코드 조회...
$promotionCode = $user->findPromotionCode('SUMMERSALE');

// 활성화된 프로모션 코드만 조회...
$promotionCode = $user->findActivePromotionCode('SUMMERSALE');

반환되는 $promotionCode는 Laravel\Cashier\PromotionCode 인스턴스로, 내부적으로 Stripe\PromotionCode 객체를 감쌉니다. coupon 메서드로 관련 쿠폰 정보를 가져올 수 있습니다.

$coupon = $user->findPromotionCode('SUMMERSALE')->coupon();

쿠폰 인스턴스를 통해 할인 방식(정액 또는 퍼센트)과 할인 금액을 확인할 수 있습니다.

if ($coupon->isPercentage()) {
    return $coupon->percentOff().'%'; // 예: 21.5%
} else {
    return $coupon->amountOff(); // 예: ₩5,000
}

고객 또는 구독에 현재 적용된 할인을 조회할 수도 있습니다.

$discount = $billable->discount();

$discount = $subscription->discount();

반환되는 Laravel\Cashier\Discount 인스턴스는 Stripe\Discount 객체를 감쌉니다. 마찬가지로 coupon 메서드로 쿠폰 정보를 가져올 수 있습니다.

$coupon = $subscription->discount()->coupon();

고객 또는 구독에 새 쿠폰이나 프로모션 코드를 적용하려면 applyCoupon 또는 applyPromotionCode 메서드를 사용합니다.

$billable->applyCoupon('coupon_id');
$billable->applyPromotionCode('promotion_code_id');

$subscription->applyCoupon('coupon_id');
$subscription->applyPromotionCode('promotion_code_id');

고객 또는 구독에는 한 번에 하나의 쿠폰 또는 프로모션 코드만 적용할 수 있습니다. 자세한 내용은 Stripe의 쿠폰 및 프로모션 코드 문서를 참고하세요.

기본 결제 수단이 있는 고객에게 구독 추가

이미 기본 결제 수단이 등록된 고객에게 구독을 추가하려면 구독 빌더의 add 메서드를 사용합니다.

use App\Models\User;

$user = User::find(1);

$user->newSubscription('default', 'price_monthly')->add();

Stripe 대시보드에서 구독 생성

Stripe 대시보드에서 직접 구독을 생성할 수도 있습니다. 이 경우 Cashier는 새로 추가된 구독을 동기화하고 타입을 default로 지정합니다. 대시보드에서 생성한 구독의 타입을 커스터마이징하려면 웹훅 이벤트 핸들러를 정의하세요.

Stripe 대시보드에서는 한 가지 타입의 구독만 생성할 수 있습니다. 애플리케이션에서 여러 타입의 구독을 제공하는 경우, 대시보드를 통해서는 한 가지 타입만 추가할 수 있습니다.

또한, 동일한 타입의 활성 구독을 중복해서 생성하지 않도록 주의하세요. 동일 타입 구독이 두 개 존재하는 경우, Cashier는 가장 최근에 추가된 구독만 사용합니다.

구독 상태 확인

고객이 구독한 이후에는 다양한 메서드로 구독 상태를 간편하게 확인할 수 있습니다.

subscribed 메서드는 고객이 활성 구독을 보유하고 있으면(체험 기간 중이라도) true를 반환합니다. 구독 타입을 첫 번째 인수로 전달합니다.

if ($user->subscribed('default')) {
    // ...
}

subscribed 메서드는 라우트 미들웨어로 활용하기에도 적합합니다. 구독 여부에 따라 라우트 접근을 제어할 수 있습니다.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserIsSubscribed
{
    /**
     * 들어오는 요청을 처리합니다.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user() && ! $request->user()->subscribed('default')) {
            // 유료 구독자가 아닌 경우 결제 페이지로 리다이렉트
            return redirect('/billing');
        }

        return $next($request);
    }
}

체험 기간 중인지 확인하려면 onTrial 메서드를 사용합니다. 체험 기간임을 사용자에게 안내하는 배너 등을 표시할 때 유용합니다.

if ($user->subscription('default')->onTrial()) {
    // ...
}

subscribedToProduct 메서드는 Stripe 상품 ID를 기반으로 특정 상품을 구독 중인지 확인합니다. Stripe에서 상품은 여러 가격(price)의 묶음입니다.

if ($user->subscribedToProduct('prod_premium', 'default')) {
    // ...
}

배열을 전달하면 여러 상품 중 하나라도 구독 중인지 확인할 수 있습니다.

if ($user->subscribedToProduct(['prod_basic', 'prod_premium'], 'default')) {
    // ...
}

subscribedToPrice 메서드는 특정 가격 ID를 구독 중인지 확인합니다.

if ($user->subscribedToPrice('price_basic_monthly', 'default')) {
    // ...
}

recurring 메서드는 현재 구독 중이며 체험 기간이 아닌지 확인합니다.

if ($user->subscription('default')->recurring()) {
    // ...
}

WARNING

동일한 타입의 구독이 두 개 이상 존재하는 경우, subscription 메서드는 항상 가장 최근 구독을 반환합니다. 이전 구독 기록은 데이터베이스에 유지되지만 Cashier에서는 최신 구독만 사용됩니다.

취소된 구독 상태

한 때 활성 구독자였으나 구독을 취소한 경우를 확인하려면 canceled 메서드를 사용합니다.

if ($user->subscription('default')->canceled()) {
    // ...
}

구독을 취소했지만 아직 만료일 전(유예 기간)인지 확인하려면 onGracePeriod 메서드를 사용합니다. 예를 들어, 3월 5일에 구독을 취소했지만 원래 만료일이 3월 10일이라면 3월 10일까지는 유예 기간입니다. 이 기간 동안 subscribed 메서드는 여전히 true를 반환합니다.

if ($user->subscription('default')->onGracePeriod()) {
    // ...
}

구독을 취소하고 유예 기간도 완전히 지났는지 확인하려면 ended 메서드를 사용합니다.

if ($user->subscription('default')->ended()) {
    // ...
}

미완료(Incomplete) 및 연체(Past Due) 상태

구독 생성 후 추가 결제 인증이 필요한 경우 구독은 incomplete 상태가 됩니다. 마찬가지로, 가격 변경 시 추가 인증이 필요하면 past_due 상태가 됩니다. 두 상태 모두 고객이 결제를 확인할 때까지 구독이 활성화되지 않습니다. 결제 미완료 여부는 다음과 같이 확인합니다.

if ($user->hasIncompletePayment('default')) {
    // ...
}

if ($user->subscription('default')->hasIncompletePayment()) {
    // ...
}

결제가 미완료 상태라면 사용자를 Cashier 결제 확인 페이지로 안내해야 합니다. latestPayment 메서드로 최신 결제 ID를 가져와 링크를 생성합니다.

<a href="{{ route('cashier.payment', $subscription->latestPayment()->id) }}">
    결제를 확인해 주세요.
</a>

past_due 또는 incomplete 상태의 구독을 활성 상태로 간주하고 싶다면, AppServiceProvider의 register 메서드에서 다음 메서드를 호출합니다.

use Laravel\Cashier\Cashier;

/**
 * 애플리케이션 서비스를 등록합니다.
 */
public function register(): void
{
    Cashier::keepPastDueSubscriptionsActive();
    Cashier::keepIncompleteSubscriptionsActive();
}

WARNING

구독이 incomplete 상태일 때는 결제가 확인될 때까지 변경이 불가합니다. swap 및 updateQuantity 메서드는 이 상태에서 예외를 발생시킵니다.

구독 쿼리 스코프

대부분의 구독 상태는 쿼리 스코프로도 제공됩니다. 특정 상태의 구독을 데이터베이스에서 손쉽게 조회할 수 있습니다.

// 모든 활성 구독 조회...
$subscriptions = Subscription::query()->active()->get();

// 특정 사용자의 취소된 구독 조회...
$subscriptions = $user->subscriptions()->canceled()->get();

사용 가능한 전체 스코프 목록은 다음과 같습니다.

Subscription::query()->active();
Subscription::query()->canceled();
Subscription::query()->ended();
Subscription::query()->incomplete();
Subscription::query()->notCanceled();
Subscription::query()->notOnGracePeriod();
Subscription::query()->notOnTrial();
Subscription::query()->onGracePeriod();
Subscription::query()->onTrial();
Subscription::query()->pastDue();
Subscription::query()->recurring();

가격 변경

고객이 구독 중인 가격을 변경하려면 swap 메서드에 새 Stripe 가격 ID를 전달합니다. 이전에 취소된 구독이었다면 재활성화됩니다.

use App\Models\User;

$user = App\Models\User::find(1);

$user->subscription('default')->swap('price_yearly');

체험 기간 중인 고객은 체험 기간이 유지됩니다. 구독에 수량이 설정되어 있다면 해당 수량도 유지됩니다.

체험 기간을 즉시 종료하고 가격을 변경하려면 skipTrial 메서드를 체이닝합니다.

$user->subscription('default')
    ->skipTrial()
    ->swap('price_yearly');

다음 결제 주기를 기다리지 않고 즉시 인보이스를 발행하며 가격을 변경하려면 swapAndInvoice 메서드를 사용합니다.

$user = User::find(1);

$user->subscription('default')->swapAndInvoice('price_yearly');

일할 계산 (Proration)

기본적으로 Stripe는 가격 변경 시 일할 계산(proration)을 적용합니다. 일할 계산 없이 가격만 변경하려면 noProrate 메서드를 사용합니다.

$user->subscription('default')->noProrate()->swap('price_yearly');

자세한 내용은 Stripe 일할 계산 문서를 참고하세요.

WARNING

swapAndInvoice 메서드 이전에 noProrate를 호출해도 일할 계산에는 영향을 주지 않습니다. 인보이스는 항상 발행됩니다.

구독 수량

구독에 "수량" 개념이 적용되는 경우(예: 프로젝트 관리 앱에서 프로젝트당 월 1만 원 청구), incrementQuantity 및 decrementQuantity 메서드로 수량을 조정할 수 있습니다.

use App\Models\User;

$user = User::find(1);

$user->subscription('default')->incrementQuantity();

// 구독 수량을 5 증가...
$user->subscription('default')->incrementQuantity(5);

$user->subscription('default')->decrementQuantity();

// 구독 수량을 5 감소...
$user->subscription('default')->decrementQuantity(5);

특정 수량으로 직접 설정하려면 updateQuantity 메서드를 사용합니다.

$user->subscription('default')->updateQuantity(10);

일할 계산 없이 수량만 변경하려면 noProrate 메서드를 체이닝합니다.

$user->subscription('default')->noProrate()->updateQuantity(10);

자세한 내용은 Stripe 구독 수량 문서를 참고하세요.

다중 상품 구독의 수량 조정

다중 상품 구독의 경우, 수량을 변경할 가격의 ID를 두 번째 인수로 전달합니다.

$user->subscription('default')->incrementQuantity(1, 'price_chat');

다중 상품 구독

다중 상품 구독을 사용하면 하나의 구독에 여러 결제 상품을 할당할 수 있습니다. 예를 들어, 기본 구독료가 월 1만 원인 헬프데스크 서비스에서 라이브 채팅 기능을 월 1만 5천 원의 애드온으로 제공하는 경우를 생각해 볼 수 있습니다. 다중 상품 구독 정보는 Cashier의 subscription_items 테이블에 저장됩니다.

newSubscription 메서드의 두 번째 인수로 가격 ID 배열을 전달하여 여러 상품을 지정할 수 있습니다.

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default', [
        'price_monthly',
        'price_chat',
    ])->create($request->paymentMethodId);

    // ...
});

각 가격에 수량을 지정하려면 quantity 메서드를 사용합니다.

$user = User::find(1);

$user->newSubscription('default', ['price_monthly', 'price_chat'])
    ->quantity(5, 'price_chat')
    ->create($paymentMethod);

기존 구독에 가격을 추가하려면 addPrice 메서드를 사용합니다. 추가된 가격은 다음 결제 주기에 청구됩니다.

$user = User::find(1);

$user->subscription('default')->addPrice('price_chat');

즉시 청구하려면 addPriceAndInvoice 메서드를 사용합니다.

$user->subscription('default')->addPriceAndInvoice('price_chat');

수량을 지정하며 가격을 추가할 수도 있습니다.

$user = User::find(1);

$user->subscription('default')->addPrice('price_chat', 5);

구독에서 가격을 제거하려면 removePrice 메서드를 사용합니다.

$user->subscription('default')->removePrice('price_chat');

WARNING

구독의 마지막 남은 가격은 제거할 수 없습니다. 대신 구독 자체를 취소하세요.

가격 교체

다중 상품 구독에서 특정 가격을 다른 가격으로 교체할 수도 있습니다. 예를 들어, price_basic 구독과 price_chat 애드온이 있는 고객을 price_pro로 업그레이드하는 경우를 생각해 볼 수 있습니다.

use App\Models\User;

$user = User::find(1);

$user->subscription('default')->swap(['price_pro', 'price_chat']);

위 예시에서는 price_basic 구독 항목이 삭제되고, price_chat은 유지되며, price_pro가 새로 추가됩니다.

수량 등 추가 옵션을 지정하려면 키/값 배열로 전달합니다.

$user = User::find(1);

$user->subscription('default')->swap([
    'price_pro' => ['quantity' => 5],
    'price_chat'
]);

단일 가격만 교체하려면 해당 구독 항목에서 직접 swap 메서드를 호출합니다. 나머지 항목의 메타데이터 등이 그대로 유지됩니다.

$user = User::find(1);

$user->subscription('default')
    ->findItemOrFail('price_basic')
    ->swap('price_pro');

일할 계산

기본적으로 Stripe는 다중 상품 구독에서 가격을 추가하거나 제거할 때 일할 계산을 적용합니다. 일할 계산 없이 조정하려면 noProrate 메서드를 체이닝합니다.

$user->subscription('default')->noProrate()->removePrice('price_chat');

수량 변경

개별 구독 가격의 수량을 변경하려면 기존 수량 메서드에 가격 ID를 추가 인수로 전달합니다.

$user = User::find(1);

$user->subscription('default')->incrementQuantity(5, 'price_chat');

$user->subscription('default')->decrementQuantity(3, 'price_chat');

$user->subscription('default')->updateQuantity(10, 'price_chat');

WARNING

구독에 여러 가격이 있을 때 Subscription 모델의 stripe_price 및 quantity 속성은 null이 됩니다. 개별 가격 속성에 접근하려면 Subscription 모델의 items 관계를 사용하세요.

구독 항목 (Subscription Items)

구독에 여러 가격이 있으면 데이터베이스의 subscription_items 테이블에 여러 구독 항목이 저장됩니다. items 관계를 통해 접근할 수 있습니다.

use App\Models\User;

$user = User::find(1);

$subscriptionItem = $user->subscription('default')->items->first();

// 특정 항목의 Stripe 가격 ID와 수량 조회...
$stripePrice = $subscriptionItem->stripe_price;
$quantity = $subscriptionItem->quantity;

findItemOrFail 메서드로 특정 가격 항목을 조회할 수 있습니다.

$user = User::find(1);

$subscriptionItem = $user->subscription('default')->findItemOrFail('price_chat');

다중 구독

Stripe는 고객이 여러 구독을 동시에 보유하는 것을 지원합니다. 예를 들어, 헬스장 앱에서 수영 구독과 웨이트 구독을 별도로 운영하고 각기 다른 요금을 적용할 수 있습니다.

구독을 생성할 때 newSubscription 메서드에 구독 타입 문자열을 지정합니다.

use Illuminate\Http\Request;

Route::post('/swimming/subscribe', function (Request $request) {
    $request->user()->newSubscription('swimming')
        ->price('price_swimming_monthly')
        ->create($request->paymentMethodId);

    // ...
});

나중에 연간 구독으로 변경하거나 구독을 취소하는 것도 동일하게 처리할 수 있습니다.

// 연간 구독으로 변경
$user->subscription('swimming')->swap('price_swimming_yearly');

// 구독 취소
$user->subscription('swimming')->cancel();

사용량 기반 결제

사용량 기반 결제를 사용하면 결제 주기 동안 고객의 실제 사용량에 따라 요금을 부과할 수 있습니다. 예를 들어, 한 달 동안 발송한 문자 메시지나 이메일 수에 따라 청구하는 방식입니다.

먼저 Stripe 대시보드에서 사용량 기반 결제 모델과 미터(meter)를 설정합니다. 미터를 생성한 후 이벤트 이름과 미터 ID를 기록해 두세요. 그런 다음 meteredPrice 메서드로 미터 가격 ID를 구독에 추가합니다.

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default')
        ->meteredPrice('price_metered')
        ->create($request->paymentMethodId);

    // ...
});

Stripe Checkout을 통해 사용량 기반 구독을 시작할 수도 있습니다.

$checkout = Auth::user()
    ->newSubscription('default', [])
    ->meteredPrice('price_metered')
    ->checkout();

return view('your-checkout-view', [
    'checkout' => $checkout,
]);

사용량 보고

고객이 앱을 사용함에 따라 Stripe에 사용량을 보고해야 정확한 청구가 이루어집니다. Billable 모델의 reportMeterEvent 메서드를 사용합니다.

$user = User::find(1);

$user->reportMeterEvent('emails-sent');

기본적으로 사용량 1이 추가됩니다. 특정 수량을 지정하려면 다음과 같이 합니다.

$user = User::find(1);

$user->reportMeterEvent('emails-sent', quantity: 15);

특정 미터의 이벤트 요약을 조회하려면 meterEventSummaries 메서드를 사용합니다.

$user = User::find(1);

$meterUsage = $user->meterEventSummaries($meterId);

$meterUsage->first()->aggregated_value // 10

미터 이벤트 요약 객체에 대한 자세한 내용은 Stripe Meter Event Summary 문서를 참고하세요.

모든 미터 목록을 조회하려면 meters 메서드를 사용합니다.

$user = User::find(1);

$user->meters();

구독 세금

WARNING

세율을 직접 계산하는 대신 Stripe Tax를 통한 자동 세금 계산을 사용하는 것을 권장합니다.

구독에 적용할 세율을 직접 지정하려면 청구 가능 모델에 taxRates 메서드를 구현하고 Stripe 세율 ID 배열을 반환합니다. 세율은 Stripe 대시보드에서 정의할 수 있습니다.

/**
 * 고객 구독에 적용할 세율입니다.
 *
 * @return array<int, string>
 */
public function taxRates(): array
{
    return ['txr_id'];
}

taxRates 메서드는 고객별로 다른 세율을 적용해야 하는 경우(예: 국가별 세율 차이)에 유용합니다.

다중 상품 구독에서 가격별로 다른 세율을 적용하려면 priceTaxRates 메서드를 구현합니다.

/**
 * 고객 구독에 적용할 가격별 세율입니다.
 *
 * @return array<string, array<int, string>>
 */
public function priceTaxRates(): array
{
    return [
        'price_monthly' => ['txr_id'],
    ];
}

WARNING

taxRates 메서드는 구독 청구에만 적용됩니다. 단건 결제에는 세율을 별도로 지정해야 합니다.

세율 동기화

taxRates 메서드에서 반환하는 세율 ID를 변경해도 기존 구독의 세율 설정은 변경되지 않습니다. 기존 구독에 새 세율을 적용하려면 syncTaxRates 메서드를 호출합니다.

$user->subscription('default')->syncTaxRates();

이 메서드는 다중 상품 구독의 항목별 세율도 함께 동기화합니다. 다중 상품 구독을 제공하는 경우 청구 가능 모델에 priceTaxRates 메서드가 구현되어 있는지 확인하세요.

세금 면제

Cashier는 고객의 세금 면제 여부를 확인하는 메서드도 제공합니다. 이 메서드들은 Stripe API를 호출하여 상태를 조회합니다.

use App\Models\User;

$user = User::find(1);

$user->isTaxExempt();
$user->isNotTaxExempt();
$user->reverseChargeApplies();

WARNING

이 메서드들은 Laravel\Cashier\Invoice 객체에서도 사용할 수 있습니다. 단, Invoice 객체에서 호출하면 인보이스 생성 당시의 세금 면제 상태를 기준으로 판단합니다.

구독 기준일 (Anchor Date)

기본적으로 결제 주기의 기준일은 구독이 생성된 날짜이며, 체험 기간이 있는 경우 체험 기간이 끝나는 날짜입니다. 기준일을 변경하려면 anchorBillingCycleOn 메서드를 사용합니다.

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $anchor = Carbon::parse('first day of next month');

    $request->user()->newSubscription('default', 'price_monthly')
        ->anchorBillingCycleOn($anchor->startOfDay())
        ->create($request->paymentMethodId);

    // ...
});

구독 결제 주기 관리에 대한 자세한 내용은 Stripe 결제 주기 문서를 참고하세요.

구독 취소

구독을 취소하려면 cancel 메서드를 호출합니다.

$user->subscription('default')->cancel();

구독이 취소되면 Cashier는 subscriptions 테이블의 ends_at 컬럼을 자동으로 설정합니다. 이 값을 기준으로 subscribed 메서드가 false를 반환할 시점을 결정합니다.

예를 들어, 3월 1일에 취소하더라도 구독 만료일이 3월 5일이라면 subscribed 메서드는 3월 5일까지 true를 반환합니다. 결제 주기가 끝날 때까지 서비스를 계속 이용할 수 있도록 하기 위함입니다.

유예 기간 중인지 확인하려면 onGracePeriod 메서드를 사용합니다.

if ($user->subscription('default')->onGracePeriod()) {
    // ...
}

즉시 취소하려면 cancelNow 메서드를 사용합니다.

$user->subscription('default')->cancelNow();

즉시 취소하면서 미청구된 사용량 또는 보류 중인 일할 계산 항목에 대한 인보이스도 발행하려면 cancelNowAndInvoice 메서드를 사용합니다.

$user->subscription('default')->cancelNowAndInvoice();

특정 시점에 구독을 취소하도록 예약할 수도 있습니다.

$user->subscription('default')->cancelAt(
    now()->addDays(10)
);

마지막으로, 사용자 모델을 삭제하기 전에 반드시 구독을 취소해야 합니다.

$user->subscription('default')->cancelNow();

$user->delete();

구독 재개

취소된 구독을 재개하려면 resume 메서드를 호출합니다. 구독을 재개하려면 반드시 유예 기간 내에 있어야 합니다.

$user->subscription('default')->resume();

구독이 완전히 만료되기 전에 취소 후 재개하는 경우, 즉시 청구되지 않으며 원래 결제 주기에 따라 다음 청구일에 청구됩니다.

구독 체험판 (Subscription Trials)

결제 수단을 먼저 수집하는 체험판

체험 기간을 제공하면서도 결제 수단 정보를 미리 받고 싶다면, 구독 생성 시 trialDays 메서드를 사용하세요:

use Illuminate\Http\Request;

Route::post('/user/subscribe', function (Request $request) {
    $request->user()->newSubscription('default', 'price_monthly')
        ->trialDays(10)
        ->create($request->paymentMethodId);

    // ...
});

이 메서드는 데이터베이스의 구독 레코드에 체험 종료 날짜를 기록하고, Stripe에 해당 날짜 이전까지는 결제를 청구하지 않도록 지시합니다. trialDays를 사용하면 Stripe 대시보드의 플랜(Price)에 설정된 기본 체험 기간은 무시되고 여기서 지정한 값으로 덮어씁니다.

WARNING

체험 기간이 끝나기 전에 구독을 취소하지 않으면, 만료 즉시 결제가 청구됩니다. 반드시 사용자에게 체험 종료 날짜를 안내하세요.

체험 종료 시점을 날짜로 직접 지정하려면 trialUntil 메서드에 DateTime 인스턴스를 전달하면 됩니다:

use Carbon\Carbon;

$user->newSubscription('default', 'price_monthly')
    ->trialUntil(Carbon::now()->addDays(10))
    ->create($paymentMethod);

사용자가 현재 체험 기간 중인지 확인하려면 유저 인스턴스 또는 구독 인스턴스의 onTrial 메서드를 사용합니다. 아래 두 코드는 동일하게 동작합니다:

if ($user->onTrial('default')) {
    // ...
}

if ($user->subscription('default')->onTrial()) {
    // ...
}

체험 기간을 즉시 종료하려면 endTrial 메서드를 사용하세요:

$user->subscription('default')->endTrial();

체험 기간이 이미 만료되었는지 확인하려면 hasExpiredTrial 메서드를 사용합니다:

if ($user->hasExpiredTrial('default')) {
    // ...
}

if ($user->subscription('default')->hasExpiredTrial()) {
    // ...
}

Stripe / Cashier에서 체험 기간 설정하기

체험 일수는 Stripe 대시보드의 플랜(Price) 설정에서 지정하거나, Cashier 코드에서 명시적으로 전달하는 방식 중 하나를 선택할 수 있습니다.

Stripe 대시보드에서 체험 일수를 설정하는 경우, 주의할 점이 있습니다. 과거에 구독 이력이 있는 고객을 포함해 모든 신규 구독에 체험 기간이 자동 적용됩니다. 이를 원하지 않는다면 구독 생성 시 명시적으로 skipTrial() 메서드를 호출해야 합니다.

결제 수단 없이 제공하는 체험판

결제 수단 정보를 미리 받지 않고 체험 기간을 제공하고 싶다면, 사용자 레코드의 trial_ends_at 컬럼에 원하는 체험 종료 날짜를 직접 설정하면 됩니다. 이 작업은 보통 회원 가입 시점에 수행합니다:

use App\Models\User;

$user = User::create([
    // ...
    'trial_ends_at' => now()->addDays(10),
]);

WARNING

Billable 모델 클래스에 trial_ends_at 속성에 대한 날짜 캐스트를 반드시 추가하세요.

이런 방식의 체험판은 특정 구독에 연결되지 않으므로, Cashier에서는 이를 **"일반 체험판(generic trial)"**이라고 부릅니다. Billable 모델 인스턴스의 onTrial 메서드는 현재 날짜가 trial_ends_at 이전이면 true를 반환합니다:

if ($user->onTrial()) {
    // 사용자가 체험 기간 중입니다...
}

실제 구독을 생성할 준비가 되면 평소와 동일하게 newSubscription 메서드를 사용하면 됩니다:

$user = User::find(1);

$user->newSubscription('default', 'price_monthly')->create($paymentMethod);

사용자의 체험 종료 날짜를 가져오려면 trialEndsAt 메서드를 사용하세요. 체험 중이면 Carbon 인스턴스를, 체험 중이 아니면 null을 반환합니다. 특정 구독 타입의 종료 날짜를 조회하려면 구독 타입을 인자로 전달할 수 있습니다:

if ($user->onTrial()) {
    $trialEndsAt = $user->trialEndsAt('main');
}

사용자가 "일반 체험판" 상태인지 (즉, 아직 실제 구독을 생성하지 않은 상태인지) 정확히 확인하려면 onGenericTrial 메서드를 사용하세요:

if ($user->onGenericTrial()) {
    // 사용자가 일반 체험 기간 중입니다 (구독 미생성 상태)...
}

체험 기간 연장

extendTrial 메서드를 사용하면 구독이 생성된 이후에도 체험 기간을 연장할 수 있습니다. 체험 기간이 이미 만료되어 실제 결제가 시작된 경우에도 연장이 가능하며, 연장된 체험 기간 동안 사용한 시간은 다음 청구서 금액에서 차감됩니다:

use App\Models\User;

$subscription = User::find(1)->subscription('default');

// 지금으로부터 7일 후에 체험 종료
$subscription->extendTrial(
    now()->addDays(7)
);

// 현재 체험 종료일에서 5일 추가 연장
$subscription->extendTrial(
    $subscription->trial_ends_at->addDays(5)
);

결제 (Laravel Cashier Stripe)

Stripe 웹훅 처리

NOTE

로컬 개발 환경에서 웹훅을 테스트할 때는 Stripe CLI를 활용하면 편리합니다.

Stripe는 다양한 이벤트가 발생했을 때 웹훅을 통해 애플리케이션에 알림을 보낼 수 있습니다. Cashier 서비스 프로바이더는 기본적으로 웹훅 컨트롤러를 가리키는 라우트를 자동으로 등록하며, 이 컨트롤러가 모든 웹훅 요청을 처리합니다.

Cashier 웹훅 컨트롤러는 기본적으로 다음 상황을 자동으로 처리합니다.

결제 실패 횟수 초과로 인한 구독 취소 (Stripe 설정 기준)
고객 정보 업데이트 및 삭제
구독 업데이트
결제 수단 변경

이 외에도 필요한 Stripe 웹훅 이벤트를 직접 처리하도록 컨트롤러를 확장할 수 있습니다.

애플리케이션이 Stripe 웹훅을 수신하려면 Stripe 대시보드에서 웹훅 URL을 설정해야 합니다. Cashier 웹훅 컨트롤러는 기본적으로 /stripe/webhook 경로로 요청을 수신합니다. Stripe 대시보드에서 활성화해야 할 웹훅 이벤트 목록은 다음과 같습니다.

customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
customer.updated
customer.deleted
payment_method.automatically_updated
invoice.payment_action_required
invoice.payment_succeeded

편의를 위해 Cashier는 cashier:webhook Artisan 명령어를 제공합니다. 이 명령어를 실행하면 Cashier가 필요로 하는 모든 이벤트를 수신하는 웹훅이 Stripe에 자동으로 생성됩니다.

php artisan cashier:webhook

생성된 웹훅은 기본적으로 .env 파일의 APP_URL 환경 변수와 Cashier에 포함된 cashier.webhook 라우트를 조합한 URL을 사용합니다. 다른 URL을 사용하려면 --url 옵션을 지정하세요.

php artisan cashier:webhook --url "https://example.com/stripe/webhook"

생성되는 웹훅은 현재 Cashier 버전과 호환되는 Stripe API 버전을 사용합니다. 특정 Stripe API 버전을 지정하려면 --api-version 옵션을 사용하세요.

php artisan cashier:webhook --api-version="2019-12-03"

웹훅은 생성 즉시 활성화됩니다. 생성은 하되 준비가 될 때까지 비활성 상태로 두고 싶다면 --disabled 옵션을 사용하세요.

php artisan cashier:webhook --disabled

WARNING

Stripe에서 전송되는 웹훅 요청은 반드시 Cashier에 내장된 웹훅 서명 검증 미들웨어로 보호해야 합니다.

웹훅과 CSRF 보호

Stripe 웹훅은 Laravel의 CSRF 보호를 우회해야 하므로, stripe/* 경로를 CSRF 검증 대상에서 제외해야 합니다. bootstrap/app.php 파일에서 다음과 같이 설정하세요.

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'stripe/*',
    ]);
})

웹훅 이벤트 핸들러 정의

Cashier는 결제 실패에 따른 구독 취소 등 자주 발생하는 Stripe 웹훅 이벤트를 자동으로 처리합니다. 그 외에 직접 처리하고 싶은 웹훅 이벤트가 있다면, Cashier가 디스패치하는 다음 이벤트에 리스너를 등록하면 됩니다.

Laravel\Cashier\Events\WebhookReceived — 웹훅 수신 시
Laravel\Cashier\Events\WebhookHandled — 웹훅 처리 완료 시

두 이벤트 모두 Stripe 웹훅의 전체 페이로드를 포함합니다. 예를 들어 invoice.payment_succeeded 이벤트를 처리하려면 다음과 같이 리스너를 등록합니다.

<?php

namespace App\Listeners;

use Laravel\Cashier\Events\WebhookReceived;

class StripeEventListener
{
    /**
     * Stripe 웹훅 수신 처리
     */
    public function handle(WebhookReceived $event): void
    {
        if ($event->payload['type'] === 'invoice.payment_succeeded') {
            // 이벤트 처리 로직 작성...
        }
    }
}

웹훅 서명 검증

외부에서 위조된 요청을 차단하기 위해 Stripe의 웹훅 서명을 활용할 수 있습니다. Cashier는 수신된 Stripe 웹훅 요청의 유효성을 검증하는 미들웨어를 기본으로 포함하고 있습니다.

웹훅 서명 검증을 활성화하려면 애플리케이션의 .env 파일에 STRIPE_WEBHOOK_SECRET 환경 변수를 설정하세요. 웹훅 시크릿(secret) 값은 Stripe 계정 대시보드에서 확인할 수 있습니다.

단건 결제

단순 결제

청구 가능(Billable) 모델 인스턴스에서 charge 메서드를 사용하면 고객에게 일회성 요금을 청구할 수 있습니다. 두 번째 인수로 결제 수단 식별자를 전달해야 합니다.

use Illuminate\Http\Request;

Route::post('/purchase', function (Request $request) {
    $stripeCharge = $request->user()->charge(
        100, $request->paymentMethodId
    );

    // ...
});

charge 메서드는 세 번째 인수로 배열을 받으며, Stripe 결제 생성 시 사용할 추가 옵션을 전달할 수 있습니다. 사용 가능한 옵션에 대한 자세한 내용은 Stripe 공식 문서를 참고하세요.

$user->charge(100, $paymentMethod, [
    'custom_option' => $value,
]);

고객(Customer) 또는 사용자 레코드 없이도 charge 메서드를 호출할 수 있습니다. 이 경우 청구 가능 모델의 새 인스턴스에서 메서드를 호출하면 됩니다.

use App\Models\User;

$stripeCharge = (new User)->charge(100, $paymentMethod);

결제에 실패하면 charge 메서드는 예외를 발생시킵니다. 결제가 성공하면 Laravel\Cashier\Payment 인스턴스가 반환됩니다.

try {
    $payment = $user->charge(100, $paymentMethod);
} catch (Exception $e) {
    // ...
}

WARNING

charge 메서드는 애플리케이션에서 사용하는 통화의 최소 단위 기준으로 금액을 받습니다. 예를 들어 원화(KRW)를 사용한다면 금액을 그대로 정수로 전달하고, 달러(USD)를 사용한다면 센트(1달러 = 100센트) 단위로 전달해야 합니다.

인보이스와 함께 결제

일회성 결제와 함께 고객에게 PDF 인보이스를 발급해야 할 때는 invoicePrice 메서드를 사용합니다. 예를 들어, 티셔츠 5개에 대한 인보이스를 발급하려면 다음과 같이 작성합니다.

$user->invoicePrice('price_tshirt', 5);

인보이스는 즉시 사용자의 기본 결제 수단으로 청구됩니다. invoicePrice 메서드는 세 번째 인수로 인보이스 항목의 결제 옵션 배열을, 네 번째 인수로 인보이스 자체의 결제 옵션 배열을 받습니다.

$user->invoicePrice('price_tshirt', 5, [
    'discounts' => [
        ['coupon' => 'SUMMER21SALE']
    ],
], [
    'default_tax_rates' => ['txr_id'],
]);

tabPrice 메서드를 사용하면 여러 항목(인보이스당 최대 250개)을 고객의 "탭(tab)"에 추가한 뒤 한 번에 인보이스를 발급할 수 있습니다. 예를 들어 티셔츠 5개와 머그컵 2개를 함께 청구하려면 다음과 같이 작성합니다.

$user->tabPrice('price_tshirt', 5);
$user->tabPrice('price_mug', 2);
$user->invoice();

또는 invoiceFor 메서드를 사용해 고객의 기본 결제 수단으로 임의의 일회성 요금을 청구할 수도 있습니다.

$user->invoiceFor('일회 이용료', 500);

invoiceFor 메서드도 사용할 수 있지만, 가급적 Stripe에 미리 등록한 가격을 활용하는 invoicePrice와 tabPrice 메서드 사용을 권장합니다. 사전 등록된 가격을 사용하면 Stripe 대시보드에서 상품별 매출 분석 데이터를 더 체계적으로 확인할 수 있습니다.

WARNING

invoice, invoicePrice, invoiceFor 메서드는 Stripe 인보이스를 생성하며, 결제 실패 시 자동으로 재시도합니다. 실패 후 재시도를 원하지 않는다면 첫 번째 결제 실패 직후 Stripe API를 통해 해당 인보이스를 직접 닫아야 합니다.

Payment Intent 생성

청구 가능 모델 인스턴스에서 pay 메서드를 호출하면 새로운 Stripe Payment Intent를 생성할 수 있습니다. 반환값은 Laravel\Cashier\Payment 인스턴스로 래핑됩니다.

use Illuminate\Http\Request;

Route::post('/pay', function (Request $request) {
    $payment = $request->user()->pay(
        $request->get('amount')
    );

    return $payment->client_secret;
});

Payment Intent를 생성한 후 client_secret을 프론트엔드로 전달하면, 사용자가 브라우저에서 직접 결제를 완료할 수 있습니다. Stripe Payment Intent를 활용한 전체 결제 흐름 구성에 대한 자세한 내용은 Stripe 공식 문서를 참고하세요.

pay 메서드를 사용하면 Stripe 대시보드에서 활성화된 모든 기본 결제 수단이 고객에게 제공됩니다. 특정 결제 수단만 허용하려면 payWith 메서드를 사용하세요.

use Illuminate\Http\Request;

Route::post('/pay', function (Request $request) {
    $payment = $request->user()->payWith(
        $request->get('amount'), ['card', 'bancontact']
    );

    return $payment->client_secret;
});

WARNING

pay 및 payWith 메서드도 통화의 최소 단위 기준으로 금액을 받습니다. 달러를 사용하는 경우 센트 단위로 전달해야 합니다.

환불 처리

Stripe 결제를 환불하려면 refund 메서드를 사용합니다. 첫 번째 인수로 Stripe Payment Intent ID를 전달합니다.

$payment = $user->charge(100, $paymentMethodId);

$user->refund($payment->id);

결제 (Laravel Cashier Stripe)

청구서 (Invoices)

청구서 조회

청구 가능한 모델의 청구서 목록은 invoices 메서드로 간편하게 조회할 수 있습니다. 이 메서드는 Laravel\Cashier\Invoice 인스턴스의 컬렉션을 반환합니다:

$invoices = $user->invoices();

미결 청구서(pending invoices)도 함께 포함하려면 invoicesIncludingPending 메서드를 사용하세요:

$invoices = $user->invoicesIncludingPending();

특정 청구서를 ID로 조회하려면 findInvoice 메서드를 사용합니다:

$invoice = $user->findInvoice($invoiceId);

청구서 정보 표시

청구서 목록을 화면에 렌더링할 때는 청구서 인스턴스의 메서드를 활용해 필요한 정보를 표시할 수 있습니다. 예를 들어, 아래처럼 테이블 형태로 청구서 목록을 나열하고 각 항목에 다운로드 링크를 제공할 수 있습니다:

<table>
    @foreach ($invoices as $invoice)
        <tr>
            <td>{{ $invoice->date()->toFormattedDateString() }}</td>
            <td>{{ $invoice->total() }}</td>
            <td><a href="/user/invoice/{{ $invoice->id }}">다운로드</a></td>
        </tr>
    @endforeach
</table>

예정 청구서 조회

고객의 다음 청구서를 미리 확인하려면 upcomingInvoice 메서드를 사용합니다:

$invoice = $user->upcomingInvoice();

구독이 여러 개인 경우, 특정 구독의 예정 청구서만 조회할 수도 있습니다:

$invoice = $user->subscription('default')->upcomingInvoice();

구독 청구서 미리보기

요금제 변경 전에 청구서가 어떻게 생성될지 미리 확인하고 싶다면 previewInvoice 메서드를 사용하세요. 고객에게 실제로 청구되기 전에 금액을 확인할 수 있어 유용합니다:

$invoice = $user->subscription('default')->previewInvoice('price_yearly');

여러 가격을 한꺼번에 변경하는 경우, 배열로 전달하면 복수의 가격이 적용된 청구서를 미리볼 수 있습니다:

$invoice = $user->subscription('default')->previewInvoice(['price_yearly', 'price_metered']);

청구서 PDF 생성

PDF 청구서를 생성하려면 먼저 Cashier의 기본 PDF 렌더러인 Dompdf 라이브러리를 Composer로 설치해야 합니다:

composer require dompdf/dompdf

설치 후, 라우트나 컨트롤러에서 downloadInvoice 메서드를 사용해 PDF 다운로드 응답을 생성할 수 있습니다. 이 메서드는 파일 다운로드에 필요한 HTTP 응답을 자동으로 구성해 반환합니다:

use Illuminate\Http\Request;

Route::get('/user/invoice/{invoice}', function (Request $request, string $invoiceId) {
    return $request->user()->downloadInvoice($invoiceId);
});

기본적으로 청구서의 모든 데이터는 Stripe에 저장된 고객 및 청구 정보를 기반으로 구성되며, 파일명은 app.name 설정값을 따릅니다. 두 번째 인수로 배열을 전달하면 회사 정보나 상품 정보 등을 커스터마이징할 수 있습니다:

return $request->user()->downloadInvoice($invoiceId, [
    'vendor'    => '주식회사 예시',
    'product'   => '프리미엄 구독',
    'street'    => '테헤란로 123',
    'location'  => '서울특별시 강남구 06234',
    'phone'     => '+82 2-0000-0000',
    'email'     => 'info@example.co.kr',
    'url'       => 'https://example.co.kr',
    'vendorVat' => '123-45-67890',
]);

세 번째 인수로 파일명을 직접 지정할 수도 있습니다. .pdf 확장자는 자동으로 붙습니다:

return $request->user()->downloadInvoice($invoiceId, [], '2024년-1월-청구서');

커스텀 청구서 렌더러

Cashier는 기본적으로 dompdf PHP 라이브러리를 활용한 DompdfInvoiceRenderer를 사용합니다. 그러나 Laravel\Cashier\Contracts\InvoiceRenderer 인터페이스를 구현하면 원하는 렌더러로 교체할 수 있습니다.

예를 들어, 외부 PDF 변환 API를 호출하는 방식으로 청구서를 생성하고 싶다면 다음과 같이 구현할 수 있습니다:

use Illuminate\Support\Facades\Http;
use Laravel\Cashier\Contracts\InvoiceRenderer;
use Laravel\Cashier\Invoice;

class ApiInvoiceRenderer implements InvoiceRenderer
{
    /**
     * 청구서를 렌더링하고 PDF 원시 바이트를 반환합니다.
     */
    public function render(Invoice $invoice, array $data = [], array $options = []): string
    {
        $html = $invoice->view($data)->render();

        return Http::get('https://example.com/html-to-pdf', ['html' => $html])->get()->body();
    }
}

커스텀 렌더러를 구현한 후에는 config/cashier.php 설정 파일의 cashier.invoices.renderer 값을 해당 클래스명으로 변경하면 적용됩니다.

NOTE

Dompdf 대신 외부 PDF API를 사용할 경우, 청구서에 포함된 고객 정보가 외부 서버로 전송된다는 점을 반드시 고려하세요. 개인정보 보호 정책 및 관련 법규(예: 개인정보 보호법)에 따라 처리 방침을 검토하시기 바랍니다.

결제 (Laravel Cashier Stripe)

Checkout

Cashier Stripe는 Stripe Checkout을 지원합니다. Stripe Checkout은 Stripe가 제공하는 호스팅 결제 페이지로, 직접 결제 UI를 구현할 필요 없이 빠르고 안전하게 결제를 처리할 수 있습니다.

아래 문서에서는 Cashier와 함께 Stripe Checkout을 시작하는 방법을 설명합니다. 더 자세한 내용은 Stripe 공식 Checkout 문서도 함께 참고하세요.

상품 결제 (Product Checkouts)

Stripe 대시보드에 미리 등록된 상품에 대한 결제는 청구 가능 모델의 checkout 메서드를 사용합니다. 이 메서드는 새로운 Stripe Checkout 세션을 시작하며, 기본적으로 Stripe Price ID를 전달해야 합니다.

use Illuminate\Http\Request;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout('price_tshirt');
});

수량을 함께 지정하려면 다음과 같이 배열로 전달합니다.

use Illuminate\Http\Request;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout(['price_tshirt' => 15]);
});

이 라우트에 접근한 사용자는 Stripe의 Checkout 페이지로 리다이렉트됩니다. 결제 완료 또는 취소 시 기본적으로 home 라우트로 이동하지만, success_url과 cancel_url 옵션으로 원하는 URL을 지정할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout(['price_tshirt' => 1], [
        'success_url' => route('your-success-route'),
        'cancel_url' => route('your-cancel-route'),
    ]);
});

success_url에 Checkout 세션 ID를 쿼리 파라미터로 받고 싶다면, URL에 리터럴 문자열 {CHECKOUT_SESSION_ID}를 포함시키면 됩니다. Stripe가 이 플레이스홀더를 실제 세션 ID로 자동 치환합니다.

use Illuminate\Http\Request;
use Stripe\Checkout\Session;
use Stripe\Customer;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout(['price_tshirt' => 1], [
        'success_url' => route('checkout-success').'?session_id={CHECKOUT_SESSION_ID}',
        'cancel_url' => route('checkout-cancel'),
    ]);
});

Route::get('/checkout-success', function (Request $request) {
    $checkoutSession = $request->user()->stripe()->checkout->sessions->retrieve($request->get('session_id'));

    return view('checkout.success', ['checkoutSession' => $checkoutSession]);
})->name('checkout-success');

프로모션 코드

기본적으로 Stripe Checkout은 사용자가 직접 입력하는 프로모션 코드를 허용하지 않습니다. 이를 활성화하려면 allowPromotionCodes 메서드를 체이닝하면 됩니다.

use Illuminate\Http\Request;

Route::get('/product-checkout', function (Request $request) {
    return $request->user()
        ->allowPromotionCodes()
        ->checkout('price_tshirt');
});

단순 결제 (Single Charge Checkouts)

Stripe 대시보드에 미리 등록하지 않은 임시 상품에 대해 단건 결제를 진행하려면 checkoutCharge 메서드를 사용합니다. 결제 금액(센트 단위), 상품명, 수량을 차례로 전달합니다.

use Illuminate\Http\Request;

Route::get('/charge-checkout', function (Request $request) {
    return $request->user()->checkoutCharge(1200, '티셔츠', 5);
});

WARNING

checkoutCharge를 사용하면 Stripe가 매 호출마다 대시보드에 새 상품과 가격을 생성합니다. 따라서 반복적으로 판매하는 상품은 Stripe 대시보드에 미리 등록한 뒤 checkout 메서드를 사용하는 방식을 권장합니다.

구독 결제 (Subscription Checkouts)

WARNING

Stripe Checkout으로 구독을 처리하려면 Stripe 대시보드에서 customer.subscription.created 웹훅을 반드시 활성화해야 합니다. 이 웹훅이 수신되어야 데이터베이스에 구독 레코드와 구독 항목이 정상적으로 저장됩니다.

Cashier의 구독 빌더 메서드로 구독을 구성한 뒤 checkout을 호출하면 Stripe Checkout을 통해 구독을 시작할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->checkout();
});

상품 결제와 마찬가지로 완료/취소 URL을 커스터마이즈할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->checkout([
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

구독 결제에서도 프로모션 코드 입력을 허용할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/subscription-checkout', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->allowPromotionCodes()
        ->checkout();
});

WARNING

Stripe Checkout은 구독 관련 모든 옵션을 지원하지 않습니다. 구독 빌더에서 anchorBillingCycleOn, 일할 계산 설정, 결제 동작 설정 등은 Stripe Checkout 세션에서 적용되지 않습니다. 사용 가능한 파라미터는 Stripe Checkout Session API 문서를 확인하세요.

Stripe Checkout과 체험 기간

Stripe Checkout을 통해 시작하는 구독에도 체험 기간을 설정할 수 있습니다.

$checkout = Auth::user()->newSubscription('default', 'price_monthly')
    ->trialDays(3)
    ->checkout();

단, Stripe Checkout이 지원하는 최소 체험 기간은 48시간입니다. 48시간 미만으로 설정하면 적용되지 않으니 주의하세요.

구독 상태와 웹훅

Stripe와 Cashier는 웹훅을 통해 구독 상태를 업데이트합니다. 따라서 사용자가 결제 정보를 입력하고 애플리케이션으로 돌아왔을 때 구독이 아직 활성화되지 않았을 수도 있습니다. 이런 경우를 대비해 결제 또는 구독이 처리 중임을 사용자에게 안내하는 메시지를 표시하는 것이 좋습니다.

세금 ID 수집

Checkout 세션에서 고객의 세금 ID(사업자 등록번호 등)를 수집하려면 세션 생성 시 collectTaxIds 메서드를 호출합니다.

$checkout = $user->collectTaxIds()->checkout('price_tshirt');

이 메서드를 사용하면 Checkout 페이지에 "기업으로 구매하는 경우" 체크박스가 표시되며, 체크 시 세금 ID를 입력할 수 있는 필드가 나타납니다.

WARNING

애플리케이션의 서비스 프로바이더에서 이미 자동 세금 수집을 설정했다면, 이 기능은 자동으로 활성화되므로 collectTaxIds를 별도로 호출할 필요가 없습니다.

비회원 결제 (Guest Checkouts)

계정이 없는 비회원 사용자에게도 Checkout 세션을 제공할 수 있습니다. Checkout::guest 메서드를 사용하세요.

use Illuminate\Http\Request;
use Laravel\Cashier\Checkout;

Route::get('/product-checkout', function (Request $request) {
    return Checkout::guest()->create('price_tshirt', [
        'success_url' => route('your-success-route'),
        'cancel_url' => route('your-cancel-route'),
    ]);
});

회원 대상 Checkout과 마찬가지로, Laravel\Cashier\CheckoutBuilder 인스턴스에서 제공하는 다양한 메서드를 체이닝하여 비회원 Checkout 세션을 커스터마이즈할 수 있습니다.

use Illuminate\Http\Request;
use Laravel\Cashier\Checkout;

Route::get('/product-checkout', function (Request $request) {
    return Checkout::guest()
        ->withPromotionCode('promo-code')
        ->create('price_tshirt', [
            'success_url' => route('your-success-route'),
            'cancel_url' => route('your-cancel-route'),
        ]);
});

비회원 결제가 완료되면 Stripe가 checkout.session.completed 웹훅 이벤트를 발송합니다. Stripe 대시보드에서 웹훅을 설정하여 이 이벤트가 애플리케이션으로 전달되도록 구성하세요. 웹훅이 활성화된 후에는 Cashier 웹훅 처리를 통해 이벤트를 처리할 수 있습니다. 웹훅 페이로드에 포함된 객체는 checkout 객체이며, 이를 통해 주문 이행 처리를 진행하면 됩니다.

결제 실패 처리

구독 또는 단건 결제가 실패하는 경우가 있습니다. 이럴 때 Cashier는 Laravel\Cashier\Exceptions\IncompletePayment 예외를 발생시켜 결제가 완료되지 않았음을 알립니다. 이 예외를 catch한 후에는 두 가지 방법 중 하나로 대응할 수 있습니다.

방법 1: Cashier 내장 결제 확인 페이지로 리다이렉트

Cashier는 결제 확인을 위한 전용 페이지를 기본으로 제공합니다. 이 페이지는 Cashier의 서비스 프로바이더를 통해 이미 네임드 라우트로 등록되어 있습니다. IncompletePayment 예외를 catch한 뒤 아래와 같이 해당 페이지로 리다이렉트할 수 있습니다.

use Laravel\Cashier\Exceptions\IncompletePayment;

try {
    $subscription = $user->newSubscription('default', 'price_monthly')
        ->create($paymentMethod);
} catch (IncompletePayment $exception) {
    return redirect()->route(
        'cashier.payment',
        [$exception->payment->id, 'redirect' => route('home')]
    );
}

결제 확인 페이지에서는 고객이 신용카드 정보를 다시 입력하거나, Stripe에서 요구하는 추가 인증(예: 3D Secure 확인)을 수행하게 됩니다. 결제가 완료되면 위에서 redirect 파라미터로 지정한 URL로 이동하며, 이때 message(문자열)와 success(정수) 쿼리 스트링이 URL에 추가됩니다.

결제 확인 페이지에서 지원하는 결제 수단은 다음과 같습니다.

신용카드 (Credit Cards)
Alipay
Bancontact
BECS Direct Debit
EPS
Giropay
iDEAL
SEPA Direct Debit

방법 2: Stripe의 자동 청구 이메일 활용

Cashier 전용 페이지 대신, Stripe 대시보드에서 자동 청구 이메일을 설정하여 Stripe가 결제 확인을 처리하도록 위임할 수도 있습니다. 다만 이 방법을 사용하더라도, IncompletePayment 예외가 catch되면 고객에게 결제 확인 안내 이메일이 발송될 것임을 반드시 알려야 합니다.

IncompletePayment 예외는 Billable 트레이트를 사용하는 모델의 charge, invoiceFor, invoice 메서드에서 발생할 수 있습니다. 구독과 관련해서는 SubscriptionBuilder의 create 메서드, 그리고 Subscription 및 SubscriptionItem 모델의 incrementAndInvoice, swapAndInvoice 메서드에서도 예외가 발생할 수 있습니다.

기존 구독에 미완료 결제가 있는지 확인하려면 billable 모델 또는 구독 인스턴스에서 hasIncompletePayment 메서드를 사용하세요.

if ($user->hasIncompletePayment('default')) {
    // 미완료 결제 처리 로직
}

if ($user->subscription('default')->hasIncompletePayment()) {
    // 미완료 결제 처리 로직
}

미완료 결제의 구체적인 상태는 예외 인스턴스의 payment 속성을 통해 확인할 수 있습니다.

use Laravel\Cashier\Exceptions\IncompletePayment;

try {
    $user->charge(1000, 'pm_card_threeDSecure2Required');
} catch (IncompletePayment $exception) {
    // 결제 인텐트 상태 확인
    $exception->payment->status;

    // 세부 조건 확인
    if ($exception->payment->requiresPaymentMethod()) {
        // 결제 수단이 필요한 경우
    } elseif ($exception->payment->requiresConfirmation()) {
        // 추가 확인이 필요한 경우
    }
}

결제 확인 (Confirming Payments)

일부 결제 수단은 결제를 확인하기 위해 추가 데이터를 요구합니다. 예를 들어 SEPA 결제 수단은 결제 과정에서 "위임(mandate)" 데이터가 필요합니다. 이러한 데이터는 withPaymentConfirmationOptions 메서드를 통해 Cashier에 전달할 수 있습니다.

$subscription->withPaymentConfirmationOptions([
    'mandate_data' => '...',
])->swap('price_xxx');

결제 확인 시 사용할 수 있는 모든 옵션은 Stripe API 문서를 참고하세요.

결제 (Laravel Cashier Stripe)

강력한 고객 인증 (Strong Customer Authentication)

유럽에 기반을 둔 사업체나 고객을 대상으로 서비스를 운영한다면, EU의 강력한 고객 인증(SCA, Strong Customer Authentication) 규정을 준수해야 합니다. 이 규정은 결제 사기를 방지하기 위해 2019년 9월 유럽연합에 의해 시행되었습니다. Stripe와 Cashier는 SCA 규정을 준수하는 애플리케이션을 구축할 수 있도록 미리 준비되어 있습니다.

WARNING

시작하기 전에 Stripe의 PSD2 및 SCA 가이드와 새로운 SCA API 문서를 반드시 먼저 검토하시기 바랍니다.

추가 확인이 필요한 결제

SCA 규정에 따라 결제를 확인하고 처리하기 위해 추가 인증이 필요한 경우가 있습니다. 이런 상황이 발생하면 Cashier는 Laravel\Cashier\Exceptions\IncompletePayment 예외를 발생시켜 추가 인증이 필요하다는 사실을 알려줍니다. 이 예외를 처리하는 방법에 대한 자세한 내용은 결제 실패 처리 문서를 참고하세요.

Stripe 또는 Cashier가 표시하는 결제 확인 화면은 특정 은행이나 카드 발급사의 결제 흐름에 맞게 구성되며, 추가 카드 확인, 소액 임시 청구, 별도 기기 인증 등 다양한 형태의 인증 절차가 포함될 수 있습니다.

Incomplete 및 Past Due 상태

결제에 추가 확인이 필요한 경우, 구독은 stripe_status 데이터베이스 컬럼에 incomplete 또는 past_due 상태로 유지됩니다. 결제 확인이 완료되고 Stripe가 웹훅을 통해 애플리케이션에 완료 사실을 알리면, Cashier가 자동으로 해당 고객의 구독을 활성화합니다.

incomplete 및 past_due 상태에 대한 자세한 내용은 이 상태들에 대한 추가 문서를 참고하세요.

오프세션 결제 알림

SCA 규정에 따르면 구독이 활성 상태이더라도 고객이 주기적으로 결제 정보를 인증해야 할 수 있습니다. 예를 들어, 구독이 갱신되는 시점에 이러한 상황이 발생할 수 있습니다. Cashier는 오프세션(off-session) 결제 확인이 필요할 때 고객에게 알림을 전송할 수 있습니다.

이 기능을 활성화하려면 CASHIER_PAYMENT_NOTIFICATION 환경 변수에 사용할 알림 클래스를 지정하세요. 기본적으로 이 알림은 비활성화되어 있습니다. Cashier에는 이 용도로 바로 사용할 수 있는 알림 클래스가 기본 포함되어 있지만, 필요에 따라 직접 만든 알림 클래스를 지정할 수도 있습니다.

CASHIER_PAYMENT_NOTIFICATION=Laravel\Cashier\Notifications\ConfirmPayment

오프세션 결제 확인 알림이 정상적으로 전달되려면 다음 두 가지를 확인해야 합니다.

애플리케이션에 Stripe 웹훅이 설정되어 있고, Stripe 대시보드에서 invoice.payment_action_required 웹훅 이벤트가 활성화되어 있어야 합니다.
Billable 모델에 Laravel의 Illuminate\Notifications\Notifiable 트레이트가 사용되고 있어야 합니다.

WARNING

고객이 추가 확인이 필요한 결제를 직접(수동으로) 진행하는 경우에도 알림이 전송됩니다. 안타깝게도 Stripe는 해당 결제가 수동으로 이루어진 것인지, 오프세션으로 처리된 것인지 구분할 방법이 없습니다. 다만, 고객이 이미 결제를 확인한 후 결제 페이지를 다시 방문하면 "결제 성공" 메시지만 표시될 뿐입니다. 동일한 결제가 실수로 두 번 확인되거나 이중 청구되는 상황은 발생하지 않으니 안심하셔도 됩니다.

Stripe SDK

Cashier의 많은 객체는 Stripe SDK 객체를 감싸는 래퍼(wrapper)입니다. Stripe 객체에 직접 접근하고 싶다면 asStripe 메서드를 사용하면 편리합니다.

$stripeSubscription = $subscription->asStripeSubscription();

$stripeSubscription->application_fee_percent = 5;

$stripeSubscription->save();

Stripe 구독을 직접 업데이트하려면 updateStripeSubscription 메서드를 사용할 수도 있습니다.

$subscription->updateStripeSubscription(['application_fee_percent' => 5]);

Stripe\StripeClient를 직접 사용하고 싶다면 Cashier 클래스의 stripe 메서드를 호출하면 됩니다. 예를 들어, 아래와 같이 Stripe 계정에 등록된 가격 목록을 조회할 수 있습니다.

use Laravel\Cashier\Cashier;

$prices = Cashier::stripe()->prices->all();

결제 (Laravel Cashier Stripe)

테스트

Cashier를 사용하는 애플리케이션을 테스트할 때, Stripe API에 대한 실제 HTTP 요청을 모킹(mocking)하는 방법을 고려할 수 있습니다. 그러나 이 방식을 사용하면 Cashier 내부 동작의 일부를 직접 재구현해야 하므로 권장하지 않습니다. 대신, 실제 Stripe API에 요청을 보내는 방식으로 테스트하는 것을 권장합니다. 속도는 다소 느릴 수 있지만, 애플리케이션이 실제로 올바르게 동작하는지 훨씬 높은 신뢰도로 검증할 수 있습니다. 처리 시간이 긴 테스트는 별도의 Pest / PHPUnit 테스트 그룹으로 분리해 관리하면 좋습니다.

또한 Cashier 자체적으로 이미 충실한 테스트 스위트를 갖추고 있으므로, 여러분은 Cashier 내부 동작을 검증하는 데 시간을 쏟기보다 자신의 애플리케이션의 구독·결제 흐름에 집중해 테스트를 작성하면 됩니다.

시작하기

테스트를 시작하려면 phpunit.xml 파일에 Stripe 테스트용 시크릿 키를 추가하세요:

<env name="STRIPE_SECRET" value="sk_test_<your-key>"/>

이렇게 설정하면 테스트 실행 중 Cashier가 Stripe와 통신할 때마다 실제 Stripe 테스트 환경으로 API 요청이 전송됩니다.

테스트를 원활하게 진행하려면, Stripe 테스트 계정에 테스트에서 사용할 구독 플랜과 가격(Price)을 미리 등록해 두는 것이 좋습니다.

NOTE

카드 거절, 결제 실패 등 다양한 결제 시나리오를 테스트하려면 Stripe에서 제공하는 테스트용 카드 번호 및 토큰을 활용하세요. 실제 카드 정보를 사용하지 않고도 다양한 오류 상황을 재현할 수 있습니다.