Laravel Cashier (Stripe)

번역일: 2026년 7월 2일

Laravel Cashier (Stripe)

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

소개

Laravel Cashier Stripe는 Stripe의 구독 결제 서비스를 편리하게 사용할 수 있도록 유연하고 표현력 있는 인터페이스를 제공합니다. Cashier를 사용하면 반복적으로 작성하게 되는 구독 청구 관련 보일러플레이트 코드를 대부분 직접 구현할 필요가 없습니다. 기본적인 구독 관리 외에도 쿠폰 적용, 구독 변경, 구독 수량 관리, 취소 유예 기간 설정, 인보이스 PDF 생성 등 다양한 기능을 제공합니다.

Laravel Cashier (Stripe)

소개

Laravel Cashier Stripe는 Stripe의 구독 결제 서비스를 위한 표현력 있고 유연한 인터페이스를 제공합니다. 반복적으로 작성하기 번거로운 구독 결제 관련 보일러플레이트 코드를 대부분 대신 처리해 줍니다. 기본적인 구독 관리 외에도, Cashier는 쿠폰 적용, 구독 플랜 변경, 구독 "수량" 관리, 해지 유예 기간 처리, 그리고 인보이스 PDF 생성까지 지원합니다.

Laravel Cashier (Stripe)

Cashier 업그레이드

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

WARNING

Cashier는 변경 사항으로 인한 오류를 방지하기 위해 Stripe API 버전을 고정하여 사용합니다. Cashier 16은 Stripe API 버전 2025-06-30.basil을 사용합니다. Stripe API 버전은 새로운 Stripe 기능 및 개선 사항을 활용하기 위해 마이너 릴리즈 시점에 업데이트됩니다.

Laravel Cashier (Stripe)

설치

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

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 공식 문서를 참고하세요.

Laravel Cashier (Stripe)

설정

Billable 모델

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

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier는 기본적으로 App\Models\User 클래스를 과금 모델로 사용합니다. 다른 모델을 사용하려면 useCustomerModel 메서드로 변경할 수 있습니다. 이 메서드는 AppServiceProvider의 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 키를 설정합니다. 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)입니다. .env 파일에서 CASHIER_CURRENCY 환경 변수를 설정해 통화를 변경할 수 있습니다. 예를 들어 원화(KRW)로 변경하려면 다음과 같이 설정합니다.

CASHIER_CURRENCY=krw

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

CASHIER_CURRENCY_LOCALE=ko_KR

WARNING

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

세금 설정

Stripe Tax를 활용하면 Stripe에서 생성되는 모든 청구서에 세금을 자동으로 계산할 수 있습니다. 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 메서드에 전달하는 price_deluxe_album은 Stripe에서 정의한 "가격 식별자(Price ID)"입니다. Stripe에서 "가격(price)"이란 특정 상품에 대해 설정된 판매 단가를 의미합니다.

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

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

상품을 판매할 때는 보통 Cart(장바구니)나 Order(주문) 모델을 통해 완료된 주문을 추적합니다. 고객이 Stripe Checkout에서 결제를 마치고 돌아왔을 때, 어떤 주문에 대한 결제였는지 연결하려면 기존 주문 ID를 Stripe Checkout 세션에 함께 전달해야 합니다.

이를 위해 checkout 메서드에 metadata 배열을 전달할 수 있습니다. 아래 예시에서는 사용자가 결제를 시작할 때 pending 상태의 Order를 먼저 생성합니다. 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로 대체해 주는 템플릿 변수입니다. 고객이 결제를 완료하고 돌아오면, 이 값을 통해 어떤 Checkout 세션이었는지 확인할 수 있습니다.

이제 성공 라우트를 정의해 봅시다. 이 라우트에서 세션 ID로 Stripe Checkout 세션을 조회하고, 메타데이터에서 주문 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을 활용하면 구독형 서비스도 깔끔하게 구현할 수 있습니다.

