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