본문으로 건너뛰기
버전: master

Laravel Cashier (Stripe)

소개 (Introduction)​

Laravel Cashier Stripe는 Stripe의 구독 결제 서비스를 보다 직관적이고 유연하게 사용할 수 있도록 해주는 인터페이스를 제공합니다. 구독 결제 시스템을 직접 구현할 때 발생하는 반복적인 보일러플레이트 코드를 대부분 처리해 줍니다.

기본적인 구독 관리 기능뿐만 아니라 다음과 같은 기능도 제공합니다.

  • 쿠폰 처리
  • 구독 요금 변경
  • 구독 수량 관리
  • 취소 후 유예 기간(grace period)
  • 인보이스 PDF 생성

Cashier 업그레이드 (Upgrading Cashier)​

새로운 Cashier 버전으로 업그레이드할 때는 반드시 업그레이드 가이드를 확인해야 합니다.

[!WARNING] 변경 사항으로 인한 문제를 방지하기 위해 Cashier는 고정된 Stripe API 버전을 사용합니다. Cashier 16은 Stripe API 버전 2025-06-30.basil을 사용합니다. 새로운 Stripe 기능과 개선 사항을 활용하기 위해 마이너 릴리스에서 Stripe API 버전이 업데이트될 수 있습니다.

설치 (Installation)​

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

composer require laravel/cashier

패키지 설치 후 vendor:publish Artisan 명령어를 사용하여 Cashier의 마이그레이션을 퍼블리시합니다.

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

그 다음 데이터베이스 마이그레이션을 실행합니다.

php artisan migrate

Cashier의 마이그레이션은 다음 작업을 수행합니다.

  • users 테이블에 여러 컬럼 추가
  • 고객 구독 정보를 저장하는 subscriptions 테이블 생성
  • 여러 가격을 가진 구독을 위한 subscription_items 테이블 생성

원한다면 Cashier 설정 파일도 퍼블리시할 수 있습니다.

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

마지막으로 Stripe 이벤트를 정상적으로 처리하기 위해 반드시 Cashier Webhook 설정을 해야 합니다.

[!WARNING] Stripe는 Stripe 식별자를 저장하는 컬럼이 대소문자를 구분(case-sensitive) 하도록 설정할 것을 권장합니다. 따라서 MySQL을 사용하는 경우 stripe_id 컬럼의 collation을 utf8_bin으로 설정해야 합니다. 자세한 내용은 Stripe 문서를 참고하십시오.

설정 (Configuration)​

Billable 모델​

Cashier를 사용하기 전에 과금 대상 모델(billable model)에 Billable trait을 추가해야 합니다. 일반적으로 이 모델은 App\Models\User입니다.

이 trait은 다음과 같은 과금 관련 작업을 수행할 수 있는 다양한 메서드를 제공합니다.

  • 구독 생성
  • 쿠폰 적용
  • 결제 수단 정보 업데이트
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Cashier는 기본적으로 App\Models\User 모델을 billable 모델로 가정합니다. 다른 모델을 사용하려면 useCustomerModel 메서드를 사용해 변경할 수 있습니다.

이 메서드는 보통 AppServiceProvider의 boot 메서드에서 호출합니다.

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

[!WARNING] Laravel에서 기본 제공하는 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 환경 변수는 반드시 .env 파일에 설정해야 합니다. 이 값은 들어오는 webhook 요청이 실제 Stripe에서 보낸 것인지 확인하는 데 사용됩니다.

통화 설정​

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

CASHIER_CURRENCY=eur

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

CASHIER_CURRENCY_LOCALE=nl_BE

[!WARNING] en 이외의 로케일을 사용하려면 서버에 ext-intl PHP 확장이 설치되어 있어야 합니다.