아래 예시를 통해 구독 판매 흐름을 살펴보겠습니다. 서비스에 "Basic" 플랜이 있고, 월간(price_basic_monthly)과 연간(price_basic_yearly) 두 가지 가격이 Stripe 대시보드의 pro_basic 상품에 묶여 있다고 가정합니다. 추가로 "Expert" 플랜(pro_expert)도 있다고 가정합니다.

고객이 가격 안내 페이지에서 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)을 활용하면 별도의 UI를 직접 개발하지 않아도 됩니다. 이 포털에서 고객은 청구서 다운로드, 결제 수단 변경, 구독 플랜 전환 등을 직접 처리할 수 있습니다.

먼저, 청구 포털로 이동하는 링크나 버튼을 애플리케이션에 추가합니다.

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

다음으로, Stripe 고객 청구 포털 세션을 시작하고 사용자를 포털로 리디렉션하는 라우트를 정의합니다. 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 청구 포털에서 구독을 취소하면 Cashier가 해당 웹훅을 수신하여 데이터베이스의 구독 상태를 자동으로 "취소됨"으로 업데이트합니다.

Laravel Cashier (Stripe)

고객 조회

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

use Laravel\Cashier\Cashier;

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

고객 생성

구독을 즉시 시작하지 않고 Stripe에 고객 정보만 먼저 등록해야 하는 경우, createAsStripeCustomer 메서드를 사용하세요:

$stripeCustomer = $user->createAsStripeCustomer();

Stripe에 고객이 생성되면 이후 원하는 시점에 구독을 시작할 수 있습니다. Stripe API가 지원하는 고객 생성 파라미터를 추가로 전달하려면 $options 배열을 인자로 넘기세요:

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

이미 Stripe 고객으로 등록된 모델의 Stripe 고객 객체를 가져오려면 asStripeCustomer 메서드를 사용하세요:

$stripeCustomer = $user->asStripeCustomer();

해당 모델이 이미 Stripe 고객으로 등록되어 있는지 확인하기 어려운 경우에는 createOrGetStripeCustomer 메서드가 유용합니다. Stripe에 고객이 존재하면 해당 객체를 반환하고, 없으면 새로 생성합니다:

$stripeCustomer = $user->createOrGetStripeCustomer();

고객 정보 수정

Stripe에 저장된 고객 정보를 직접 수정하려면 updateStripeCustomer 메서드를 사용하세요. Stripe API가 지원하는 고객 수정 옵션을 배열로 전달합니다:

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

잔액 관리

Stripe는 고객 계정에 잔액(balance)을 적립하거나 차감하는 기능을 제공합니다. 이 잔액은 이후 생성되는 인보이스에 자동으로 반영됩니다. 고객의 현재 잔액은 balance 메서드로 확인할 수 있으며, 고객의 통화에 맞는 형식의 문자열로 반환됩니다:

$balance = $user->balance();

잔액을 적립하려면 creditBalance 메서드를 사용하세요. 필요하면 설명도 함께 전달할 수 있습니다:

$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 관리

Cashier를 통해 고객의 세금 ID를 손쉽게 관리할 수 있습니다. taxIds 메서드는 고객에게 등록된 모든 세금 ID를 컬렉션으로 반환합니다:

$taxIds = $user->taxIds();

특정 세금 ID를 식별자로 조회하려면 findTaxId 메서드를 사용하세요:

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

새로운 세금 ID를 등록하려면 유효한 타입과 값을 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에도 해당 변경 사항을 반영해야 합니다. 두 곳의 데이터가 일치해야 청구 관련 기능이 정확하게 동작합니다.

이를 자동화하려면 청구 대상 모델의 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에 정보를 동기화합니다.

동기화에 사용할 컬럼을 커스터마이징하려면 Cashier가 제공하는 메서드를 오버라이드하면 됩니다. 예를 들어, Stripe에 전송할 고객 이름을 company_name 컬럼으로 변경하려면 stripeName 메서드를 오버라이드하세요:

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

