Net::Stripe - API client for Stripe.com
version 0.42
my $stripe = Net::Stripe->new(api_key => $API_KEY); my $card_token = 'a token'; my $charge = $stripe->post_charge( # Net::Stripe::Charge amount => 12500, currency => 'usd', source => $card_token, description => 'YAPC Registration', ); print "Charge was not paid!\n" unless $charge->paid; my $card = $charge->card; # Net::Stripe::Card # look up a charge by id my $same_charge = $stripe->get_charge(charge_id => $charge->id); # ... and the API mirrors https://stripe.com/docs/api # Charges: post_charge() get_charge() refund_charge() get_charges() # Customer: post_customer()
This module is a wrapper around the Stripe.com HTTP API. Methods are generally named after the HTTP method and the object name.
This method returns Moose objects for responses from the API.
Because of occasional non-backward-compatible changes in the Stripe API, a given version of the SDK is only guaranteed to support Stripe API versions within the range defined by Net::Stripe::Constants::MIN_API_VERSION and Net::Stripe::Constants::MAX_API_VERSION.
Net::Stripe::Constants::MIN_API_VERSION
Net::Stripe::Constants::MAX_API_VERSION
If you need a version of the SDK supporting a specific older Stripe API version, you can check for available versions at https://github.com/lukec/stripe-perl/branches, or by cloning this repository, located at <https://github.com/lukec/stripe-perl> and using <git branch> to view available version-specific branches.
If you do not set the Stripe API version on object instantiation, API calls will default to the API version setting for your Stripe account.
If you set the Stripe API version on object instantiation you are telling Stripe to use that version of the API instead of the default for your account, and therefore the available API request and response parameters, the names of those parameters and the structure of the format of the returned data will all be dictated by the version that you specify. You can read more about the details of specific API versions at <https://stripe.com/docs/upgrades#api-changelog>.
If you are wearing a cowboy hat and think - although your specified account version is outside the range defined in Net::Stripe::Constants - that your use case is simple enough that it should "just work", you can create your object instance with force_api_version => 1, but don't say we didn't warn you!
Net::Stripe::Constants
force_api_version => 1
This creates a new stripe API object. The following parameters are accepted:
This is required. You get this from your Stripe Account settings.
This is the value of the Stripe-Version header <https://stripe.com/docs/api/versioning> you wish to transmit for API calls.
Set this to true to bypass the safety checks for API version compatibility with a given version of the SDK. Please see the warnings above, and remember that you are handling the financial data of your users. Use with extreme caution!
You can set this to true to see extra debug info.
You can set this to true to see the actual network requests.
Reader: api_base
Type: Str
Additional documentation: This is the base part of the URL for every request made
Reader: api_key
This attribute is required.
Additional documentation: You get this from your Stripe Account settings
Reader: api_version
Type: StripeAPIVersion
Additional documentation: This is the value of the Stripe-Version header you wish to transmit for API calls
Reader: debug
Writer: debug
Type: Bool
Additional documentation: The debug flag
Reader: debug_network
Writer: debug_network
Additional documentation: The debug network request flag
Reader: force_api_version
Additional documentation: Set this to true to bypass the safety checks for API version compatibility.
Reader: ua
Type: Object
Additional documentation: The LWP::UserAgent that is used for requests
Retrieve a balance transaction.
https://stripe.com/docs/api#retrieve_balance_transaction
id - Str - balance transaction ID to retrieve.
Returns a Net::Stripe::BalanceTransaction.
$stripe->get_balance_transaction(id => 'id');
Create a new charge.
https://stripe.com/docs/api/charges/create#create_charge
amount - Int - amount to charge
currency - Str - currency for charge
customer - StripeCustomerId - customer to charge - optional
card - StripeTokenId or StripeCardId - card to use - optional
source - StripeTokenId or StripeCardId - source to use - optional
description - Str - description for the charge - optional
metadata - HashRef - metadata for the charge - optional
capture - Bool - optional
statement_descriptor - Str - descriptor for statement - optional
application_fee - Int - optional
receipt_email - Str - The email address to send this charge's receipt to - optional
Returns Net::Stripe::Charge.
$stripe->post_charge(currency => 'USD', amount => 500, customer => 'testcustomer');
Retrieve a charge.
https://stripe.com/docs/api#retrieve_charge
charge_id - Str - charge id to retrieve
$stripe->get_charge(charge_id => 'chargeid');
Refunds a charge.
https://stripe.com/docs/api#create_refund
charge - Net::Stripe::Charge or Str - charge or charge_id to refund
amount - Int - amount to refund in cents, optional
Returns a new Net::Stripe::Refund.
$stripe->refund_charge(charge => $charge, amount => 500);
Returns a Net::Stripe::List object containing Net::Stripe::Charge objects.
https://stripe.com/docs/api#list_charges
created - HashRef - created conditions to match, optional
customer - Net::Stripe::Customer or Str - customer to match
ending_before - Str - ending before condition, optional
limit - Int - maximum number of charges to return, optional
starting_after - Str - starting after condition, optional
Returns a list of Net::Stripe::Charge objects.
$stripe->get_charges(customer => $customer, limit => 5);
https://stripe.com/docs/api/charges/capture#capture_charge
charge - Net::Stripe::Charge or Str - charge to capture
amount - Int - amount to capture
Returns a Net::Stripe::Charge.
$stripe->capture_charge(charge => $charge_id);
Create or update a customer.
https://stripe.com/docs/api/customers/create#create_customer https://stripe.com/docs/api/customers/update#update_customer
customer - Net::Stripe::Customer or StripeCustomerId - existing customer to update, optional
account_balance - Int, optional
balance - Int, optional
card - Net::Stripe::Token or StripeTokenId, default card for the customer, optional
source - StripeTokenId or StripeSourceId, source for the customer, optional
coupon - Str, optional
default_card - Net::Stripe::Token, Net::Stripe::Card, Str or HashRef, default card for the customer, optional
default_source - StripeCardId or StripeSourceId, default source for the customer, optional
description - Str, optional
email - Str, optional
metadata - HashRef, optional
plan - Str, optional
quantity - Int, optional
trial_end - Int or Str, optional
Returns a Net::Stripe::Customer object.
my $customer = $stripe->post_customer( source => $token_id, email => 'stripe@example.com', description => 'Test for Net::Stripe', );
Returns the subscriptions for a customer.
https://stripe.com/docs/api#list_subscriptions
customer - Net::Stripe::Customer or Str
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional
Returns a list of Net::Stripe::Subscription objects.
Retrieve a customer.
https://stripe.com/docs/api#retrieve_customer
customer_id - Str - the customer id to retrieve
Returns a Net::Stripe::List object containing Net::Stripe::Customer objects.
$stripe->get_customer(customer_id => $id);
Delete a customer.
https://stripe.com/docs/api#delete_customer
customer - Net::Stripe::Customer or Str - the customer to delete
$stripe->delete_customer(customer => $customer);
Returns a list of customers.
https://stripe.com/docs/api#list_customers
created - HashRef - created conditions, optional
$stripe->get_customers(limit => 7);
Retrieve information about a customer's card.
https://stripe.com/docs/api#retrieve_card
customer - Net::Stripe::Customer or Str - the customer
card_id - Str - the card ID to retrieve
Returns a Net::Stripe::Card.
$stripe->get_card(customer => 'customer_id', card_id => 'abcdef');
Create a card.
https://stripe.com/docs/api/cards/create#create_card
customer - Net::Stripe::Customer or StripeCustomerId
card - Net::Stripe::Token or StripeTokenId
source - StripeTokenId
$stripe->post_card(customer => $customer, source => $token_id);
Update a card.
https://stripe.com/docs/api/cards/update#update_card
customer_id - StripeCustomerId
card_id - StripeCardId
card - HashRef
$stripe->update_card( customer_id => $customer_id, card_id => $card_id, card => { name => $new_name, metadata => { 'account-number' => $new_account_nunmber, }, }, );
Returns a list of cards.
https://stripe.com/docs/api#list_cards
Returns a Net::Stripe::List object containing Net::Stripe::Card objects.
$stripe->list_cards(customer => 'abcdec', limit => 10);
Delete a card.
https://stripe.com/docs/api#delete_card
card - Net::Stripe::Card or Str
$stripe->delete_card(customer => $customer, card => $card);
Create a new source object
https://stripe.com/docs/api/sources/create#create_source
amount - Int - amount associated with the source
currency - Str - currency associated with the source
flow - StripeSourceFlow - authentication flow for the source
mandate - HashRef - information about a mandate attached to the source
metadata - HashRef - metadata for the source
owner - HashRef - information about the owner of the payment instrument
receiver - HashRef - parameters for the receiver flow
redirect - HashRef - parameters required for the redirect flow
source_order - HashRef - information about the items and shipping associated with the source
statement_descriptor - Str - descriptor for statement
token - StripeTokenId - token used to create the source
type - StripeSourceType - type of source to create - required
usage - StripeSourceUsage - whether the source should be reusable or not
Returns a Net::Stripe::Source
$stripe->create_source( type => 'card', token => $token_id, );
Retrieve an existing source object
https://stripe.com/docs/api/sources/retrieve#retrieve_source
source_id - StripeSourceId - id of source to retrieve - required
client_secret - Str - client secret of the source
$stripe->get_source( source_id => $source_id, );
Update the specified source by setting the values of the parameters passed
https://stripe.com/docs/api/sources/update#update_source
source_id - StripeSourceId - id of source to update - required
$stripe->update_source( source_id => $source_id, owner => { email => $new_email, phone => $new_phone, }, );
Attaches a Source object to a Customer
https://stripe.com/docs/api/sources/attach#attach_source
source_id - StripeSourceId - id of source to be attached - required
customer_id - StripeCustomerId - id of customer to which source should be attached - required
$stripe->attach_source( customer_id => $customer_id, source_id => $source->id, );
Detaches a Source object from a Customer
https://stripe.com/docs/api/sources/detach#detach_source
source_id - StripeSourceId - id of source to be detached - required
customer_id - StripeCustomerId - id of customer from which source should be detached - required
$stripe->detach_source( customer_id => $customer_id, source_id => $source->id, );
List all sources belonging to a Customer
customer_id - StripeCustomerId - id of customer for which source to list sources - required
object - Str - object type - required
ending_before - Str - ending before condition
limit - Int - maximum number of charges to return
starting_after - Str - starting after condition
Returns a Net::Stripe::List object containing objects of the requested type
$stripe->list_sources( customer_id => $customer_id, object => 'card', limit => 10, );
Adds or updates a subscription for a customer.
https://stripe.com/docs/api#create_subscription
customer - Net::Stripe::Customer
subscription - Net::Stripe::Subscription or Str
card - Net::Stripe::Card, Net::Stripe::Token or Str, default card for the customer, optional
trial_end - Int, or Str optional
application_fee_percent - Int, optional
prorate - Bool, optional
cancel_at_period_end - Bool, optional
Returns a Net::Stripe::Subscription object.
$stripe->post_subscription(customer => $customer, plan => 'testplan');
Returns a customer's subscription.
Returns a Net::Stripe::Subscription.
$stripe->get_subscription(customer => 'test123');
Cancel a customer's subscription.
https://stripe.com/docs/api#cancel_subscription
at_period_end - Bool, optional
$stripe->delete_subscription(customer => $customer, subscription => $subscription);
Retrieves an existing token.
https://stripe.com/docs/api#retrieve_token
token_id - Str
Returns a Net::Stripe::Token.
$stripe->get_token(token_id => 'testtokenid');
Create a new Product
https://stripe.com/docs/api/products/create#create_product https://stripe.com/docs/api/service_products/create#create_service_product
name - Str - name of the product - required
active - Bool - whether the product is currently available for purchase
attributes - ArrayRef[Str] - a list of attributes that each sku can provide values for
caption - Str - a short description
deactivate_on - ArrayRef[Str] - an list of connect application identifiers that cannot purchase this product
description - Str - description
id - Str - unique identifier
images - ArrayRef[Str] - a list of image URLs
metadata - HashRef[Str] - metadata
package_dimensions - HashRef - package dimensions for shipping
shippable - Bool - whether the product is a shipped good
type - StripeProductType - the type of the product
unit_label - Str - label that represents units of the product
url - Str - URL of a publicly-accessible web page for the product
Returns a Net::Stripe::Product
$stripe->create_product( name => $product_name, type => 'good', );
Retrieve an existing Product
https://stripe.com/docs/api/products/retrieve#retrieve_product https://stripe.com/docs/api/service_products/retrieve#retrieve_service_product
product_id - StripeProductId|Str - id of product to retrieve - required
$stripe->get_product( product_id => $product_id, );
Update an existing Product
https://stripe.com/docs/api/products/update#update_product https://stripe.com/docs/api/service_products/update#update_service_product
name - Str - name of the product
$stripe->update_product( product_id => $product_id, name => $new_name, );
Retrieve a list of Products
https://stripe.com/docs/api/products/list#list_products https://stripe.com/docs/api/service_products/list#list_service_products
active - Bool - only return products that are active or inactive
ids - StripeProductId|Str - only return products with the given ids
shippable - Bool - only return products that can or cannot be shipped
url - Str - only return products with the given url
type - StripeProductType - only return products of this type
created - HashRef[Str] - created conditions to match
limit - Int - maximum number of objects to return
Returns a Net::Stripe::List object containing Net::Stripe::Product objects.
$stripe->list_products( limit => 5, );
Delete an existing Product
https://stripe.com/docs/api/products/delete#delete_product https://stripe.com/docs/api/service_products/delete#delete_service_product
product_id - StripeProductId|Str - id of product to delete - required
Returns hashref of the form
{ deleted => <bool>, id => <product_id>, } $stripe->delete_product( product_id => $product_id, );
Create a new plan.
https://stripe.com/docs/api#create_plan
id - Str - identifier of the plan
amount - Int - cost of the plan in cents
currency - Str
interval - Str
interval_count - Int - optional
name - Str - name of the plan
trial_period_days - Int - optional
statement_descriptor - Str - optional
metadata - HashRef - optional
Returns a Net::Stripe::Plan object.
$stripe->post_plan( id => "free-$future_ymdhms", amount => 0, currency => 'usd', interval => 'year', name => "Freeplan $future_ymdhms", );
Retrieves a plan.
plan_id - Str
Returns a Net::Stripe::Plan.
$stripe->get_plan(plan_id => 'plan123');
Delete a plan.
https://stripe.com/docs/api#delete_plan
plan_id - Net::Stripe::Plan or Str
$stripe->delete_plan(plan_id => $plan);
Return a list of plans.
https://stripe.com/docs/api#list_plans
product - StripeProductId|Str - only return plans for the given product
Returns a Net::Stripe::List object containing Net::Stripe::Plan objects.
$stripe->get_plans(limit => 10);
Create or update a coupon.
https://stripe.com/docs/api#create_coupon
id - Str, optional
duration - Str
amount_offset - Int, optional
currency - Str, optional
duration_in_months - Int, optional
max_redemptions - Int, optional
percent_off - Int, optional
redeem_by - Int, optional
Returns a Net::Stripe::Coupon object.
$stripe->post_coupon( id => $coupon_id, percent_off => 100, duration => 'once', max_redemptions => 1, redeem_by => time() + 100, );
Retrieve a coupon.
https://stripe.com/docs/api#retrieve_coupon
coupon_id - Str
$stripe->get_coupon(coupon_id => 'id');
Delete a coupon.
https://stripe.com/docs/api#delete_coupon
Returns a Net::Stripe::Coupon.
$stripe->delete_coupon(coupon_id => 'coupon123');
Returns a Net::Stripe::List object containing Net::Stripe::Coupon objects.
$stripe->get_coupons(limit => 15);
Update an invoice.
invoice - Net::Stripe::Invoice, Str
closed - Bool - optional
description - Str - optional
Returns a Net::Stripe::Invoice.
$stripe->post_invoice(invoice => $invoice, closed => 1)
invoice_id - Str
$stripe->get_invoice(invoice_id => 'testinvoice');
$stripe->pay_invoice(invoice_id => 'testinvoice');
Returns a list of invoices.
https://stripe.com/docs/api#list_customer_invoices
customer - Net::Stripe::Customer or Str, optional
date - Int or HashRef, optional
Returns a Net::Stripe::List object containing Net::Stripe::Invoice objects.
$stripe->get_invoices(limit => 10);
Create a new invoice.
https://stripe.com/docs/api#create_invoice
customer - Net::Stripe::Customer, Str
subscription - Net::Stripe::Subscription or Str, optional
$stripe->create_invoice(customer => 'custid', description => 'test');
$stripe->get_invoice(invoice_id => 'test');
customer, Net::Stripe::Customer or Str
$stripe->get_upcominginvoice(customer => $customer);
Create an invoice item.
https://stripe.com/docs/api#create_invoiceitem
amount - Int
invoice - Net::Stripe::Invoice or Str, optional
Returns a Net::Stripe::Invoiceitem object.
$stripe->create_invoiceitem(customer => 'test', amount => 500, currency => 'USD');
Update an invoice item.
invoice_item - Net::Stripe::Invoiceitem or Str
amount - Int, optional
Returns a Net::Stripe::Invoiceitem.
$stripe->post_invoiceitem(invoice_item => 'itemid', amount => 750);
Retrieve an invoice item.
invoice_item - Str
$stripe->get_invoiceitem(invoice_item => 'testitemid');
Delete an invoice item.
$stripe->delete_invoiceitem(invoice_item => $invoice_item);
Returns a Net::Stripe::List object containing Net::Stripe::Invoiceitem objects.
$stripe->get_invoiceitems(customer => 'test', limit => 30);
Deletes a customer-wide discount.
https://stripe.com/docs/api/curl#delete_discount
customer - Net::Stripe::Customer or Str - the customer with a discount to delete
$stripe->delete_customer_discount(customer => $customer);
{ deleted => <bool> }
Create a PaymentMethod
https://stripe.com/docs/api/payment_methods/create#create_payment_method
type - StripePaymentMethodType - type of PaymentMethod - required
card - StripeTokenId - Token id for card associated with the PaymentMethod
billing_details - HashRef - billing information associated with the PaymentMethod
fpx - HashRef - details about the FPX payment method
ideal - HashRef - details about the iDEAL payment method
sepa_debit - HashRef - details about the SEPA debit bank account
Returns a Net::Stripe::PaymentMethod.
$stripe->create_payment_method( type => 'card', card => $token_id, );
Retrieve an existing PaymentMethod
https://stripe.com/docs/api/payment_methods/retrieve#retrieve_payment_method
payment_method_id - StripePaymentMethodId - id of PaymentMethod to retrieve - required
Returns a Net::Stripe::PaymentMethod
$stripe->get_payment_method( payment_method_id => $payment_method_id, );
Update a PaymentMethod
https://stripe.com/docs/api/payment_methods/update#update_payment_method
payment_method_id - StripePaymentMethodId - id of PaymentMethod to update - required
card - HashRef[Int] - card details to update
$stripe->update_payment_method( payment_method_id => $payment_method_id, metadata => $metadata, );
Retrieve a list of PaymentMethods
https://stripe.com/docs/api/payment_methods/list#list_payment_methods
customer - StripeCustomerId - return only PaymentMethods for the specified Customer id - required
type - Str - filter by type - required
Returns a Net::Stripe::List object containing Net::Stripe::PaymentMethod objects
$stripe->list_payment_methods( customer => $customer_id, type => 'card', limit => 10, );
Attach a PaymentMethod to a Customer
https://stripe.com/docs/api/payment_methods/attach#customer_attach_payment_method
payment_method_id - StripePaymentMethodId - id of PaymentMethod to attach - required
customer - StripeCustomerId - id of Customer to which to attach the PaymentMethod - required
$stripe->attach_payment_method( payment_method_id => $payment_method_id, customer => $customer, );
Detach a PaymentMethod from a Customer
https://stripe.com/docs/api/payment_methods/detach#customer_detach_payment_method
payment_method_id - StripePaymentMethodId - id of PaymentMethod to detach - required
$stripe->detach_payment_method( payment_method_id => $payment_method_id, );
Create a PaymentIntent object
https://stripe.com/docs/api/payment_intents/create#create_payment_intent
amount - Int - amount intended to be collected by this PaymentIntent - required
currency - Str - currency - required
application_fee_amount - Int - the amount of the application fee
capture_method - StripeCaptureMethod - capture method
confirm - Bool - attempt to confirm this PaymentIntent immediately
confirmation_method - StripeConfirmationMethod - confirmation method
customer - StripeCustomerId - id of Customer this PaymentIntent belongs to
error_on_requires_action - Bool - fail the payment attempt if the PaymentIntent transitions into `requires_action`
mandate - Str - id of the mandate to be used for this payment
mandate_data - HashRef - details about the Mandate to create
off_session - Bool - indicate that the customer is not in your checkout flow
on_behalf_of - Str - Stripe account ID for which these funds are intended
payment_method - StripePaymentMethodId - id of PaymentMethod to attach to this PaymentIntent
payment_method_options - HashRef - PaymentMethod-specific configuration for this PaymentIntent
payment_method_types - ArrayRef[StripePaymentMethodType] - list of PaymentMethod types that this PaymentIntent is allowed to use
receipt_email - Str - email address to send the receipt to
return_url - Str - URL to redirect your customer back to
save_payment_method - Bool - save the payment method to the customer
setup_future_usage - Str - allow future payments with this PaymentIntent's PaymentMethod
shipping - HashRef - shipping information for this PaymentIntent
statement_descriptor_suffix - Str - suffix to be concatenated with the statement descriptor
transfer_data - HashRef - parameters used to automatically create a Transfer when the payment succeeds
transfer_group - Str - identifies the resulting payment as part of a group
use_stripe_sdk - Bool - use manual confirmation and the iOS or Android SDKs to handle additional authentication steps
Returns a Net::Stripe::PaymentIntent
$stripe->create_payment_intent( amount => 3300, currency => 'usd', );
Retrieve an existing PaymentIntent
https://stripe.com/docs/api/payment_intents/retrieve#retrieve_payment_intent
payment_intent_id - StripePaymentIntentId - id of PaymentIntent to retrieve - required
client_secret - Str - client secret of the PaymentIntent to retrieve
$stripe->get_payment_intent( payment_intent_id => $payment_intent_id, );
Update an existing PaymentIntent
https://stripe.com/docs/api/payment_intents/update#update_payment_intent
payment_intent_id - StripePaymentIntentId - id of PaymentIntent to update - required
$stripe->update_payment_intent( payment_intent_id => $payment_intent_id, description => 'Updated Description', );
Confirm that customer intends to pay with provided PaymentMethod
https://stripe.com/docs/api/payment_intents/confirm#confirm_payment_intent
payment_intent_id - StripePaymentIntentId - id of PaymentIntent to confirm - required
client_secret - Str - client secret of the PaymentIntent
$stripe->confirm_payment_intent( payment_intent_id => $payment_intent_id, );
Capture the funds for the PaymentIntent
https://stripe.com/docs/api/payment_intents/capture#capture_payment_intent
payment_intent_id - StripePaymentIntentId - id of PaymentIntent to capture - required
amount_to_capture - Int - amount to capture from the PaymentIntent
application_fee_amount - Int - application fee amount
$stripe->capture_payment_intent( payment_intent_id => $payment_intent_id, );
Cancel the PaymentIntent
https://stripe.com/docs/api/payment_intents/cancel#cancel_payment_intent
payment_intent_id - StripePaymentIntentId - id of PaymentIntent to cancel - required
cancellation_reason - StripeCancellationReason - reason for cancellation
$stripe->cancel_payment_intent( payment_intent_id => $payment_intent_id, cancellation_reason => 'requested_by_customer', );
Retrieve a list of PaymentIntents
https://stripe.com/docs/api/payment_intents/list#list_payment_intents
customer - StripeCustomerId - return only PaymentIntents for the specified Customer id
created - HashRef[Int] - created conditions to match
Returns a Net::Stripe::List object containing Net::Stripe::PaymentIntent objects.
$stripe->list_payment_intents( customer => $customer_id, type => 'card', limit => 10, );
Stripe strongly discourages direct handling of PANs (primary account numbers), even in test mode, and returns invalid_request_error when passing PANs to the API from accounts that were created after October 2017. In live mode, all tokenization should be performed via client-side libraries because direct handling of PANs violates PCI compliance. So we have removed the methods and parameter constraints that allow direct handling of PANs and updated the unit tests appropriately.
If you have code that updates a customer card by updating the internal values for an existing customer object and then posting that object:
my $customer_obj = $stripe->get_customer( customer_id => $customer_id, ); $customer_obj->card( $new_card ); $stripe->post_customer( customer => $customer_obj );
you must unset the default_card attribute in the existing object before posting the customer object.
$customer_obj->default_card( undef );
Otherwise there is a conflict, since the old default_card attribute in the object is serialized in the POST stream, and it appears that you are requesting to set default_card to the id of a card that no longer exists, but rather is being replaced by the new value of the card attribute in the object.
For Stripe API versions after 2018-02-15 https://stripe.com/docs/upgrades#2018-02-05 each Plan object is linked to a Product object with type=service. The Plan object 'name' and 'statement_descriptor' attributes have been moved to Product objects.
While the API returns both card-related and source-related values for earlier versions, making the update mostly backwards-compatible, Stripe API versions after 2015-02-18 https://stripe.com/docs/upgrades#2015-02-18 will no longer return the card-related values, so you should update your code where necessary to use the 'source' argument and method for Charge objects, and the 'source', 'sources' and 'default_source' arguments and methods for Customer, in preparation for the eventual deprecation of the card-related arguments.
While the API returns both 'account_balance' and 'balance' for earlier versions, making the update backwards-compatible, Stripe API versions after 2019-10-17 https://stripe.com/docs/upgrades#2019-10-17 do not accept or return 'account_balance', so you should update your code where necessary to use the 'balance' argument and method for Customer objects in preparation for the eventual deprecation of the 'account_balance' argument.
For Stripe API versions after 2018-08-23 https://stripe.com/docs/upgrades#2018-08-23, you can no longer use 'at_period_end' in delete_subscription(). The delete_subscription() method is reserved for immediate canceling going forward. You should update your code to use 'cancel_at_period_end in update_subscription() instead.
While the API returns both 'date' and 'created' for earlier versions, making the update backwards-compatible, Stripe API versions after 2019-03-14 https://stripe.com/docs/upgrades#2019-03-14 only return 'created', so you should update your code where necessary to use the 'created' method for Invoice objects in preparation for the eventual deprecation of the 'date' argument.
The 'closed' attribute for the Invoice object controls automatic collection, and has been deprecated in favor of the more specific 'auto_advance' attribute. Where you might have set closed=true on Invoices in the past, set auto_advance=false. While the API returns both 'closed' and 'auto_advance' for earlier versions, making the update backwards-compatible, Stripe API versions after 2018-11-08 https://stripe.com/docs/upgrades#2018-11-08 only return 'auto_advance', so you should update your code where necessary to use the 'auto_advance' argument and method for Invoice objects in preparation for the eventual deprecation of the 'closed' argument.
Some argument types for `customer` and `card` were non-functional in the current code and have been removed from the Kavorka method signature. We removed `Net::Stripe::Customer` and `HashRef` for `customer` and we removed `Net::Stripe::Card` and `Net::Stripe::Token` for `card`, as none of these forms were being serialized correctly for passing to the API call. We must retain `Net::Stripe::Card` for the `card` attribute in `Net::Stripe::Charge` because the `card` value returned from the API call is objectified into a card object. We have also added TypeConstraints for the string arguments passed and added in-method validation to ensure that the passed argument values make sense in the context of one another.
Some argument types for `card` are not legitimate, or are being deprecated and have been removed from the Kavorka method signature. We removed `Net::Stripe::Card` and updated the string validation to disallow card id for `card`, as neither of these are legitimate when creating or updating a card https://github.com/lukec/stripe-perl/issues/138, and the code path that appeared to be handling `Net::Stripe::Card` was actually unreachable https://github.com/lukec/stripe-perl/issues/100. We removed the dead code paths and made the conditional structure more explicit, per discussion in https://github.com/lukec/stripe-perl/pull/133. We also added unit tests for all calling forms, per https://github.com/lukec/stripe-perl/issues/139.
Some argument types for `card` are not legitimate and have been removed from the Kavorka method signature. We removed `Net::Stripe::Card` and updated the string validation to disallow card id for `card`, as neither of these are legitimate when creating or updating a customer https://github.com/lukec/stripe-perl/issues/138. We have also updated the structure of the method so that we always create a Net::Stripe::Customer object before posting https://github.com/lukec/stripe-perl/issues/148 and cleaned up and centralized Net::Stripe:Token coercion code.
Prior to ff84dd7, we were passing %args directly to _post(), and therefore default_card would have been included in the POST stream. Now we are creating a Net::Stripe::Customer object and posting it, so the posted parameters rely on the explicit list in $customer_obj->form_fields(), which was lacking default_card. See also BREAKING CHANGES.
In older Stripe API versions, some list-type data structures were returned as arrayrefs. We now coerce those old-style lists and collections into the hashref format that newer versions of the API return, with metadata stored top-level keys and the list elements in an arrayref with the key 'data', which is the format that Net::Stripe::List expects. This makes the SDK compatible with the Stripe API back to the earliest documented API version https://stripe.com/docs/upgrades#2011-06-21.
Net::Stripe::List
When passing a hashref with a nested metadata hashref to _post(), that metadata must be encoded properly before being passed to the Stripe API. There is now a dedicated block in convert_to_form_fields for this operation. This update was necessary because of the addition of update_card(), which accepts a card hashref, which may include metadata.
We removed the nested tertiary operator in _post() and updated convert_to_form_fields() so that it now handles encoding of objects, both top-level and nested. This streamlines the hashref vs object serailizing code, making it easy to adapt to other methods.
We were using string contatenation to both serilize the individual query args, in _get_collections(), and to join the individual query args together, in _get_with_args(). This also involved some unnecessary duplication of the logic that convert_to_form_fields() was already capable of handling. We now use convert_to_form_fields() to process the passed data, and URI to encode and serialize the query string. Along with other updates to convert_to_form_fields(), _get() can now easily handle the same calling form as _post(), eliminating the need for _get_collections() and _get_with_args(). We have also updated _delete() accordingly.
Similar to methods provided by other SDKs, calls using this method will allow access to all records for a given object type without having to manually paginate through the results. It is not intended to be used directly, but will be accessed through new and existing list-retrieval methods. In order to maintain backwards-compatibility with existing list retrieval behavior, this method supports passing a value of 0 for 'limit' in order to retrieve all records. Any other positive integer value for 'limit' will attempt to retrieve that number of records up to the maximum available. As before, not passing a value for 'limit', or explicitly passing an undefined value, retrieves whatever number of records the API returns by default.
The statement_description attribute is now statement_descriptor for Net::Stripe::Charge and Net::Stripe::Plan. The API docs https://stripe.com/docs/upgrades#2014-12-17 indicate that this change is backwards-compatible. You must update your code to reflect this change for parameters passed to these objects and methods called on these objects.
For Stripe API versions after 2015-02-18 https://stripe.com/docs/upgrades#2015-02-18, the status property on the Charge object has a value of 'succeeded' for successful charges. Previously, the status property would be 'paid' for successful charges. This change does not affect the API calls themselves, but if your account is using Stripe API version 2015-02-18 or later, you should update any code that relies on strict checking of the return value of Charge->status.
This method allows updates to card address, expiration, metadata, etc for existing customer cards.
Added type and client_ip attributes for Net::Stripe::Token.
Passing 'amount' to capture_charge() allows capture of a partial charge. Per the API, any remaining amount is immediately refunded. The charge object now also has a 'refunds' attribute, representing a Net::Stripe::List of Net::Stripe::Refund objects for the charge.
Added a Source object. Also added 'source' attribute and argument for Charge objects and methods, and added 'source', 'sources' and 'default_source' attributes and arguments for Customer objects and methods.
Added 'balance' attribute and arguments for Customer objects and methods.
Added 'cancel_at_period_end' argument update_subscription() and added 'cancel_at_period_end' to the POST stream for Subscription objects.
Added 'created' attribute for Invoice objects, and removed the required constraint for the deprecated 'date' attribute. Also added the 'auto_advance' attribute and removed the required constraint for the deprecated 'closed' attribute.
Added a Product object. Also added 'product' attribute and argument for Plan objects and methods.
Added PaymentMethod and PaymentIntent objects and methods.
https://stripe.com, https://stripe.com/docs/api
Luke Closs
Rusty Conover
Andrew Solomon <andrew@geekuni.com>
Andrew Solomon <andrew@illywhacker.net>
Brian Collins <bricollins@gmail.com>
Devin M. Certas <devin@nacredata.com>
Dimitar Petrov <mitakaa@gmail.com>
Dylan Reinhold <dylan@gasdasoftware.com>
E. Choroba <choroba@matfyz.cz>
Florian Heyer <info@heyer-it.de>
Hermann Calabria <hermann@ivouch.com>
Jonathan "Duke" Leto <jonathan@leto.net>
Luke Closs <lukec@users.noreply.github.com>
Luke Closs <me@luk.ec>
Mohammad S Anwar <mohammad.anwar@yahoo.com>
Olaf Alders <olaf@wundersolutions.com>
Paul Cochrane <paul@liekut.de>
Peter Scott <peter@shotgundriver.com>
Rusty Conover <rusty@luckydinosaur.com>
Sachin Sebastian <sachinjsk@users.noreply.github.com>
Sherrard Burton <32931314+sherrardb@users.noreply.github.com>
Sherrard Burton <sburton@allafrica.com>
Slobodan Mišković <slobodan@miskovic.ca>
Tom Eliaz <tom@tomeliaz.com>
This software is copyright (c) 2015 by Prime Radiant, Inc., (c) copyright 2014 Lucky Dinosaur LLC.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Net::Stripe, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Stripe
CPAN shell
perl -MCPAN -e shell install Net::Stripe
For more information on module installation, please visit the detailed CPAN module installation guide.