Cartalyst LLC.
Stripe-billing-laravel by Cartalyst
0
26
0
6
3

This package requires a valid subscription. Subscribe for access.

Preface

Introduction

Stripe Billing functionality for Laravel 8.

The package requires PHP 7.3+ and follows the FIG standards PSR-1, PSR-2 and PSR-4 to ensure a high level of interoperability between shared PHP.

Have a read through the Installation Guide and on how to Integrate it with Laravel 8.

Examples

// Get the Billable Entity object
$user = User::find(1);

// Loop through all the Entity Subscriptions
foreach ($user->subscriptions as $subscription) {
    // Check if the Subscription is expired
    if ($subscription->isExpired()) {
        echo 'Subscription is expired!';
    }
}
// Get the Billable Entity object
$user = User::find(1);

// Find a Payment Method
$paymentMethod = $user->cards->find(10);

// Check if the Payment Method is expired
if ($paymentMethod->isExpired() {
    echo 'The Payment Method is expired.';
}

Installation

Note: Please read the Cartalyst Stripe Laravel integration documentation before continuing!!

Cartalyst packages utilize Composer, for more information on how to install Composer please read the Composer Documentation.

First, register the private Packages repository from Cartalyst by running:

composer config repositories.cartalyst composer https://packages.cartalyst.com

Now require the Cartalyst Stripe Billing Laravel package by running:

composer require cartalyst/stripe-billing-laravel:^13.0

Database Migrations

The Cartalyst Stripe Billing Laravel service provider registers its own migrations directory, though we need to know which table(s) to use for your Billable Entity(ies).

Therefore, the package comes with a very simple Artisan command that can generate a migration, or several, dependending on how many Billable Entities you want to use.

To generate these migrations please run php artisan stripe:schema and follow the instructions.

Now that the migration files have been generated, all that's left to do is to migrate your database by running:

php artisan migrate

These migrations will create several tables, but if you need to overwrite the migrations that ship with the Cartalyst Stripe Billing Laravel package, you can do so by publishing them using the Laravel vendor:publish Artisan command:

php artisan vendor:publish --tag="cartalyst:stripe.billing.migrations"

The migrations will be published to your database/migrations directory and can now be freely modified.

Configuration

Billable Entity Model

Before the Cartalyst Stripe Billing Laravel can be used, a little setup on the your Billable Entity(ies) needs to happen.

The Billable Entity needs to implement the Cartalyst\Stripe\Billing\Laravel\BillableContract contract and the Cartalyst\Stripe\Billing\Laravel\Billable trait needs to be added as well.

Here's an example using the default User model that ships with Laravel:

<?php

namespace App;

use Cartalyst\Stripe\Billing\Laravel\Billable;
use Cartalyst\Stripe\Billing\Laravel\BillableContract;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable implements BillableContract
{
    use Notifiable;
    use Billable;
}

Currency Configuration

The currency can be defined on a Billable Entity Model basis instead of globally, this is to ensure maximum flexibility without a lot of code duplication.

By default the currency is USD and to change it all you need to do is to override the preferedCurrency() inside the desired Billable Entity Model:

<?php

namespace App;

use Cartalyst\Stripe\Billing\Laravel\Billable;
use Cartalyst\Stripe\Billing\Laravel\BillableContract;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable implements BillableContract
{
    use Notifiable;
    use Billable;

    /**
     * Returns the Billable Entity prefered currency
     * that will be used on Charges and Invoices.
     *
     * @return string
     */
    public function preferedCurrency(): string
    {
        // Define the value as being static or check the
        // next example for a more dynamic behaviour.
        return 'eur';

        // Alternatively, this value can be read from the database if you so desire.
        // So something like the following would read the value
        // from the column "currency" from the "users" table.
        return $this->currency;
    }
}

Customers

Now that the package is installed and the Billable Entities are configured, it is now time to create or attach an existing Stripe Customer to a Billable Entity.

Note: This is a required step and can't be skipped as every Billable Entity requires a Stripe Customer to be attached, otherwise a Cartalyst\Stripe\Billing\Laravel\Exception\InvalidStripeCustomer exception will be thrown.

Attach a Customer

This method is useful when you already have an existing Stripe Customer and you want to attach it to a Billable Entity:

Arguments
Key Required Type Default Description
$stripeId true string null The Stripe Customer ID.
Usage
// Get the non Billable Entity object
$user = User::find(1);

// Attach the Stripe Customer to the non Billable Entity
$user->attachStripeCustomer('cus_5Nq3Ee9rD5wLde');

Now the selected Entity has a valid Stripe Customer attached and is therefore Billable.

Create a new Customer

Creating a new Stripe Customer and attaching it to a Billable Entity couldn't be any easier.

Just call the createStripeCustomer() method on the Billable Entity object and pass an array with any allowed Stripe parameter:

Arguments
Key Required Type Default Description
$parameters false array [] The parameters that can be used when creating the Stripe Customer. For a list of available parameters, please check the official Stripe API documentation.
Usage
// Get the non Billable Entity object
$user = User::find(1);

// Create the Stripe Customer on the non Billable Entity
$user->createStripeCustomer([
    'email' => $user->email,
]);

Now the selected Entity has a valid Stripe Customer attached and is therefore Billable.

Update a Customer

There's also the possibility to easily update a Stripe Customer.

To perform an update, just call the updateStripeCustomer() method on the Billable Entity object and pass an array with the parameters you wish to update:

Arguments
Key Required Type Default Description
$parameters false array [] The parameters that can be used when updating the Stripe Customer. For a list of available parameters, please check the official Stripe API documentation.
Usage
// Get the Billable Entity object
$user = User::find(1);

// Update the Stripe Customer
$user->updateStripeCustomer([
    'description' => 'This is a VIP customer!',
]);

Delete a Customer

There are situations where you might want to delete a Stripe Customer.

That can be performed by using the deleteStripeCustomer() method:

// Get the Billable Entity object
$user = User::find(1);

// Delete the Stripe Customer
$user->deleteStripeCustomer();

Note: Do keep in mind that this method is destructive and irreversible, as it will delete the account and the related data from Stripe, but the data locally will still be retained!

General methods

In this section we'll cover some actions you can perform against your Billable Entity object.

Note We're covering most of these in this section as they don't fit on the other sections.

Determine if the Entity is Billable

This method is very useful when you need to determine if the Entity is ready to be billed, or in other words, if the Entity has a Stripe Customer attached.

Usage
// Get the Billable Entity object
$user = User::find(1);

// Determine if the Entity is Billable
if (! $user->isBillable()) {
    echo 'The Entity is not ready to be billed!';
}

Determine if the Entity has a discount applied

Determine if the Entity has a Stripe discount coupon applied

Usage
// Get the Billable Entity object
$user = User::find(1);

// Determine if the Entity has a stripe discount applied
if (! $user->hasStripeDiscount()) {
    echo 'The Entity does not have a Stripe discount applied.';
}

Apply a discount

Applies a coupon on the Entity, this will execute a Stripe API call to apply the coupon on the Stripe Customer that is attached to this Entity.

Arguments
Key Required Type Default Description
$coupon true string null The coupon unique identifier.
Usage
// Get the submitted Stripe coupon
$coupon = request()->input('coupon');

// Get the Billable Entity object
$user = User::find(1);

// Apply the coupon on the Entity
$user->applyStripeDiscount($coupon);

Remove the discount

Removes the coupon from the Billable Entity.

Usage
// Get the Billable Entity object
$user = User::find(1);

// Remove the coupon from the Entity
$user->removeStripeDiscount();

Synchronize the Entity

There are situations where you want to synchronize a Billable Entity with Stripe, luckily we have made this task very easy to be performed.

All that needs to be done is to call the syncWithStripe(); method on the Billable Entity:

Usage
// Get the Billable Entity object
$user = User::find(1);

// Synchronize the Billable Entity with Stripe
$user->syncWithStripe();

This will syncronize the Payment Methods, Charges and Refunds, Invoices and their Invoice Items, the pending Invoice Items, Subscriptions and their Items that belongs to your Entity.

Note: Considering that this is not an async call, we highly recommend this to be run through a Queued Job or some sort of CLI command, to avoid timeouts, interruptions and blocking other operations to be performed.

Payment Methods

Either when you're going to accept "one off" charges or deal with subscriptions, the Billable Entity requires at least one valid Payment Method.

With the Cartalyst Stripe Billing Laravel you can attach as many Payment Methods as you want to a Billable Entity.

Attach a Payment Method

If you want to attach a Payment Method to the Entity you'll need to call the attach() method on the Payment Methods Eloquent query builder and pass the Payment Method Id to it.

// Receive the submitted Stripe Payment Method ID that was generated using Stripe.js
$paymentMethodId = request()->input('payment_method_id');

// Get the Billable Entity object
$user = User::find(1);

// Create the card and make it default
$user->paymentMethods()->attach($paymentMethodId);

Note: The payment_method_id field name used above is just for the example, you can name it differently.

Detach a Payment Method

Payment Methods can be detached from a Stripe Customer.

To do so, you just need to find the Payment Method you want to detach and call the detach() method on the object.

Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method to be detached
$paymentMethod = $user->paymentMethods->find(10);

// Detach the Payment Method
$paymentMethod->detach();

Create a Payment Method

While not recommend, it's totally possible to create Payment Methods using card numbers instead of using Stripe.js.

However, please ensure you meet the requirements for PCI compliance as indicated here if you want to go with this route.

Arguments

The following are the arguments that the create() method of the Payment Methods accepts.

Key Required Type Default Description
$parameters true array [] The Payment Method parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples

Create a new Payment Method of the Card type with a Card number:

// Get the Billable Entity object
$user = User::find(1);

// Create the Payment Method
$paymentMethod = $user->paymentMethods()->create([
    'type' => 'card',
    'card' => [
        'number'    => '4242424242424242',
        'exp_month' => 10,
        'cvc'       => 314,
        'exp_year'  => 2025,
    ],
]);

Retrieve a Payment Method

To retrieve an existing Payment Method that is attached to an Entity all you're required to do is to call the find() method and pass the Payment Method id on the paymentMethods collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods->find(10);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods()->where('stripe_id', 'pm_1EUpGU4Lf1hyuG3tyUasGREf')->first();
Determine if the Entity has active Payment Methods
// Get the Billable Entity object
$user = User::find(1);

// Determine if the Entity has active Payment Methods
if (! $user->hasActivePaymentMethods()) {
    echo 'The Entity does not have any active Payment Methods!';
}
Get the Entity default Payment Method
// Get the Billable Entity object
$user = User::find(1);

// Get the Entity default Payment Method object
$paymentMethod = $user->getDefaultPaymentMethod();

echo $paymentMethod->data['last4'];

Statuses

Is Expirable

Some Payment Methods might not be expirable and in order to determine that, the method isExpirable() can be called on a Payment Method object.

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods->find(10);

// Determine if the Payment Method is expirable
if (! $paymentMethod->isExpirable()) {
    echo 'The Payment Method is not expirable.';
}
Has Expired

To determine if the Payment Method has expired, you may use the hasExpired() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods->find(10);

if ($paymentMethod->hasExpired() {
    echo 'The Payment Method has expired.';
}
Is Expiring

In this example we'll be checking if the Payment Method is expiring in the upcoming month.

// Create a new Carbon object date
$date = Carbon\Carbon::now()->addMonth();

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods->find(10);

// Check if the Payment Method is expiring
if ($paymentMethod->isExpiringOn($date)) {
    echo 'The Payment Method is going to expire next month!';
}
Is Default

To determine if the Payment Method is the default Payment Method, you may use the isDefault() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method
$paymentMethod = $user->paymentMethods->find(10);

if ($paymentMethod->isDefault()) {
    echo 'This is the default Payment Method.';
}

Update a Payment Method

Updating a Payment Method is straightforward.

Arguments

The following are the arguments that the update() method accepts

Key Required Type Default Description
$parameters false array [] The Payment Method parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Method to be updated
$paymentMethod = $user->paymentMethods->find(10);

// Update the Payment Method
$paymentMethod->update([
    'billing_details' => [
        'name' => 'John Doe',
    ],
]);
Setting an existing Payment Method as the default Payment Method
$user = User::find(1);

$user->paymentMethods->find(10)->setAsDefault();

Retrieve all Payment Methods

To retrieve all Payment Methods that are attached to an Entity all you need to do is to call the paymentMethods collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Methods
$paymentMethods = $user->paymentMethods;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Payment Methods with a custom query
$paymentMethods = $user->paymentMethods()->where(function ($query) {
    return $query
        ->where('type', 'card')
        ->where('data.exp_year', '>=', '2020')
    ;
})->get();

Synchronization

Often you might have the need to synchronize the data from Stripe with your database, we have an easy way to achieve this.

This method synchronizes all the Payment Methods of Entity from Stripe into the local storage.

// Get the Billable Entity object
$user = User::find(1);

// Synchronize this Entity Payment Methods
$user->paymentMethods()->syncWithStripe();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the Payment Methods API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

PaymentMethodAttached

This event is dispatched when a Payment Method is attached to a Billable Entity.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\PaymentMethod\Events\PaymentMethodAttached

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethodContract $paymentMethod The instance of the local Payment Method.
array $stripeResponse The response that Stripe returned when performing the action.

PaymentMethodDetached

This event is dispatched when a Payment Method is detached from a Billable Entity.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\PaymentMethod\Events\PaymentMethodDetached

Arguments

Below you can find a list of all the arguments in the exact order that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethodContract $paymentMethod The instance of the local Payment Method.
array $stripeResponse The response that Stripe returned when performing the action.

PaymentMethodUpdated

This event is dispatched when a Payment Method from a Billable Entity is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\PaymentMethod\Events\PaymentMethodUpdated

Arguments

Below you can find a list of all the arguments in the exact order that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethodContract $paymentMethod The instance of the local Payment Method.
array $stripeResponse The response that Stripe returned when performing the action.

Charges

To charge a credit or a debit card, you create a Charge object.

You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique, random ID.

Creating a Charge

To charge a credit card, you create a charge object. If your API key is in test mode, the supplied card won't actually be charged, though everything else will occur as if in live mode. (Stripe assumes that the charge would have completed successfully).

Arguments

The following are the arguments that the create() method of the Card Gateway accepts.

Key Required Type Default Description
$parameters true array [] The Charge parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples

Let's create a charge for $50.55. The amount is always required to be passed, where the currency will be automatically applied.

The amount needs to be sent in cents as that's what Stripe only accepts.

// Get the Billable Entity object
$user = User::find(1);

// Create the Charge
$charge = $user->charges()->create([
    'amount'      => 5055,
    'currency'    => 'usd',
    'description' => 'A single Charge',
]);

Retrieve a Charge

To retrieve an existing payment that is attached to an Entity all you're required to do is to call the find() method and pass the payment id on the charges collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges()->where('stripe_id', 'ch_15jaLgJvzVWl1WTeiY8u661R')->first();

Statuses

To determine if a Charge is fully captured, you may use the isFullyCaptured() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

if ($payment->isFullyCaptured() {
    echo 'The Charge is fully captured.';
}

To determine if the Charge is fully refunded, you may use the isFullyRefunded() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

if ($payment->isFullyRefunded() {
    echo 'The Charge is fully refunded.';
}

To determine if the Charge is partially captured, you may use the isPartiallyCaptured() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

if ($payment->isPartiallyCaptured() {
    echo 'The Charge is partially captured.';
}

To determine if the Charge is partially refunded, you may use the isPartiallyRefunded() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

if ($payment->isPartiallyRefunded() {
    echo 'The Charge is partially refunded.';
}

To determine if the Charge is paid, you may use the isPaid() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

if ($payment->isPaid() {
    echo 'The Charge is not paid.';
}

Update a Charge

Updating a Charge is very easy.

Arguments

The following are the arguments that the update() method accepts

Key Required Type Default Description
$parameters false array [] The Charge parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge to be updated
$payment = $user->charges->find(10);

// Update the Charge
$payment->update([
    'description' => 'Charge for the Book',
]);

Fully capture a Charge

Fully capture an uncaptured Charge on the entirity of its amount

Arguments

The following are the arguments that the capture() method accepts

Key Required Type Default Description
$parameters false array [] The Charge parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Fully capture the Charge
$charge->capture();

Partially capture a Charge

Fully capture an uncaptured Charge on the given amount

Arguments

The following are the arguments that the partiallyCapture() method accepts

Key Required Type Default Description
$amount true number null The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.
$parameters false array [] The Charge parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Partially capture the Charge
$charge->partiallyCapture(2349);

Retrieve all Charges

To retrieve all charges that are attached to an Entity all you're required to do is to call the charges collection, yeah, that simple.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charges
$charges = $user->charges;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Charges
$charges = $user->charges()->orderBy('created_at', 'desc')->get();

Synchronization

Often you might have the need to synchronize the data from Stripe with your database, we have an easy way to achieve this.

This method synchronizes all the Charges of Entity from Stripe into the local storage.

// Get the Billable Entity object
$user = User::find(1);

// Synchronize this Entity Charges
$user->charges()->syncWithStripe();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the Charges API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

ChargeCreated

This event is dispatched when a Charge is created.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargeCreated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

ChargeFullyCaptured

This event is dispatched when a Charge is fully captured.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargeFullyCaptured

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

ChargeFullyRefunded

This event is dispatched when a Charge is fully refunded.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargeFullyRefunded

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

ChargePartiallyCaptured

This event is dispatched when a Charge is partially captured.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargePartiallyCaptured

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

ChargePartiallyRefunded

This event is dispatched when a Charge is partially refunded.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargePartiallyRefunded

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

ChargeUpdated

This event is dispatched when a Charge is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Events\ChargeUpdated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\ChargeContract $charge The instance of the local Charge.
array $stripeResponse The response that Stripe returned when performing the action.

Refunds

Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

Create a Refund

Creating a new Refund will Refund a Charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

Arguments

The following are the arguments that the update() method accepts

Key Required Type Default Description
$parameters false array [] The Refund parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples

Do a full refund

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

// Refund the Charge
$payment->refund();

Do a partial refund

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$payment = $user->charges->find(10);

// Refund the Charge
$payment->refund(5000);

Retrieve a Refund

To retrieve an existing Charge Refund call the find() method and pass the refund id on the refunds collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Find the Refund
$refund = $charge->refunds->find(2020);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Find the Refund
$refund = $user->refunds()->where('stripe_id', 're_15iBdsJvzVWl1WTevOaPONHV')->first();

Update a refund

Updating a Refund is very easy.

Arguments

The following are the arguments that the update() method accepts

Key Required Type Default Description
$parameters false array [] The refund parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Find the Refund to be updated
$refund = $charge->refunds->find(2020);

// Update the Refund
$refund->update([
    'metadata' => [
        'foo' => 'Bar',
    ],
]);

Retrieve all Refunds

To retrieve all Refunds that are attached to a Charge all you're required to do is to call the refunds collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Find the Refunds
$refunds = $charge->refunds;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Charge
$charge = $user->charges->find(10);

// Find the Refunds
$refunds = $charge->refunds()->orderBy('created_at', 'desc')->get();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the Charge Refunds API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

RefundCreated

This event is dispatched when a Charge Refund is created.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Refund\Events\RefundCreated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\Refund\RefundContract $chargeRefund The instance of the local Charge Refund.
array $stripeResponse The response that Stripe returned when performing the action.

RefundUpdated

This event is dispatched when a ChargeRefund is updated

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Charge\Refund\Events\Refundpdated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Charge\Refund\RefundContract $chargeRefund The instance of the local Charge Refund.
array $stripeResponse The response that Stripe returned when performing the action.

Subscriptions

Subscriptions allow you to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan you've created.

Create a Subscription

Subscribing an Entity to a single plan:

// Get the Billable Entity object
$user = User::find(1);

// Create the Subscription
$user->subscriptions()->create([
    'items' => [
        [
            'plan'     => 'monthly',
            'quantity' => 1,
        ],
    ],
]);

Subscribing an Entity to multiple plans:

// Get the Billable Entity object
$user = User::find(1);

// Create the Subscription
$user->subscriptions()->create([
    'items' => [
        [
            'plan'     => 'monthly',
            'quantity' => 1,
        ],
        [
            'plan'     => '50mb-storage-addon',
            'quantity' => 1,
        ],
    ],
]);

Subscribing an Entity to a plan and apply a coupon to this new subscription:

// Get the submitted coupon
$coupon = request()->input('coupon');

// Get the Billable Entity object
$user = User::find(1);

// Create the Subscription
$user->subscriptions()->create([
    'discount' => $coupon,
    'items' => [
        [
            'plan'     => 'monthly',
            'quantity' => 1,
        ],
    ],
]);

Create a trial subscription:

// Get the Billable Entity object
$user = User::find(1);

// Create the Subscription
$user->subscriptions()->create([
    'trial_end' => Carbon::now()->addDays(14),
    'items' => [
        [
            'plan'     => 'monthly',
            'quantity' => 1,
        ],
    ],
]);

Retrieve a Subscription

To retrieve an existing subscription that is attached to an Entity all you're required to do is to call the find() method and pass the subscription id on the subscriptions collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions()->where('stripe_id', 'sub_5vp6DX7N6yVJqY')->first();

Check if the Entity has active Subscriptions

You can check if an Entity has active subscriptions by calling the isSubscribed() method on the Entity object:

Usage
// Get the Billable Entity object
$user = User::find(1);

// Check if the Entity has any active Subscription
if ($user->isSubscribed()) {
    echo 'Entity has at least one active Subscription!';
}

Statuses

To determine if the subscription is on the trial period, you may use the onTrialPeriod() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the subscription
$subscription = $user->subscriptions->find(10);

if ($subscription->isOnTrialPeriod()) {
    echo "Subscription is on trial period from {$subscription->trial_starts_at} to {$subscription->trial_ends_at}!";
}

To determine if the subscription is marked as canceled, you may use the isCanceled() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the subscription
$subscription = $user->subscriptions->find(10);

if ($subscription->isCanceled()) {
    echo "Subscription was canceled on {$subscription->canceled_at}!";
}

To determine if the subscription has expired, you may use the isExpired() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the subscription
$subscription = $user->subscriptions->find(10);

if ($subscription->isExpired()) {
    echo "Subscription has expired on {$subscription->ended_at}!";
}

To determine if a subscription is still on their "grace period" until the subscription fully expires. For example, if a user cancels a subscription on March 5th that was scheduled to end on March 10th, the user is on their "grace period" until March 10th.

// Get the Billable Entity object
$user = User::find(1);

// Find the subscription
$subscription = $user->subscriptions->find(10);

if ($subscription->isOnGracePeriod()) {
    echo "Subscription is on it's grace period until {$subscription->period_ends_at}.";
}

Update a Subscription

Swap a plan from a Subscription item

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Get the item to have the plan swapped
$item = $subscription->items->first();

// Swap the Subscription plan
$item->swap('new-plan-name');

Swap a plan from a Subscription item and Invoice the customer

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Get the item to have the plan swapped
$item = $subscription->items->first();

// Swap the Subscription plan
$item->swapAndInvoice('new-plan-name');

Apply a trial period on a subscription

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Create a new Carbon instance
$trialPeriod = Carbon::now()->addDays(14);

// Set the trial on the Subscription
$subscription->applyTrialPeriod($trialPeriod);

Removing the trial period from a Subscription

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Remove the trial from the Subscription
$subscription->removeTrialPeriod();

Apply a coupon to an existing Subscription

// Get the submitted coupon
$coupon = request()->input('coupon');

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Apply the coupon
$subscription->applyCoupon($coupon);

Remove a coupon from an existing Subscription

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Remove the coupon
$subscription->removeCoupon();

Cancel a Subscription

Cancel an active Subscription immediately.

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Cancel the Subscription
$subscription->cancelNow();

Cancel a subscription at the end of the billing period

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Cancel the Subscription
$subscription->cancelAtPeriodEnd();

Resume a subscription

Resume a canceled subscription

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscription
$subscription = $user->subscriptions->find(10);

// Resume the Subscription
$subscription->resume();

Retrieve all subscriptions

To retrieve all subscriptions that are attached to an Entity all you're required to do is to call the subscriptions collection, yeah, that simple.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Subscriptions
$subscriptions = $user->subscriptions;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Subscriptions
$subscriptions = $user->subscriptions()->orderBy('created_at', 'desc')->get();
Find all Subscriptions that are active
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->active()->get();
Find all Subscriptions that are not active
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notActive()->get();
Find all canceled Subscriptions that are canceled
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->canceled()->get();
Find all non canceled Subscriptions that are not canceled
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notCanceled()->get();
Find all Subscriptions that are expired
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->expired()->get();
Find all Subscriptions that are not expired
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notExpired()->get();
Find all Subscriptions that are incomplete
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->incomplete()->get();
Find all Subscriptions are not incomplete
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notIncomplete()->get();
Find all Subscriptions that are on grace period
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->onGracePeriod()->get();
Find all Subscriptions that are not on grace period
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notOnGracePeriod()->get();
Find all Subscriptions that are on trial period
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->onTrialPeriod()->get();
Find all Subscriptions that are not on trial period
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notOnTrialPeriod()->get();
Find all Subscriptions that are past due
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->pastDue()->get();
Find all Subscriptions that are not past due
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notPastDue()->get();
Find all Subscriptions that are unpaid
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->unpaid()->get();
Find all Subscriptions that are not unpaid
// Get the Billable Entity object
$user = User::find(1);

// Find the subscriptions
$subscriptions = $user->subscriptions()->notUnpaid()->get();

Synchronization

Often you might have the need to synchronize the data from Stripe with your database, we have an easy way to achieve this.

This method synchronizes all the Subscriptions of Entity from Stripe into the local storage.

// Get the Billable Entity object
$user = User::find(1);

// Synchronize this Entity Subscriptions
$user->subscriptions()->syncWithStripe();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the Subscriptions API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

SubscriptionCreated

This event is dispatched when a Subscription is created.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Events\SubscriptionCreated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionUpdated

This event is dispatched when a Subscription is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Events\SubscriptionUpdated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionCanceled

This event is dispatched when a Subscription is canceled.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Events\SubscriptionCanceled

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionResumed

This event is dispatched when a canceled Subscription is resumed.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Events\SubscriptionResumed

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionItemCreated

This event is dispatched when a canceled Subscription Item is created.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Item\Events\SubscriptionItemCreated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItemContract $subscriptionItem The instance of the local Subscription Item.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionItemUpdated

This event is dispatched when a canceled Subscription Item is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Item\Events\SubscriptionItemUpdated

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItemContract $subscriptionItem The instance of the local Subscription Item.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionItemDeleted

This event is dispatched when a canceled Subscription Item is deleted.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Item\Events\SubscriptionItemDeleted

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItemContract $subscriptionItem The instance of the local Subscription Item.
array $stripeResponse The response that Stripe returned when performing the action.

SubscriptionItemSwapped

This event is dispatched when a canceled Subscription Item has its plan swapped for another one.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Subscription\Item\Events\SubscriptionItemSwapped

Arguments

Below you can find a list of all the properties that are publically accessible from the event class.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionContract $subscription The instance of the local Subscription.
Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItemContract $subscriptionItem The instance of the local Subscription Item.
array $stripeResponse The response that Stripe returned when performing the action.

Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.

They contain invoice items, and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary).

Create an Invoice

If you need to invoice your customer outside the regular billing cycle, you can create an invoice that pulls in all pending invoice items, including prorations. The customer's billing cycle and regular subscription won't be affected.

Once you create the invoice, it'll be picked up and paid automatically, though you can choose to pay it right away.

Arguments

The following are the arguments that the create() method of the Invoice Gateway accepts.

Key Required Type Default Description
$parameters false array [] The Invoice parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Create the Invoice
$invoice = $user->invoices()->create([
    'collection_method' => 'send_invoice',
    'description'       => 'Tailored service',
]);

Create a new Invoice and set its Items:

// Get the Billable Entity object
$user = User::find(1);

// Create the Invoice
$invoice = $user->invoices()->create([
    'items' => [
        [
            'amount'      => 1000,
            'currency'    => 'usd',
            'description' => 'Invoice Item 1',
        ],
        [
            'amount'      => 3540,
            'currency'    => 'usd',
            'description' => 'Invoice Item 2',
        ],
    ],
]);

Retrieve a invoice

To retrieve an existing invoice that is attached to an Entity all you're required to do is to call the find() method and pass the invoice id on the invoices collection.

Usage
// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices()->where('stripe_id', 'in_15kPp3JvzVWl1WTe4KBHXGqK')->first();

Statuses

Is Draft

To determine if the invoice is closed, you may use the isDraft() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if (! $invoice->isDraft() {
    echo 'The invoice is not a draft.';
}

Is Opened

To determine if the invoice is closed, you may use the isOpened() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if (! $invoice->isOpened() {
    echo 'The invoice is not opened.';
}

Is Paid

To determine if the invoice is paid, you may use the isPaid() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if (! $invoice->isPaid() {
    echo 'The invoice is not paid.';
}

Is Uncollectible

To determine if the invoice is closed, you may use the isUncollectible() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if ($invoice->isUncollectible() {
    echo 'The invoice is uncollectible.';
}

Is Void

To determine if the invoice is closed, you may use the isVoid() method:

// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if (! $invoice->isVoid() {
    echo 'The invoice is not voided.';
}

Update an invoice

Until an invoice is paid, it is marked as open (closed=false). If you'd like to stop Stripe from automatically attempting payment on an invoice or would simply like to close the invoice out as no longer owed by the customer, you can update the closed parameter.

Arguments

The following are the arguments that the update() method of the Invoice Gateway accepts.

Key Required Type Default Description
$parameters false array [] The invoice item parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

// Update the invoice
$invoice->update([
    'description' => 'A nice description for this Invoice.',
]);

Pay an invoice

Stripe automatically creates and then attempts to pay invoices for customers on subscriptions.

However, if you'd like to attempt to collect payment on an invoice out of the normal retry schedule or for some other reason, you can do so.

Arguments

The following are the arguments that the pay() method of the Invoice Gateway accepts.

Key Required Type Default Description
$parameters false array [] The invoice item parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the invoice
$invoice = $user->invoices->find(10);

if (! $invoice->isPaid()) {
    // Pay the invoice
    $invoice->pay();
}

Retrieve all invoices

To retrieve all invoices that are attached to an Entity all you're required to do is to call the invoices collection, yeah, that simple.

Usage
// Get the Billable Entity object
$user = User::find(1);

// Find the invoices
$invoices = $user->invoices;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the invoices
$invoices = $user->invoices()->orderBy('created_at', 'desc')->get();

Synchronization

Often you might have the need to synchronize the data from Stripe with your database, we have an easy way to achieve this.

This method synchronizes all the Invoices of Entity from Stripe into the local storage.

// Get the Billable Entity object
$user = User::find(1);

// Synchronize this Entity Invoices
$user->invoices()->syncWithStripe();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the Invoices API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

InvoiceCreated

This event is dispatched when an Invoice is created on a Billable Entity.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Invoice\Events\InvoiceCreated

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Invoice\InvoiceContract $invoice The instance of the local Invoice.
array $stripeResponse The response that Stripe returned when performing the action.

InvoiceUpdated

This event is dispatched when a Invoice from a Billable Entity is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Invoice\Events\InvoiceUpdated

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Invoice\InvoiceContract $invoice The instance of the local Invoice.
array $stripeResponse The response that Stripe returned when performing the action.

InvoicePaid

This event is dispatched when a Invoice from a Billable Entity is paid.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\Invoice\Events\InvoicePaid

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
Cartalyst\Stripe\Billing\Laravel\Invoice\InvoiceContract $invoice The instance of the local Invoice.
array $stripeResponse The response that Stripe returned when performing the action.

Invoice Items

Sometimes you want to add a charge or credit to a customer but only actually charge the customer's card at the end of a regular billing cycle. This is useful for combining several charges to minimize per-transaction fees or having Stripe tabulate your usage-based billing totals.

Create an Invoice Item

Adds an arbitrary charge or credit to the customer's upcoming invoice.

Arguments

The following are the arguments that the create() method of the Invoice Item Gateway accepts.

Key Required Type Default Description
$parameters false array [] The Invoice Item parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Create the Invoice Item
$invoiceItem = $user->invoiceItems()->create([
    'amount'   => 1250,
    'currency' => 'usd',
]);

Retrieve an Invoice Item

To retrieve an existing Invoice Item that is attached to an Entity all you're required to do is to call the find() method and pass the charge id on the invoiceItems collection.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Item
$invoiceItem = $user->invoiceItems->find(10);

If a more robust search is required, you can use the normal Laravel Eloquent methods like where() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Item
$invoiceItem = $user->invoiceItems()->where('stripe_id', 'ch_15jaLgJvzVWl1WTeiY8u661R')->first();

Update an Invoice Item

Updating an Invoice Item is very easy.

Arguments

The following are the arguments that the update() method accepts

Key Required Type Default Description
$parameters false array [] The Invoice Item parameters. For a list of available parameters, please check the official Stripe API documentation.
Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Item to be updated
$invoiceItem = $user->invoiceItems->find(10);

// Update the Invoice Item
$invoiceItem->update([
    'amount' => 5099,
]);

Delete an Invoice Item

Deleting an Invoice Item couldn't be more simple, just find the Invoice Item you want to delete, and call the delete() method on the Invoice Item object.

Usage example
// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Item to be deleted
$invoiceItem = $user->invoiceItems->find(10);

// Delete the Invoice Item
$invoiceItem->delete();

Retrieve all Invoice Items

To retrieve all Invoice Items that are attached to an Entity all you're required to do is to call the invoiceItems collection, yeah, that simple.

Usage examples
// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Items
$invoiceItems = $user->invoiceItems;

If a more robust search is required, you can use the normal Laravel Eloquent methods like where(), orderBy() etc..

// Get the Billable Entity object
$user = User::find(1);

// Find the Invoice Items
$invoiceItems = $user->invoiceItems()->orderBy('created_at', 'desc')->get();

Synchronization

Often you might have the need to synchronize the data from Stripe with your database, we have an easy way to achieve this.

This method synchronizes all the Invoice Items of Entity from Stripe into the local storage.

// Get the Billable Entity object
$user = User::find(1);

// Synchronize this Entity Invoice Items
$user->invoiceItems()->syncWithStripe();

Events

On this section you can find all the events that are dispatched whenever an action occurs within the InvoiceItem Items API.

Note: For more information on how Laravel Events work and how to set Event Listeners, please refer to the Laravel Documentation.

InvoiceItemCreated

This event is dispatched when an Invoice Item is created on a Billable Entity.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\InvoiceItem\Events\InvoiceItemCreated

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
int $invoiceItemId The InvoiceItem ID from local storage.
string $stripeInvoiceItemId The InvoiceItem ID from Stripe.
array $stripeResponse The response that Stripe returned when performing the action.

InvoiceItemUpdated

This event is dispatched when a InvoiceItem from a Billable Entity is updated.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\InvoiceItem\Events\InvoiceItemUpdated

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
int $invoiceItemId The InvoiceItem ID from local storage.
string $stripeInvoiceItemId The InvoiceItem ID from Stripe.
array $stripeResponse The response that Stripe returned when performing the action.

InvoiceItemDeleted

This event is dispatched when a InvoiceItem from a Billable Entity is deleted.

FQCN

This is the Full Qualified Class Name (FQCN) of this event.

Cartalyst\Stripe\Billing\Laravel\InvoiceItem\Events\InvoiceItemDeleted

Arguments

Below you can find a list of all the arguments that this Event receives.

Type Name Description
Cartalyst\Stripe\Billing\Laravel\BillableContract $billable The instance of the Billable Entity.
int $invoiceItemId The InvoiceItem ID from local storage.
string $stripeInvoiceItemId The InvoiceItem ID from Stripe.
array $stripeResponse The response that Stripe returned when performing the action.

Overriding

If you need to override a billable model or even a gateway to introduce custom methods or a different behaviour, you can achieve that in an extremely easy way as we provide handy methods you can utilise with your Entity in case you require that extra functionality.

Models

To override a model, you'll need to first create the model you want to override and this model needs to extend the base model that it's overriding, here's an example on how to do it:

<?php

namespace App\Billing\Models;

use Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethod as Model;

class PaymentMethod extends Model
{
    // You can add new methods here or if required,
    // existing methods can be also overrided so
    // you can apply your own custom features.
}

Note: Please use the list below for a complete list of models namespace paths.

Models list

Model Name FQCN
Invoice Cartalyst\Stripe\Billing\Laravel\Invoice\Invoice
InvoiceItem Cartalyst\Stripe\Billing\Laravel\InvoiceItem\InvoiceItem
Payment Cartalyst\Stripe\Billing\Laravel\Payment\Payment
Refund Cartalyst\Stripe\Billing\Laravel\Payment\Refund\Refund
PaymentMethod Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethod
Subscription Cartalyst\Stripe\Billing\Laravel\Subscription\Subscription
SubscriptionItem Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItem

Set the Models

Now that you've the model(s) created, it's time to set them.

This can be done where you see it's more appropriate inside your application, as an example, you can do this within a Service Provider boot() method, this is mainly to ensure you only apply these changes once.

Note: We recommended that this should be done the earlier as you can in your application.

Model Method Example
Invoice setInvoiceModelFQCN User::setInvoiceModelFQCN('App\Billing\Models\Invoice');
InvoiceItem setInvoiceItemModelFQCN User::setInvoiceItemModelFQCN('App\Billing\Models\InvoiceItem');
Payment setPaymentModelFQCN User::setPaymentModelFQCN('App\Billing\Models\Payment');
Refund setRefundModelFQCN User::setRefundModelFQCN('App\Billing\Models\PaymentRefund');
PaymentMethod setPaymentMethodModelFQCN User::setPaymentMethodModelFQCN('App\Billing\Models\PaymentMethod');
Subscription setSubscriptionModelFQCN User::setSubscriptionModelFQCN('App\Billing\Models\Subscription');
SubscriptionItem setSubscriptionItemModelFQCN User::setSubscriptionItemModelFQCN('App\Billing\Models\SubscriptionItem');

Gateways

Overriding a gateway has a similar process as overriding a model, first you'll need to create the gateway you want to override and this gateway needs to extend the gateway you want to override, here's an example on how to do it:

<?php

namespace App\Billing\Gateways;

use Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethodGateway as Gateway;

class PaymentMethodGateway extends Gateway
{
    // You can create any new methods here or if
    // required, you can override any existing
    // method to apply your custom features.
}

Note: Please use the list below for a complete list of gateways namespace paths.

Gateways list

Gateway Name FQCN
Invoice Cartalyst\Stripe\Billing\Laravel\Invoice\InvoiceGateway
InvoiceItem Cartalyst\Stripe\Billing\Laravel\InvoiceItem\InvoiceItemGateway
Payment Cartalyst\Stripe\Billing\Laravel\Payment\PaymentGateway
Refund Cartalyst\Stripe\Billing\Laravel\Payment\Refund\RefundGateway
PaymentMethod Cartalyst\Stripe\Billing\Laravel\PaymentMethod\PaymentMethodGateway
Subscription Cartalyst\Stripe\Billing\Laravel\Subscription\SubscriptionGateway
SubscriptionItem Cartalyst\Stripe\Billing\Laravel\Subscription\Item\SubscriptionItemGateway

Set the Gateways

Now that you've the gateway(s) created, it's time to set them.

This can be done where you see it's more appropriate inside your application, as an example, you can do this through a Service Provider, this is mainly to ensure you only apply these changes once per request!

Note: We recommended that this should be done the earlier as you can on your application.

Gateway Method Example
Invoice setInvoiceGatewayFQCN User::setInvoiceGatewayFQCN('App\Billing\Gateways\InvoiceGateway');
InvoiceItem setInvoiceItemGatewayFQCN User::setInvoiceItemGatewayFQCN('App\Billing\Gateways\InvoiceItemGateway');
Payment setPaymentGatewayFQCN User::setPaymentGatewayFQCN('App\Billing\Gateways\PaymentGateway');
Refund setRefundGatewayFQCN User::setRefundGatewayFQCN('App\Billing\Gateways\PaymentRefundGateway');
PaymentMethod setPaymentMethodGatewayFQCN User::setPaymentMethodGatewayFQCN('App\Billing\Gateways\PaymentMethodGateway');
Subscription setSubscriptionGatewayFQCN User::setSubscriptionGatewayFQCN('App\Billing\Gateways\SubscriptionGateway');
SubscriptionItem setSubscriptionItemGatewayFQCN User::setSubscriptionItemGatewayFQCN('App\Billing\Gateways\SubscriptionItemGateway');

You wont find fancy lifestyle graphics and marketing bravado here. Just cold... hard... code...

Code Well, Rock On!
Processing Payment...