마찬가지로 stripeEmail, stripePhone(최대 20자), stripeAddress, stripePreferredLocales 메서드도 오버라이드할 수 있습니다. 이 메서드들은 Stripe 고객 객체 수정 시 각 대응 파라미터로 전달됩니다. 동기화 과정 전체를 직접 제어하고 싶다면 syncStripeCustomerDetails 메서드 자체를 오버라이드하세요.

청구 포털

Stripe는 고객이 구독, 결제 수단, 청구 내역을 직접 관리할 수 있는 청구 포털을 제공합니다. 컨트롤러나 라우트에서 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'));

결제 수단

결제 수단 저장

구독을 생성하거나 단건 결제를 처리하려면 먼저 결제 수단을 저장하고 Stripe에서 발급한 식별자를 가져와야 합니다. 구독용 결제 수단과 단건 결제용 결제 수단은 처리 방식이 다르므로, 아래에서 각각 설명합니다.

구독용 결제 수단

구독에 사용할 신용카드 정보를 안전하게 수집하려면 Stripe의 "Setup Intents" API를 사용해야 합니다. Setup Intent는 "이 결제 수단을 나중에 청구에 사용하겠다"는 의도를 Stripe에 미리 등록하는 개념입니다. Cashier의 Billable 트레이트에는 이를 손쉽게 생성할 수 있는 createSetupIntent 메서드가 포함되어 있습니다. 결제 수단 입력 폼을 렌더링하는 라우트나 컨트롤러에서 이 메서드를 호출하세요.

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

Setup Intent를 생성한 뒤 뷰에 전달했다면, 해당 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 메서드를 사용해 카드를 검증하고, 안전한 "결제 수단 식별자"를 Stripe로부터 가져올 수 있습니다.

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 {
        // 카드 검증 성공...
    }
});

카드 검증이 완료되면 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)

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

구독 생성

구독을 생성하려면 먼저 청구 가능한 모델(Billable Model) 인스턴스를 가져옵니다. 일반적으로 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의 첫 번째 인수는 구독의 내부 타입(type)입니다. 애플리케이션에 구독이 하나뿐이라면 default 또는 primary로 지정하면 됩니다. 이 타입은 애플리케이션 내부에서만 사용되며, 사용자에게 직접 노출되는 값이 아닙니다. 공백을 포함해서는 안 되며, 구독 생성 후에는 절대 변경하면 안 됩니다. 두 번째 인수는 사용자가 구독할 Stripe 가격 식별자(price ID)입니다.

create 메서드는 Stripe 결제 수단 식별자 또는 Stripe PaymentMethod 객체를 받아 구독을 시작하고, 데이터베이스의 청구 모델에 Stripe 고객 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)을 지정하려면, 구독 빌더에서 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);

여기서 전달하는 프로모션 코드 ID는 Stripe API가 내부적으로 할당한 ID이며, 고객에게 공개되는 프로모션 코드 문자열이 아닙니다. 고객 공개용 코드로 API ID를 조회하려면 findPromotionCode 메서드를 사용하세요.

// 고객 공개용 코드로 프로모션 코드 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.99
}

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

$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 API ID를 사용해야 합니다. 고객 또는 구독에는 한 번에 하나의 쿠폰 또는 프로모션 코드만 적용할 수 있습니다.

자세한 내용은 Stripe 공식 문서의 쿠폰 및 프로모션 코드 항목을 참고하세요.

기존 고객에게 구독 추가하기

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

use App\Models\User;

$user = User::find(1);

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

Stripe 대시보드에서 구독 생성하기

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

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

마지막으로, 동일한 타입의 활성 구독은 반드시 하나만 유지해야 합니다. 같은 타입의 default 구독이 두 개 있는 경우, 두 구독 모두 데이터베이스에 동기화되지만 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 제품(product)을 구독 중인지 확인합니다. Stripe에서 제품(product)은 여러 가격(price)의 묶음입니다. 아래 예시에서는 사용자의 default 구독이 "premium" 제품을 구독 중인지 확인합니다. 제품 식별자는 Stripe 대시보드의 것과 일치해야 합니다.

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 메서드는 항상 가장 최근 구독을 반환합니다. 예를 들어 default 타입의 구독 레코드가 두 개 있다면, 하나는 만료된 과거 구독이고 다른 하나는 현재 활성 구독일 수 있습니다. 항상 가장 최근 구독이 반환되며, 이전 구독 기록은 이력 조회를 위해 데이터베이스에 보존됩니다.

