=pod
=head1 NAME
Net::Stripe - API client for Stripe.com
=head1 VERSION
version 0.41
=head1 SYNOPSIS
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);
Charges: post_charge() get_charge() refund_charge() get_charges()
Customer: post_customer()
=head1 DESCRIPTION
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.
=head2 VERSIONING
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 C and
C.
If you need a version of the SDK supporting a specific older Stripe API
version, you can check for available versions at
Lhttps://github.com/lukec/stripe-perl/branches, or by cloning this
repository, located at https://github.com/lukec/stripe-perl and using
to view available version-specific branches.
=head3 DEFAULT VERSIONING
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.
=head3 SPECIFIC VERSIONING
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
.
=head3 OUT OF SCOPE VERSIONING
If you are wearing a cowboy hat and think - although your specified account
version is outside the range defined in C - that your
use case is simple enough that it should "just work", you can create your
object instance with C 1>, but don't say we didn't
warn you!
=head1 METHODS
=head2 new PARAMHASH
This creates a new stripe API object. The following parameters are accepted:
=over
=item api_key
This is required. You get this from your Stripe Account settings.
=item api_version
This is the value of the Stripe-Version header
you wish to transmit for API calls.
=item force_api_version
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!
=item debug
You can set this to true to see extra debug info.
=item debug_network
You can set this to true to see the actual network requests.
=back
=head1 ATTRIBUTES
=head2 api_base
Reader: api_base
Type: Str
Additional documentation: This is the base part of the URL for every request made
=head2 api_key
Reader: api_key
Type: Str
This attribute is required.
Additional documentation: You get this from your Stripe Account settings
=head2 api_version
Reader: api_version
Type: StripeAPIVersion
Additional documentation: This is the value of the Stripe-Version header you wish to transmit for API calls
=head2 debug
Reader: debug
Writer: debug
Type: Bool
Additional documentation: The debug flag
=head2 debug_network
Reader: debug_network
Writer: debug_network
Type: Bool
Additional documentation: The debug network request flag
=head2 force_api_version
Reader: force_api_version
Type: Bool
Additional documentation: Set this to true to bypass the safety checks for API version compatibility.
=head2 ua
Reader: ua
Type: Object
Additional documentation: The LWP::UserAgent that is used for requests
=head1 Balance Transaction Methods
=head2 get_balance_transaction
Retrieve a balance transaction.
L
=over
=item * id - Str - balance transaction ID to retrieve.
=back
Returns a L.
$stripe->get_balance_transaction(id => 'id');
=head1 Charge Methods
=head2 post_charge
Create a new charge.
L
=over
=item * amount - Int - amount to charge
=item * currency - Str - currency for charge
=item * customer - StripeCustomerId - customer to charge - optional
=item * card - StripeTokenId or StripeCardId - card to use - optional
=item * source - StripeTokenId or StripeCardId - source to use - optional
=item * description - Str - description for the charge - optional
=item * metadata - HashRef - metadata for the charge - optional
=item * capture - Bool - optional
=item * statement_descriptor - Str - descriptor for statement - optional
=item * application_fee - Int - optional
=item * receipt_email - Str - The email address to send this charge's receipt to - optional
=back
Returns L.
$stripe->post_charge(currency => 'USD', amount => 500, customer => 'testcustomer');
=head2 get_charge
Retrieve a charge.
L
=over
=item * charge_id - Str - charge id to retrieve
=back
Returns L.
$stripe->get_charge(charge_id => 'chargeid');
=head2 refund_charge
Refunds a charge.
L
=over
=item * charge - L or Str - charge or charge_id to refund
=item * amount - Int - amount to refund in cents, optional
=back
Returns a new L.
$stripe->refund_charge(charge => $charge, amount => 500);
=head2 get_charges
Returns a L object containing L objects.
L
=over
=item * created - HashRef - created conditions to match, optional
=item * customer - L or Str - customer to match
=item * ending_before - Str - ending before condition, optional
=item * limit - Int - maximum number of charges to return, optional
=item * starting_after - Str - starting after condition, optional
=back
Returns a list of L objects.
$stripe->get_charges(customer => $customer, limit => 5);
=head2 capture_charge
L
=over
=item * charge - L or Str - charge to capture
=item * amount - Int - amount to capture
=back
Returns a L.
$stripe->capture_charge(charge => $charge_id);
=head1 Customer Methods
=head2 post_customer
Create or update a customer.
L
L
=over
=item * customer - L or StripeCustomerId - existing customer to update, optional
=item * account_balance - Int, optional
=item * balance - Int, optional
=item * card - L or StripeTokenId, default card for the customer, optional
=item * source - StripeTokenId or StripeSourceId, source for the customer, optional
=item * coupon - Str, optional
=item * default_card - L, L, Str or HashRef, default card for the customer, optional
=item * default_source - StripeCardId or StripeSourceId, default source for the customer, optional
=item * description - Str, optional
=item * email - Str, optional
=item * metadata - HashRef, optional
=item * plan - Str, optional
=item * quantity - Int, optional
=item * trial_end - Int or Str, optional
=back
Returns a L object.
my $customer = $stripe->post_customer(
source => $token_id,
email => 'stripe@example.com',
description => 'Test for Net::Stripe',
);
=head2 list_subscriptions
Returns the subscriptions for a customer.
L
=over
=item * customer - L or Str
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a list of L objects.
=head2 get_customer
Retrieve a customer.
L
=over
=item * customer_id - Str - the customer id to retrieve
=back
Returns a L object containing L objects.
$stripe->get_customer(customer_id => $id);
=head2 delete_customer
Delete a customer.
L
=over
=item * customer - L or Str - the customer to delete
=back
Returns a L object.
$stripe->delete_customer(customer => $customer);
=head2 get_customers
Returns a list of customers.
L
=over
=item * created - HashRef - created conditions, optional
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->get_customers(limit => 7);
=head1 Card Methods
=head2 get_card
Retrieve information about a customer's card.
L
=over
=item * customer - L or Str - the customer
=item * card_id - Str - the card ID to retrieve
=back
Returns a L.
$stripe->get_card(customer => 'customer_id', card_id => 'abcdef');
=head2 post_card
Create a card.
L
=over
=item * customer - L or StripeCustomerId
=item * card - L or StripeTokenId
=item * source - StripeTokenId
=back
Returns a L.
$stripe->post_card(customer => $customer, source => $token_id);
=head2 update_card
Update a card.
L
=over
=item * customer_id - StripeCustomerId
=item * card_id - StripeCardId
=item * card - HashRef
=back
Returns a L.
$stripe->update_card(
customer_id => $customer_id,
card_id => $card_id,
card => {
name => $new_name,
metadata => {
'account-number' => $new_account_nunmber,
},
},
);
=head2 get_cards
Returns a list of cards.
L
=over
=item * customer - L or Str
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->list_cards(customer => 'abcdec', limit => 10);
=head2 delete_card
Delete a card.
L
=over
=item * customer - L or Str
=item * card - L or Str
=back
Returns a L.
$stripe->delete_card(customer => $customer, card => $card);
=head1 Source Methods
=head2 create_source
Create a new source object
L
=over
=item * amount - Int - amount associated with the source
=item * currency - Str - currency associated with the source
=item * flow - StripeSourceFlow - authentication flow for the source
=item * mandate - HashRef - information about a mandate attached to the source
=item * metadata - HashRef - metadata for the source
=item * owner - HashRef - information about the owner of the payment instrument
=item * receiver - HashRef - parameters for the receiver flow
=item * redirect - HashRef - parameters required for the redirect flow
=item * source_order - HashRef - information about the items and shipping associated with the source
=item * statement_descriptor - Str - descriptor for statement
=item * token - StripeTokenId - token used to create the source
=item * type - StripeSourceType - type of source to create - required
=item * usage - StripeSourceUsage - whether the source should be reusable or not
=back
Returns a L
$stripe->create_source(
type => 'card',
token => $token_id,
);
=head2 get_source
Retrieve an existing source object
L
=over
=item * source_id - StripeSourceId - id of source to retrieve - required
=item * client_secret - Str - client secret of the source
=back
Returns a L
$stripe->get_source(
source_id => $source_id,
);
=head2 update_source
Update the specified source by setting the values of the parameters passed
L
=over
=item * source_id - StripeSourceId - id of source to update - required
=item * amount - Int - amount associated with the source
=item * metadata - HashRef - metadata for the source
=item * mandate - HashRef - information about a mandate attached to the source
=item * owner - HashRef - information about the owner of the payment instrument
=item * source_order - HashRef - information about the items and shipping associated with the source
=back
Returns a L
$stripe->update_source(
source_id => $source_id,
owner => {
email => $new_email,
phone => $new_phone,
},
);
=head2 attach_source
Attaches a Source object to a Customer
L
=over
=item * source_id - StripeSourceId - id of source to be attached - required
=item * customer_id - StripeCustomerId - id of customer to which source should be attached - required
=back
Returns a L
$stripe->attach_source(
customer_id => $customer_id,
source_id => $source->id,
);
=head2 detach_source
Detaches a Source object from a Customer
L
=over
=item * source_id - StripeSourceId - id of source to be detached - required
=item * customer_id - StripeCustomerId - id of customer from which source should be detached - required
=back
Returns a L
$stripe->detach_source(
customer_id => $customer_id,
source_id => $source->id,
);
=head2 list_sources
List all sources belonging to a Customer
=over
=item * customer_id - StripeCustomerId - id of customer for which source to list sources - required
=item * object - Str - object type - required
=item * ending_before - Str - ending before condition
=item * limit - Int - maximum number of charges to return
=item * starting_after - Str - starting after condition
=back
Returns a L object containing objects of the requested type
$stripe->list_sources(
customer_id => $customer_id,
object => 'card',
limit => 10,
);
=head1 Subscription Methods
=head2 post_subscription
Adds or updates a subscription for a customer.
L
=over
=item * customer - L
=item * subscription - L or Str
=item * card - L, L or Str, default card for the customer, optional
=item * coupon - Str, optional
=item * description - Str, optional
=item * plan - Str, optional
=item * quantity - Int, optional
=item * trial_end - Int, or Str optional
=item * application_fee_percent - Int, optional
=item * prorate - Bool, optional
=item * cancel_at_period_end - Bool, optional
=back
Returns a L object.
$stripe->post_subscription(customer => $customer, plan => 'testplan');
=head2 get_subscription
Returns a customer's subscription.
=over
=item * customer - L or Str
=back
Returns a L.
$stripe->get_subscription(customer => 'test123');
=head2 delete_subscription
Cancel a customer's subscription.
L
=over
=item * customer - L or Str
=item * subscription - L or Str
=item * at_period_end - Bool, optional
=back
Returns a L object.
$stripe->delete_subscription(customer => $customer, subscription => $subscription);
=head1 Token Methods
=head2 get_token
Retrieves an existing token.
L
=over
=item * token_id - Str
=back
Returns a L.
$stripe->get_token(token_id => 'testtokenid');
=head1 Product Methods
=head2 create_product
Create a new Product
L
L
=over
=item * name - Str - name of the product - required
=item * active - Bool - whether the product is currently available for purchase
=item * attributes - ArrayRef[Str] - a list of attributes that each sku can provide values for
=item * caption - Str - a short description
=item * deactivate_on - ArrayRef[Str] - an list of connect application identifiers that cannot purchase this product
=item * description - Str - description
=item * id - Str - unique identifier
=item * images - ArrayRef[Str] - a list of image URLs
=item * metadata - HashRef[Str] - metadata
=item * package_dimensions - HashRef - package dimensions for shipping
=item * shippable - Bool - whether the product is a shipped good
=item * statement_descriptor - Str - descriptor for statement
=item * type - StripeProductType - the type of the product
=item * unit_label - Str - label that represents units of the product
=item * url - Str - URL of a publicly-accessible web page for the product
=back
Returns a L
$stripe->create_product(
name => $product_name,
type => 'good',
);
=head2 get_product
Retrieve an existing Product
L
L
=over
=item * product_id - StripeProductId|Str - id of product to retrieve - required
=back
Returns a L
$stripe->get_product(
product_id => $product_id,
);
=head2 update_product
Update an existing Product
L
L
=over
=item * product_id - StripeProductId|Str - id of product to retrieve - required
=item * active - Bool - whether the product is currently available for purchase
=item * attributes - ArrayRef[Str] - a list of attributes that each sku can provide values for
=item * caption - Str - a short description
=item * deactivate_on - ArrayRef[Str] - an list of connect application identifiers that cannot purchase this product
=item * description - Str - description
=item * images - ArrayRef[Str] - a list of image URLs
=item * metadata - HashRef[Str] - metadata
=item * name - Str - name of the product
=item * package_dimensions - HashRef - package dimensions for shipping
=item * shippable - Bool - whether the product is a shipped good
=item * statement_descriptor - Str - descriptor for statement
=item * type - StripeProductType - the type of the product
=item * unit_label - Str - label that represents units of the product
=item * url - Str - URL of a publicly-accessible web page for the product
=back
Returns a L
$stripe->update_product(
product_id => $product_id,
name => $new_name,
);
=head2 list_products
Retrieve a list of Products
L
L
=over
=item * active - Bool - only return products that are active or inactive
=item * ids - StripeProductId|Str - only return products with the given ids
=item * shippable - Bool - only return products that can or cannot be shipped
=item * url - Str - only return products with the given url
=item * type - StripeProductType - only return products of this type
=item * created - HashRef[Str] - created conditions to match
=item * ending_before - Str - ending before condition
=item * limit - Int - maximum number of objects to return
=item * starting_after - Str - starting after condition
=back
Returns a L object containing L objects.
$stripe->list_products(
limit => 5,
);
=head2 delete_product
Delete an existing Product
L
L
=over
=item * product_id - StripeProductId|Str - id of product to delete - required
=back
Returns hashref of the form
{
deleted => ,
id => ,
}
$stripe->delete_product(
product_id => $product_id,
);
=head1 Plan Methods
=head2 post_plan
Create a new plan.
L
=over
=item * id - Str - identifier of the plan
=item * amount - Int - cost of the plan in cents
=item * currency - Str
=item * interval - Str
=item * interval_count - Int - optional
=item * name - Str - name of the plan
=item * trial_period_days - Int - optional
=item * statement_descriptor - Str - optional
=item * metadata - HashRef - optional
=back
Returns a L object.
$stripe->post_plan(
id => "free-$future_ymdhms",
amount => 0,
currency => 'usd',
interval => 'year',
name => "Freeplan $future_ymdhms",
);
=head2 get_plan
Retrieves a plan.
=over
=item * plan_id - Str
=back
Returns a L.
$stripe->get_plan(plan_id => 'plan123');
=head2 delete_plan
Delete a plan.
L
=over
=item * plan_id - L or Str
=back
Returns a L object.
$stripe->delete_plan(plan_id => $plan);
=head2 get_plans
Return a list of plans.
L
=over
=item * product - StripeProductId|Str - only return plans for the given product
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->get_plans(limit => 10);
=head1 Coupon Methods
=head2 post_coupon
Create or update a coupon.
L
=over
=item * id - Str, optional
=item * duration - Str
=item * amount_offset - Int, optional
=item * currency - Str, optional
=item * duration_in_months - Int, optional
=item * max_redemptions - Int, optional
=item * metadata - HashRef, optional
=item * percent_off - Int, optional
=item * redeem_by - Int, optional
=back
Returns a L object.
$stripe->post_coupon(
id => $coupon_id,
percent_off => 100,
duration => 'once',
max_redemptions => 1,
redeem_by => time() + 100,
);
=head2 get_coupon
Retrieve a coupon.
L
=over
=item * coupon_id - Str
=back
Returns a L object.
$stripe->get_coupon(coupon_id => 'id');
=head2 delete_coupon
Delete a coupon.
L
=over
=item * coupon_id - Str
=back
Returns a L.
$stripe->delete_coupon(coupon_id => 'coupon123');
=head2 get_coupons
=over
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->get_coupons(limit => 15);
=head1 Invoice Methods
=head2 post_invoice
Update an invoice.
=over
=item * invoice - L, Str
=item * application_fee - Int - optional
=item * closed - Bool - optional
=item * description - Str - optional
=item * metadata - HashRef - optional
=back
Returns a L.
$stripe->post_invoice(invoice => $invoice, closed => 1)
=head2 get_invoice
=over
=item * invoice_id - Str
=back
Returns a L.
$stripe->get_invoice(invoice_id => 'testinvoice');
=head2 pay_invoice
=over
=item * invoice_id - Str
=back
Returns a L.
$stripe->pay_invoice(invoice_id => 'testinvoice');
=head2 get_invoices
Returns a list of invoices.
L
=over
=item * customer - L or Str, optional
=item * date - Int or HashRef, optional
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->get_invoices(limit => 10);
=head2 create_invoice
Create a new invoice.
L
=over
=item * customer - L, Str
=item * application_fee - Int - optional
=item * description - Str - optional
=item * metadata - HashRef - optional
=item * subscription - L or Str, optional
=back
Returns a L.
$stripe->create_invoice(customer => 'custid', description => 'test');
=head2 get_invoice
=over
=item * invoice_id - Str
=back
Returns a L.
$stripe->get_invoice(invoice_id => 'test');
=head2 get_upcominginvoice
=over
=item * customer, L or Str
=back
Returns a L.
$stripe->get_upcominginvoice(customer => $customer);
=head1 Invoice Item Methods
=head2 create_invoiceitem
Create an invoice item.
L
=over
=item * customer - L or Str
=item * amount - Int
=item * currency - Str
=item * invoice - L or Str, optional
=item * subscription - L or Str, optional
=item * description - Str, optional
=item * metadata - HashRef, optional
=back
Returns a L object.
$stripe->create_invoiceitem(customer => 'test', amount => 500, currency => 'USD');
=head2 post_invoiceitem
Update an invoice item.
L
=over
=item * invoice_item - L or Str
=item * amount - Int, optional
=item * description - Str, optional
=item * metadata - HashRef, optional
=back
Returns a L.
$stripe->post_invoiceitem(invoice_item => 'itemid', amount => 750);
=head2 get_invoiceitem
Retrieve an invoice item.
=over
=item * invoice_item - Str
=back
Returns a L.
$stripe->get_invoiceitem(invoice_item => 'testitemid');
=head2 delete_invoiceitem
Delete an invoice item.
=over
=item * invoice_item - L or Str
=back
Returns a L.
$stripe->delete_invoiceitem(invoice_item => $invoice_item);
=head2 get_invoiceitems
=over
=item * customer - L or Str, optional
=item * date - Int or HashRef, optional
=item * ending_before - Str, optional
=item * limit - Int, optional
=item * starting_after - Str, optional
=back
Returns a L object containing L objects.
$stripe->get_invoiceitems(customer => 'test', limit => 30);
=head1 Discount Methods
=head2 delete_customer_discount
Deletes a customer-wide discount.
L
=over
=item * customer - L or Str - the customer with a discount to delete
=back
$stripe->delete_customer_discount(customer => $customer);
Returns hashref of the form
{
deleted =>
}
=head1 Payment Method Methods
=head2 create_payment_method
Create a PaymentMethod
L
=over
=item * type - StripePaymentMethodType - type of PaymentMethod - required
=item * card - StripeTokenId - Token id for card associated with the PaymentMethod
=item * billing_details - HashRef - billing information associated with the PaymentMethod
=item * fpx - HashRef - details about the FPX payment method
=item * ideal - HashRef - details about the iDEAL payment method
=item * metadata - HashRef[Str] - metadata
=item * sepa_debit - HashRef - details about the SEPA debit bank account
=back
Returns a L.
$stripe->create_payment_method(
type => 'card',
card => $token_id,
);
=head2 get_payment_method
Retrieve an existing PaymentMethod
L
=over
=item * payment_method_id - StripePaymentMethodId - id of PaymentMethod to retrieve - required
=back
Returns a L
$stripe->get_payment_method(
payment_method_id => $payment_method_id,
);
=head2 update_payment_method
Update a PaymentMethod
L
=over
=item * payment_method_id - StripePaymentMethodId - id of PaymentMethod to update - required
=item * billing_details - HashRef - billing information associated with the PaymentMethod
=item * card - HashRef[Int] - card details to update
=item * metadata - HashRef[Str] - metadata
=item * sepa_debit - HashRef - details about the SEPA debit bank account
=back
Returns a L
$stripe->update_payment_method(
payment_method_id => $payment_method_id,
metadata => $metadata,
);
=head2 list_payment_methods
Retrieve a list of PaymentMethods
L
=over
=item * customer - StripeCustomerId - return only PaymentMethods for the specified Customer id - required
=item * type - Str - filter by type - required
=item * ending_before - Str - ending before condition
=item * limit - Int - maximum number of objects to return
=item * starting_after - Str - starting after condition
=back
Returns a L object containing L objects
$stripe->list_payment_methods(
customer => $customer_id,
type => 'card',
limit => 10,
);
=head2 attach_payment_method
Attach a PaymentMethod to a Customer
L
=over
=item * payment_method_id - StripePaymentMethodId - id of PaymentMethod to attach - required
=item * customer - StripeCustomerId - id of Customer to which to attach the PaymentMethod - required
=back
Returns a L
$stripe->attach_payment_method(
payment_method_id => $payment_method_id,
customer => $customer,
);
=head2 detach_payment_method
Detach a PaymentMethod from a Customer
L
=over
=item * payment_method_id - StripePaymentMethodId - id of PaymentMethod to detach - required
=back
Returns a L.
$stripe->detach_payment_method(
payment_method_id => $payment_method_id,
);
=head1 Payment Intent Methods
=head2 create_payment_intent
Create a PaymentIntent object
L
=over
=item * amount - Int - amount intended to be collected by this PaymentIntent - required
=item * currency - Str - currency - required
=item * application_fee_amount - Int - the amount of the application fee
=item * capture_method - StripeCaptureMethod - capture method
=item * confirm - Bool - attempt to confirm this PaymentIntent immediately
=item * confirmation_method - StripeConfirmationMethod - confirmation method
=item * customer - StripeCustomerId - id of Customer this PaymentIntent belongs to
=item * description - Str - description
=item * error_on_requires_action - Bool - fail the payment attempt if the PaymentIntent transitions into `requires_action`
=item * mandate - Str - id of the mandate to be used for this payment
=item * mandate_data - HashRef - details about the Mandate to create
=item * metadata - HashRef[Str] - metadata
=item * off_session - Bool - indicate that the customer is not in your checkout flow
=item * on_behalf_of - Str - Stripe account ID for which these funds are intended
=item * payment_method - StripePaymentMethodId - id of PaymentMethod to attach to this PaymentIntent
=item * payment_method_options - HashRef - PaymentMethod-specific configuration for this PaymentIntent
=item * payment_method_types - ArrayRef[StripePaymentMethodType] - list of PaymentMethod types that this PaymentIntent is allowed to use
=item * receipt_email - Str - email address to send the receipt to
=item * return_url - Str - URL to redirect your customer back to
=item * save_payment_method - Bool - save the payment method to the customer
=item * setup_future_usage - Str - allow future payments with this PaymentIntent's PaymentMethod
=item * shipping - HashRef - shipping information for this PaymentIntent
=item * statement_descriptor - Str - descriptor for statement
=item * statement_descriptor_suffix - Str - suffix to be concatenated with the statement descriptor
=item * transfer_data - HashRef - parameters used to automatically create a Transfer when the payment succeeds
=item * transfer_group - Str - identifies the resulting payment as part of a group
=item * use_stripe_sdk - Bool - use manual confirmation and the iOS or Android SDKs to handle additional authentication steps
=back
Returns a L
$stripe->create_payment_intent(
amount => 3300,
currency => 'usd',
);
=head2 get_payment_intent
Retrieve an existing PaymentIntent
L
=over
=item * payment_intent_id - StripePaymentIntentId - id of PaymentIntent to retrieve - required
=item * client_secret - Str - client secret of the PaymentIntent to retrieve
=back
Returns a L
$stripe->get_payment_intent(
payment_intent_id => $payment_intent_id,
);
=head2 update_payment_intent
Update an existing PaymentIntent
L
=over
=item * payment_intent_id - StripePaymentIntentId - id of PaymentIntent to update - required
=item * amount - Int - amount intended to be collected by this PaymentIntent - required
=item * application_fee_amount - Int - the amount of the application fee
=item * currency - Str - currency - required
=item * customer - StripeCustomerId - id of Customer this PaymentIntent belongs to
=item * description - Str - description
=item * metadata - HashRef[Str] - metadata
=item * payment_method - StripePaymentMethodId - id of PaymentMethod to attach to this PaymentIntent
=item * payment_method_options - HashRef - PaymentMethod-specific configuration for this PaymentIntent
=item * payment_method_types - ArrayRef[StripePaymentMethodType] - list of PaymentMethod types that this PaymentIntent is allowed to use
=item * receipt_email - Str - email address to send the receipt to
=item * save_payment_method - Bool - save the payment method to the customer
=item * setup_future_usage - Str - allow future payments with this PaymentIntent's PaymentMethod
=item * shipping - HashRef - shipping information for this PaymentIntent
=item * statement_descriptor - Str - descriptor for statement
=item * statement_descriptor_suffix - Str - suffix to be concatenated with the statement descriptor
=item * transfer_data - HashRef - parameters used to automatically create a Transfer when the payment succeeds
=item * transfer_group - Str - identifies the resulting payment as part of a group
=back
Returns a L
$stripe->update_payment_intent(
payment_intent_id => $payment_intent_id,
description => 'Updated Description',
);
=head2 confirm_payment_intent
Confirm that customer intends to pay with provided PaymentMethod
L
=over
=item * payment_intent_id - StripePaymentIntentId - id of PaymentIntent to confirm - required
=item * client_secret - Str - client secret of the PaymentIntent
=item * error_on_requires_action - Bool - fail the payment attempt if the PaymentIntent transitions into `requires_action`
=item * mandate - Str - id of the mandate to be used for this payment
=item * mandate_data - HashRef - details about the Mandate to create
=item * off_session - Bool - indicate that the customer is not in your checkout flow
=item * payment_method - StripePaymentMethodId - id of PaymentMethod to attach to this PaymentIntent
=item * payment_method_options - HashRef - PaymentMethod-specific configuration for this PaymentIntent
=item * payment_method_types - ArrayRef[StripePaymentMethodType] - list of PaymentMethod types that this PaymentIntent is allowed to use
=item * receipt_email - Str - email address to send the receipt to
=item * return_url - Str - URL to redirect your customer back to
=item * save_payment_method - Bool - save the payment method to the customer
=item * setup_future_usage - Str - allow future payments with this PaymentIntent's PaymentMethod
=item * shipping - HashRef - shipping information for this PaymentIntent
=item * use_stripe_sdk - Bool - use manual confirmation and the iOS or Android SDKs to handle additional authentication steps
=back
Returns a L
$stripe->confirm_payment_intent(
payment_intent_id => $payment_intent_id,
);
=head2 capture_payment_intent
Capture the funds for the PaymentIntent
L
=over
=item * payment_intent_id - StripePaymentIntentId - id of PaymentIntent to capture - required
=item * amount_to_capture - Int - amount to capture from the PaymentIntent
=item * application_fee_amount - Int - application fee amount
=item * statement_descriptor - Str - descriptor for statement
=item * statement_descriptor_suffix - Str - suffix to be concatenated with the statement descriptor
=item * transfer_data - HashRef - parameters used to automatically create a Transfer when the payment succeeds
=back
Returns a L
$stripe->capture_payment_intent(
payment_intent_id => $payment_intent_id,
);
=head2 cancel_payment_intent
Cancel the PaymentIntent
L
=over
=item * payment_intent_id - StripePaymentIntentId - id of PaymentIntent to cancel - required
=item * cancellation_reason - StripeCancellationReason - reason for cancellation
=back
Returns a L
$stripe->cancel_payment_intent(
payment_intent_id => $payment_intent_id,
cancellation_reason => 'requested_by_customer',
);
=head2 list_payment_intents
Retrieve a list of PaymentIntents
L
=over
=item * customer - StripeCustomerId - return only PaymentIntents for the specified Customer id
=item * created - HashRef[Int] - created conditions to match
=item * ending_before - Str - ending before condition
=item * limit - Int - maximum number of objects to return
=item * starting_after - Str - starting after condition
=back
Returns a L object containing L objects.
$stripe->list_payment_intents(
customer => $customer_id,
type => 'card',
limit => 10,
);
=head1 RELEASE NOTES
=head2 Version 0.40
=head3 BREAKING CHANGES
=over
=item deprecate direct handling of PANs
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.
=item updating customer card by passing Customer object to post_customer()
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.
=item Plan objects now linked to Product objects
For Stripe API versions after 2018-02-15 L
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.
=back
=head3 DEPRECATION WARNING
=over
=item update 'card' to 'source' for Charge and Customer
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 L 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.
=item update 'account_balance' to 'balance' for Customer
While the API returns both 'account_balance' and 'balance' for earlier
versions, making the update backwards-compatible, Stripe API versions
after 2019-10-17 L 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.
=item use 'cancel_at_period_end' instead of 'at_period_end' for canceling Subscriptions
For Stripe API versions after 2018-08-23
L, 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.
=item update 'date' to 'created' for Invoice
While the API returns both 'date' and 'created' for earlier versions, making
the update backwards-compatible, Stripe API versions after 2019-03-14
L 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.
=item use 'auto_advance' instead of 'closed' for Invoice
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 L
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.
=back
=head3 BUG FIXES
=over
=item fix post_charge() arguments
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.
=item cleanup post_card()
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 L, and the code path
that appeared to be handling `Net::Stripe::Card` was actually unreachable
L. We removed the dead code
paths and made the conditional structure more explicit, per discussion in
L. We also added unit tests
for all calling forms, per L.
=item fix post_customer() arguments
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 L.
We have also updated the structure of the method so that we always create a
Net::Stripe::Customer object before posting L
and cleaned up and centralized Net::Stripe:Token coercion code.
=item default_card not updating in post_customer()
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 L 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.
=back
=head3 ENHANCEMENTS
=over
=item coerce old lists
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 C expects. This makes the SDK
compatible with the Stripe API back to the earliest documented API version
L.
=item encode card metdata in convert_to_form_fields()
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.
=item encode objects in convert_to_form_fields()
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.
=item remove manual serialization in _get_collections() and _get_with_args()
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 L 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.
=item add _get_all()
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.
=back
=head3 UPDATES
=over
=item update statement_description to statement_descriptor
The statement_description attribute is now statement_descriptor for
L and L. The API docs
L 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.
=item update unit tests for Charge->status
For Stripe API versions after 2015-02-18 L,
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.
=item add update_card()
This method allows updates to card address, expiration, metadata, etc for
existing customer cards.
=item update Token attributes
Added type and client_ip attributes for L.
=item allow capture of partial charge
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 L
of L objects for the charge.
=item add Source
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.
=item add balance for Customer
Added 'balance' attribute and arguments for Customer objects and methods.
=item add cancel_at_period_end for update_subscription()
Added 'cancel_at_period_end' argument update_subscription() and added
'cancel_at_period_end' to the POST stream for Subscription objects.
=item update Invoice
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.
=item add Product
Added a Product object. Also added 'product' attribute and argument for Plan
objects and methods.
=item add PaymentMethod and PaymentIntent
Added PaymentMethod and PaymentIntent objects and methods.
=back
=head1 SEE ALSO
L, L
=encoding UTF-8
=head1 AUTHORS
=over 4
=item *
Luke Closs
=item *
Rusty Conover
=back
=head1 CONTRIBUTORS
=for stopwords Andrew Solomon Brian Collins Devin M. Certas Dimitar Petrov Dylan Reinhold E. Choroba Florian Heyer Hermann Calabria Jonathan "Duke" Leto Luke Closs Mohammad S Anwar Olaf Alders Paul Cochrane Peter Scott Rusty Conover Sachin Sebastian Sherrard Burton Slobodan Mišković Tom Eliaz
=over 4
=item *
Andrew Solomon
=item *
Andrew Solomon
=item *
Brian Collins
=item *
Devin M. Certas
=item *
Dimitar Petrov
=item *
Dylan Reinhold
=item *
E. Choroba
=item *
Florian Heyer
=item *
Hermann Calabria
=item *
Jonathan "Duke" Leto
=item *
Luke Closs
=item *
Luke Closs
=item *
Mohammad S Anwar
=item *
Olaf Alders
=item *
Paul Cochrane
=item *
Peter Scott
=item *
Rusty Conover
=item *
Sachin Sebastian
=item *
Sherrard Burton <32931314+sherrardb@users.noreply.github.com>
=item *
Sherrard Burton
=item *
Slobodan Mišković
=item *
Tom Eliaz
=back
=head1 COPYRIGHT AND LICENSE
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.
=cut