취소된 구독 상태

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

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

구독이 취소되었지만 아직 유예 기간(grace period) 중인지도 확인할 수 있습니다. 예를 들어 사용자가 3월 5일에 구독을 취소했고 만료 예정일이 3월 10일이라면, 3월 10일까지는 유예 기간입니다. 유예 기간 동안은 subscribed 메서드가 여전히 true를 반환합니다.

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

구독이 취소되었고 유예 기간도 끝났는지 확인하려면 ended 메서드를 사용합니다.

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

미완료(Incomplete) 및 기한 초과(Past Due) 상태

구독 생성 후 추가 결제 인증이 필요한 경우, 구독은 incomplete 상태로 표시됩니다. 구독 상태는 Cashier의 subscriptions 테이블의 stripe_status 컬럼에 저장됩니다.

마찬가지로, 가격 변경(swap) 시 추가 결제 인증이 필요하면 구독은 past_due 상태로 표시됩니다. 두 상태 모두 고객이 결제를 확인하기 전까지는 구독이 활성화되지 않습니다. 미완료 결제 여부는 hasIncompletePayment 메서드로 확인할 수 있습니다.

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

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

미완료 결제가 있는 경우, Cashier의 결제 확인 페이지로 사용자를 안내해야 합니다. latestPayment 메서드로 최근 결제 ID를 가져와 링크를 생성하세요.

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

past_due 또는 incomplete 상태에서도 구독을 활성 상태로 간주하고 싶다면, Cashier가 제공하는 keepPastDueSubscriptionsActive와 keepIncompleteSubscriptionsActive 메서드를 사용합니다. 보통 App\Providers\AppServiceProvider의 register 메서드에서 호출합니다.

use Laravel\Cashier\Cashier;

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

WARNING

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

구독 스코프(Scopes)

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

// 모든 활성 구독 조회...
$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 가격 식별자를 전달합니다. 가격을 변경하면 이전에 취소된 구독도 재활성화된다고 가정합니다. 가격 식별자는 Stripe 대시보드의 것과 일치해야 합니다.

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는 가격 변경 시 일할 계산을 적용합니다. 일할 계산 없이 가격만 변경하려면 noProrate 메서드를 사용합니다.

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

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

WARNING

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

구독 수량

구독에 "수량(quantity)" 개념이 필요한 경우가 있습니다. 예를 들어 프로젝트 관리 애플리케이션에서 프로젝트당 월 10,000원을 청구하는 방식입니다. 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');

복수 상품 구독

복수 상품 구독을 사용하면 하나의 구독에 여러 청구 상품을 할당할 수 있습니다. 예를 들어, 기본 구독료가 월 10,000원인 고객 서비스 헬프데스크 애플리케이션에서 월 15,000원짜리 실시간 채팅 부가 상품을 추가하는 경우를 생각해 보세요. 복수 상품 구독 정보는 Cashier의 subscription_items 테이블에 저장됩니다.

구독 생성 시 newSubscription의 두 번째 인수로 가격 배열을 전달하여 복수 상품을 지정할 수 있습니다.

use Illuminate\Http\Request;

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

    // ...
});

위 예시에서 고객의 default 구독에는 두 가지 가격이 연결됩니다. 각 가격은 각자의 청구 주기에 따라 청구됩니다. 가격별로 수량을 지정하려면 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_basic을 price_pro로 업그레이드하려는 경우를 생각해 보세요.

use App\Models\User;

$user = User::find(1);

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

위 예시를 실행하면 price_basic 구독 항목은 삭제되고, price_chat 항목은 유지되며, price_pro 항목이 새로 생성됩니다.

swap 메서드에 키/값 배열을 전달하여 구독 항목 옵션(예: 수량)을 지정할 수도 있습니다.

$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 테이블에 여러 구독 "항목(item)"이 저장됩니다. 구독의 items 관계를 통해 접근할 수 있습니다.

use App\Models\User;

$user = User::find(1);

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

// 특정 항목의 Stripe 가격과 수량 조회...
$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);

    // ...
});

나중에 고객이 연간 구독으로 전환하고 싶다면, swimming 구독의 가격을 교체하면 됩니다.

$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);

특정 미터에 대한 고객의 이벤트 요약을 조회하려면 Billable 인스턴스의 meterEventSummaries 메서드를 사용합니다.

$user = User::find(1);

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

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

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

모든 미터 목록을 조회하려면 Billable 인스턴스의 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 메서드는 구독 청구에만 적용됩니다. Cashier로 단건 결제를 처리할 때는 해당 시점에 세율을 직접 지정해야 합니다.

세율 동기화

taxRates 메서드가 반환하는 하드코딩된 세율 ID를 변경하더라도, 기존 구독의 세율 설정은 그대로 유지됩니다. 기존 구독에 새로운 세율을 반영하려면 구독 인스턴스의 syncTaxRates 메서드를 호출해야 합니다.

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

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

세금 면제

Cashier는 고객의 세금 면제 여부를 확인하는 isNotTaxExempt, isTaxExempt, reverseChargeApplies 메서드도 제공합니다. 이 메서드들은 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()->plus(days: 10)
);

마지막으로, 연결된 사용자 모델을 삭제하기 전에는 항상 구독을 먼저 취소해야 합니다.

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

$user->delete();

구독 재개

취소된 구독을 재개하려면 구독 인스턴스의 resume 메서드를 호출합니다. 구독을 재개하려면 고객이 아직 유예 기간 내에 있어야 합니다.

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

고객이 구독을 취소한 후 만료 전에 구독을 재개하면 즉시 청구되지 않습니다. 대신 구독이 재활성화되어 원래 청구 주기에 따라 다음 결제가 이루어집니다.

Laravel Cashier (Stripe)

구독 체험 기간 (Trial)

결제 수단을 먼저 수집하는 방식

체험 기간을 제공하면서 결제 수단 정보를 미리 수집하고 싶다면, 구독 생성 시 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)에 설정한 기본 체험 기간은 Cashier가 덮어씁니다.

WARNING

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

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

use Illuminate\Support\Carbon;

$user->newSubscription('default', 'price_monthly')
    ->trialUntil(Carbon::now()->plus(days: 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()->plus(days: 10),
]);

WARNING

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

Cashier는 이처럼 실제 구독과 연결되지 않은 체험을 **"일반 체험(generic trial)"**이라고 부릅니다. 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()) {
    // 사용자가 "일반 체험" 기간 중입니다 (구독 미생성)...
}

NOTE

onTrial()은 일반 체험과 구독 연결 체험 모두를 포함하고, onGenericTrial()은 실제 구독 없이 trial_ends_at만 설정된 경우만 감지합니다. 두 메서드의 차이를 명확히 이해하고 상황에 맞게 사용하세요.

체험 기간 연장

구독이 생성된 이후에도 extendTrial 메서드로 체험 기간을 연장할 수 있습니다. 체험이 이미 만료되어 실제 청구가 시작된 상태라도 연장이 가능하며, 연장된 체험 기간만큼 다음 인보이스 금액에서 차감됩니다:

use App\Models\User;

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

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

// 현재 체험 종료일에서 5일 추가 연장
$subscription->extendTrial(
    $subscription->trial_ends_at->plus(days: 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

생성된 웹훅은 기본적으로 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 보호를 우회해야 합니다. 따라서 bootstrap/app.php에서 stripe/* 경로를 CSRF 검증 대상에서 제외해야 합니다.

->withMiddleware(function (Middleware $middleware): void {
    $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 계정 대시보드에서 확인할 수 있습니다.

Laravel Cashier (Stripe)

단건 결제 (Single Charges)

단순 결제

청구 가능 모델 인스턴스에서 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,
]);

기존 고객이나 사용자 없이도 charge 메서드를 사용할 수 있습니다. 이 경우 청구 가능 모델의 새 인스턴스에서 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'],
]);

invoicePrice와 유사하게, 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 인스턴스로 감싸진 Payment Intent를 반환합니다.

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 메서드도 금액을 해당 통화의 최소 단위로 지정해야 합니다. 미국 달러의 경우 센트 단위로 전달하세요(예: 1달러 = 100).

결제 환불

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

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

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

인보이스

인보이스 조회

invoices 메서드를 사용하면 청구 가능한 모델의 인보이스 목록을 쉽게 가져올 수 있습니다. 이 메서드는 Laravel\Cashier\Invoice 인스턴스의 컬렉션을 반환합니다:

$invoices = $user->invoices();

아직 처리 중인(pending) 인보이스도 함께 포함하려면 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' => '02-1234-5678',
    'email' => 'info@example.com',
    'url' => 'https://example.com',
    'vendorVat' => '123-45-67890',
]);

세 번째 인자로 커스텀 파일명을 지정할 수도 있습니다. 지정한 이름 뒤에는 자동으로 .pdf 확장자가 붙습니다:

return $request->user()->downloadInvoice($invoiceId, [], 'my-invoice');

커스텀 인보이스 렌더러

Cashier는 기본적으로 dompdf 라이브러리를 사용하는 DompdfInvoiceRenderer로 PDF를 생성하지만, 필요에 따라 커스텀 렌더러를 구현해 사용할 수 있습니다. Laravel\Cashier\Contracts\InvoiceRenderer 인터페이스를 구현하면 외부 PDF 변환 API 등 원하는 방식으로 PDF를 생성할 수 있습니다:

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 값을 해당 클래스명으로 변경하면 됩니다.

Laravel Cashier (Stripe)

Checkout

Cashier Stripe는 Stripe Checkout을 지원합니다. Stripe Checkout은 미리 구축된 호스팅 결제 페이지를 제공하여, 직접 결제 페이지를 구현하는 번거로움을 줄여줍니다.

Stripe Checkout에 대한 더 자세한 내용은 Stripe 공식 Checkout 문서도 함께 참고하시기 바랍니다.

상품 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 옵션으로 직접 지정할 수 있습니다.

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_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 메서드를 호출하면 Checkout 페이지에서 프로모션 코드 입력란을 활성화할 수 있습니다.

use Illuminate\Http\Request;

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

단건 결제 Checkout

Stripe 대시보드에 사전 등록하지 않은 임시 상품도 checkoutCharge 메서드로 바로 결제 세션을 만들 수 있습니다. 금액(센트 단위), 상품명, 수량을 순서대로 전달합니다.

use Illuminate\Http\Request;

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

WARNING

checkoutCharge 메서드를 사용하면 Stripe 대시보드에 상품과 가격이 매번 새로 생성됩니다. 반복적으로 판매하는 상품이라면 Stripe 대시보드에 미리 등록한 후 checkout 메서드를 사용하는 것을 권장합니다.

구독 Checkout

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();
});

상품 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'),
        ]);
});

구독 Checkout에도 프로모션 코드를 활성화할 수 있습니다.

use Illuminate\Http\Request;

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

WARNING

Stripe Checkout은 구독 시작 시 모든 청구 옵션을 지원하지 않습니다. 구독 빌더에서 anchorBillingCycleOn, 비례 배분(proration) 설정, 결제 동작(payment behavior) 설정은 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를 별도로 호출할 필요가 없습니다.

게스트 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'),
        ]);
});

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

Laravel Cashier (Stripe)

결제 실패 처리

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

첫 번째 방법은 Cashier에 내장된 결제 확인 페이지로 고객을 리디렉션하는 것입니다. 이 페이지는 Cashier의 서비스 프로바이더가 자동으로 네임드 라우트를 등록하므로, 별도 설정 없이 바로 사용할 수 있습니다. IncompletePayment 예외를 잡아서 다음과 같이 리디렉션하면 됩니다:

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

두 번째 방법은 Stripe의 자동 결제 이메일 기능을 활용하는 것입니다. 이 경우 결제 확인 페이지로 직접 리디렉션하는 대신, Stripe 대시보드에서 자동 청구 이메일을 설정할 수 있습니다. 단, IncompletePayment 예외가 발생했을 때는 사용자에게 결제 안내 이메일이 발송될 예정임을 명확히 알려주어야 합니다.

NOTE

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()) {
        // 추가 확인이 필요한 경우...
    }
}

결제 확인

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

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

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

Laravel Cashier (Stripe)

강력한 고객 인증 (SCA)

유럽에 사업자 또는 고객이 있는 경우, EU의 강력한 고객 인증(Strong Customer Authentication, SCA) 규정을 준수해야 합니다. 이 규정은 결제 사기 방지를 목적으로 2019년 9월 EU에서 시행되었습니다. 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는 해당 결제가 수동으로 이루어진 것인지 오프세션으로 이루어진 것인지 구별할 수 없습니다. 다만, 고객이 이미 결제를 확인한 후 결제 페이지를 다시 방문하면 "결제 성공" 메시지가 표시될 뿐이며, 동일한 결제가 중복으로 승인되거나 이중 청구가 발생하는 일은 없습니다.

Laravel Cashier (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 메서드를 호출하면 됩니다. 예를 들어, 아래와 같이 StripeClient 인스턴스를 통해 Stripe 계정의 가격 목록을 가져올 수 있습니다:

use Laravel\Cashier\Cashier;

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

Laravel Cashier (Stripe)

테스트

Cashier를 사용하는 애플리케이션을 테스트할 때, Stripe API로 향하는 실제 HTTP 요청을 목(mock)으로 대체하는 방법을 생각할 수 있습니다. 그러나 이 방식은 Cashier 내부 동작을 부분적으로 직접 재구현해야 하므로 권장하지 않습니다. 대신, 실제 Stripe API에 요청을 보내는 방식으로 테스트하는 것을 추천합니다.

실제 API를 사용하면 테스트 속도는 다소 느려지지만, 애플리케이션이 실제 환경에서 정상적으로 동작하는지 훨씬 높은 신뢰도로 확인할 수 있습니다. 속도가 느린 테스트는 별도의 Pest / PHPUnit 테스트 그룹으로 분리해 관리하면 됩니다.

또한 Cashier 자체에는 이미 충실한 테스트 스위트가 포함되어 있으므로, 여러분은 Cashier의 내부 동작을 검증하는 데 시간을 쏟을 필요가 없습니다. 여러분의 애플리케이션에서 구현한 구독 및 결제 흐름에만 집중해서 테스트를 작성하세요.

시작하기

먼저 phpunit.xml 파일에 Stripe 테스트용 시크릿 키를 추가합니다.

<env name="STRIPE_SECRET" value="sk_test_<your-key>"/>

이렇게 설정하면 테스트 실행 중 Cashier와 상호작용할 때마다 Stripe 테스트 환경으로 실제 API 요청이 전송됩니다.

테스트를 원활하게 진행하려면, Stripe 테스트 계정에 테스트용 구독 플랜과 가격(price)을 미리 생성해 두는 것이 좋습니다. 테스트 케이스에서 이 데이터를 바로 참조할 수 있어 편리합니다.

NOTE

신용카드 거절, 결제 실패 등 다양한 결제 시나리오를 테스트하려면 Stripe에서 제공하는 테스트용 카드 번호 및 토큰을 활용하세요. 실제 카드 정보를 입력하지 않아도 다양한 결제 상황을 재현할 수 있습니다.