NAME

Net::Stripe - API client for Stripe.com

VERSION

version 0.41

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

# ... and the API mirrors https://stripe.com/docs/api
# Charges: post_charge() get_charge() refund_charge() get_charges()
# Customer: post_customer()

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.

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 Net::Stripe::Constants::MIN_API_VERSION and 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.

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.

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 <https://stripe.com/docs/upgrades#api-changelog>.

OUT OF SCOPE VERSIONING

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!

METHODS

new PARAMHASH

This creates a new stripe API object. The following parameters are accepted:

api_key: This is required. You get this from your Stripe Account settings.
api_version: This is the value of the Stripe-Version header <https://stripe.com/docs/api/versioning> you wish to transmit for API calls.
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!
debug: You can set this to true to see extra debug info.
debug_network: You can set this to true to see the actual network requests.

ATTRIBUTES

api_base

Reader: api_base

Type: Str

Additional documentation: This is the base part of the URL for every request made

api_key

Reader: api_key

Type: Str

This attribute is required.

Additional documentation: You get this from your Stripe Account settings

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

debug

Reader: debug

Writer: debug

Type: Bool

Additional documentation: The debug flag

debug_network

Reader: debug_network

Writer: debug_network

Type: Bool

Additional documentation: The debug network request flag

force_api_version

Reader: force_api_version

Type: Bool

Additional documentation: Set this to true to bypass the safety checks for API version compatibility.

ua

Reader: ua

Type: Object

Additional documentation: The LWP::UserAgent that is used for requests

Balance Transaction Methods

get_balance_transaction

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

Charge Methods

post_charge

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

get_charge

Retrieve a charge.

https://stripe.com/docs/api#retrieve_charge

charge_id - Str - charge id to retrieve

Returns Net::Stripe::Charge.

$stripe->get_charge(charge_id => 'chargeid');

refund_charge

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

get_charges

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

capture_charge

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

Customer Methods

post_customer

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

list_subscriptions

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.

get_customer

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_customer

Delete a customer.

https://stripe.com/docs/api#delete_customer

customer - Net::Stripe::Customer or Str - the customer to delete

Returns a Net::Stripe::Customer object.

$stripe->delete_customer(customer => $customer);

get_customers

Returns a list of customers.

https://stripe.com/docs/api#list_customers

created - HashRef - created conditions, optional
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Customer objects.

$stripe->get_customers(limit => 7);

Card Methods

get_card

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

post_card

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

Returns a Net::Stripe::Card.

$stripe->post_card(customer => $customer, source => $token_id);

update_card

Update a card.

https://stripe.com/docs/api/cards/update#update_card

customer_id - StripeCustomerId
card_id - StripeCardId
card - HashRef

Returns a Net::Stripe::Card.

$stripe->update_card(
    customer_id => $customer_id,
    card_id => $card_id,
    card => {
        name => $new_name,
        metadata => {
            'account-number' => $new_account_nunmber,
        },
    },
);

get_cards

Returns a list of cards.

https://stripe.com/docs/api#list_cards

customer - Net::Stripe::Customer or Str
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Card objects.

$stripe->list_cards(customer => 'abcdec', limit => 10);

delete_card

Delete a card.

https://stripe.com/docs/api#delete_card

customer - Net::Stripe::Customer or Str
card - Net::Stripe::Card or Str

Returns a Net::Stripe::Card.

$stripe->delete_card(customer => $customer, card => $card);

Source Methods

create_source

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

get_source

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

Returns a Net::Stripe::Source

$stripe->get_source(
    source_id => $source_id,
);

update_source

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
amount - Int - amount associated with the source
metadata - HashRef - metadata for the source
mandate - HashRef - information about a mandate attached to the source
owner - HashRef - information about the owner of the payment instrument
source_order - HashRef - information about the items and shipping associated with the source

Returns a Net::Stripe::Source

$stripe->update_source(
    source_id => $source_id,
    owner => {
        email => $new_email,
        phone => $new_phone,
    },
);

attach_source

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

Returns a Net::Stripe::Source

$stripe->attach_source(
    customer_id => $customer_id,
    source_id => $source->id,
);

detach_source

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

Returns a Net::Stripe::Source

$stripe->detach_source(
    customer_id => $customer_id,
    source_id => $source->id,
);

list_sources

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

Subscription Methods

post_subscription

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
coupon - Str, optional
description - Str, optional
plan - Str, optional
quantity - Int, 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');

get_subscription

Returns a customer's subscription.

customer - Net::Stripe::Customer or Str

Returns a Net::Stripe::Subscription.

$stripe->get_subscription(customer => 'test123');

delete_subscription

Cancel a customer's subscription.

https://stripe.com/docs/api#cancel_subscription

customer - Net::Stripe::Customer or Str
subscription - Net::Stripe::Subscription or Str
at_period_end - Bool, optional

Returns a Net::Stripe::Subscription object.

$stripe->delete_subscription(customer => $customer, subscription => $subscription);

Token Methods

get_token

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

Product Methods

create_product

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
statement_descriptor - Str - descriptor for statement
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',
);

get_product

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

Returns a Net::Stripe::Product

$stripe->get_product(
    product_id => $product_id,
);

update_product

Update an existing Product

https://stripe.com/docs/api/products/update#update_product https://stripe.com/docs/api/service_products/update#update_service_product

product_id - StripeProductId|Str - id of product to retrieve - 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
images - ArrayRef[Str] - a list of image URLs
metadata - HashRef[Str] - metadata
name - Str - name of the product
package_dimensions - HashRef - package dimensions for shipping
shippable - Bool - whether the product is a shipped good
statement_descriptor - Str - descriptor for statement
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->update_product(
    product_id => $product_id,
    name => $new_name,
);

list_products

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
ending_before - Str - ending before condition
limit - Int - maximum number of objects to return
starting_after - Str - starting after condition

Returns a Net::Stripe::List object containing Net::Stripe::Product objects.

$stripe->list_products(
    limit => 5,
);

delete_product

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

Plan Methods

post_plan

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",
);

get_plan

Retrieves a plan.

plan_id - Str

Returns a Net::Stripe::Plan.

$stripe->get_plan(plan_id => 'plan123');

delete_plan

Delete a plan.

https://stripe.com/docs/api#delete_plan

plan_id - Net::Stripe::Plan or Str

Returns a Net::Stripe::Plan object.

$stripe->delete_plan(plan_id => $plan);

get_plans

Return a list of plans.

https://stripe.com/docs/api#list_plans

product - StripeProductId|Str - only return plans for the given product
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Plan objects.

$stripe->get_plans(limit => 10);

Coupon Methods

post_coupon

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
metadata - HashRef, 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,
);

get_coupon

Retrieve a coupon.

https://stripe.com/docs/api#retrieve_coupon

coupon_id - Str

Returns a Net::Stripe::Coupon object.

$stripe->get_coupon(coupon_id => 'id');

delete_coupon

Delete a coupon.

https://stripe.com/docs/api#delete_coupon

coupon_id - Str

Returns a Net::Stripe::Coupon.

$stripe->delete_coupon(coupon_id => 'coupon123');

get_coupons

ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Coupon objects.

$stripe->get_coupons(limit => 15);

Invoice Methods

post_invoice

Update an invoice.

invoice - Net::Stripe::Invoice, Str
application_fee - Int - optional
closed - Bool - optional
description - Str - optional
metadata - HashRef - optional

Returns a Net::Stripe::Invoice.

$stripe->post_invoice(invoice => $invoice, closed => 1)

get_invoice

invoice_id - Str

Returns a Net::Stripe::Invoice.

$stripe->get_invoice(invoice_id => 'testinvoice');

pay_invoice

invoice_id - Str

Returns a Net::Stripe::Invoice.

$stripe->pay_invoice(invoice_id => 'testinvoice');

get_invoices

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
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Invoice objects.

$stripe->get_invoices(limit => 10);

create_invoice

Create a new invoice.

https://stripe.com/docs/api#create_invoice

customer - Net::Stripe::Customer, Str
application_fee - Int - optional
description - Str - optional
metadata - HashRef - optional
subscription - Net::Stripe::Subscription or Str, optional

Returns a Net::Stripe::Invoice.

$stripe->create_invoice(customer => 'custid', description => 'test');

get_invoice

invoice_id - Str

Returns a Net::Stripe::Invoice.

$stripe->get_invoice(invoice_id => 'test');

get_upcominginvoice

customer, Net::Stripe::Customer or Str

Returns a Net::Stripe::Invoice.

$stripe->get_upcominginvoice(customer => $customer);

Invoice Item Methods

create_invoiceitem

Create an invoice item.

https://stripe.com/docs/api#create_invoiceitem

customer - Net::Stripe::Customer or Str
amount - Int
currency - Str
invoice - Net::Stripe::Invoice or Str, optional
subscription - Net::Stripe::Subscription or Str, optional
description - Str, optional
metadata - HashRef, optional

Returns a Net::Stripe::Invoiceitem object.

$stripe->create_invoiceitem(customer => 'test', amount => 500, currency => 'USD');

post_invoiceitem

Update an invoice item.

https://stripe.com/docs/api#create_invoiceitem

invoice_item - Net::Stripe::Invoiceitem or Str
amount - Int, optional
description - Str, optional
metadata - HashRef, optional

Returns a Net::Stripe::Invoiceitem.

$stripe->post_invoiceitem(invoice_item => 'itemid', amount => 750);

get_invoiceitem

Retrieve an invoice item.

invoice_item - Str

Returns a Net::Stripe::Invoiceitem.

$stripe->get_invoiceitem(invoice_item => 'testitemid');

delete_invoiceitem

Delete an invoice item.

invoice_item - Net::Stripe::Invoiceitem or Str

Returns a Net::Stripe::Invoiceitem.

$stripe->delete_invoiceitem(invoice_item => $invoice_item);

get_invoiceitems

customer - Net::Stripe::Customer or Str, optional
date - Int or HashRef, optional
ending_before - Str, optional
limit - Int, optional
starting_after - Str, optional

Returns a Net::Stripe::List object containing Net::Stripe::Invoiceitem objects.

$stripe->get_invoiceitems(customer => 'test', limit => 30);

Discount Methods

delete_customer_discount

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

Returns hashref of the form

{
  deleted => <bool>
}

Payment Method Methods

create_payment_method

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
metadata - HashRef[Str] - metadata
sepa_debit - HashRef - details about the SEPA debit bank account

Returns a Net::Stripe::PaymentMethod.

$stripe->create_payment_method(
    type => 'card',
    card => $token_id,
);

get_payment_method

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_payment_method

Update a PaymentMethod

https://stripe.com/docs/api/payment_methods/update#update_payment_method

payment_method_id - StripePaymentMethodId - id of PaymentMethod to update - required
billing_details - HashRef - billing information associated with the PaymentMethod
card - HashRef[Int] - card details to update
metadata - HashRef[Str] - metadata
sepa_debit - HashRef - details about the SEPA debit bank account

Returns a Net::Stripe::PaymentMethod

$stripe->update_payment_method(
    payment_method_id => $payment_method_id,
    metadata => $metadata,
);

list_payment_methods

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
ending_before - Str - ending before condition
limit - Int - maximum number of objects to return
starting_after - Str - starting after condition

Returns a Net::Stripe::List object containing Net::Stripe::PaymentMethod objects

$stripe->list_payment_methods(
    customer => $customer_id,
    type => 'card',
    limit => 10,
);

attach_payment_method

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

Returns a Net::Stripe::PaymentMethod

$stripe->attach_payment_method(
    payment_method_id => $payment_method_id,
    customer => $customer,
);

detach_payment_method

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

Returns a Net::Stripe::PaymentMethod.

$stripe->detach_payment_method(
    payment_method_id => $payment_method_id,
);

Payment Intent Methods

create_payment_intent

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
description - Str - description
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
metadata - HashRef[Str] - metadata
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 - Str - descriptor for statement
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',
);

get_payment_intent

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

Returns a Net::Stripe::PaymentIntent

$stripe->get_payment_intent(
    payment_intent_id => $payment_intent_id,
);

update_payment_intent

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
amount - Int - amount intended to be collected by this PaymentIntent - required
application_fee_amount - Int - the amount of the application fee
currency - Str - currency - required
customer - StripeCustomerId - id of Customer this PaymentIntent belongs to
description - Str - description
metadata - HashRef[Str] - metadata
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
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 - Str - descriptor for statement
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

Returns a Net::Stripe::PaymentIntent

$stripe->update_payment_intent(
    payment_intent_id => $payment_intent_id,
    description => 'Updated Description',
);

confirm_payment_intent

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
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
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
use_stripe_sdk - Bool - use manual confirmation and the iOS or Android SDKs to handle additional authentication steps

Returns a Net::Stripe::PaymentIntent

$stripe->confirm_payment_intent(
    payment_intent_id => $payment_intent_id,
);

capture_payment_intent

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
statement_descriptor - Str - descriptor for statement
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

Returns a Net::Stripe::PaymentIntent

$stripe->capture_payment_intent(
    payment_intent_id => $payment_intent_id,
);

cancel_payment_intent

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

Returns a Net::Stripe::PaymentIntent

$stripe->cancel_payment_intent(
    payment_intent_id => $payment_intent_id,
    cancellation_reason => 'requested_by_customer',
);

list_payment_intents

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
ending_before - Str - ending before condition
limit - Int - maximum number of objects to return
starting_after - Str - starting after condition

Returns a Net::Stripe::List object containing Net::Stripe::PaymentIntent objects.

$stripe->list_payment_intents(
    customer => $customer_id,
    type => 'card',
    limit => 10,
);

RELEASE NOTES

Version 0.40

BREAKING CHANGES

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.

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.

Plan objects now linked to Product objects

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.

DEPRECATION WARNING

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 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.
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 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.
use 'cancel_at_period_end' instead of 'at_period_end' for canceling Subscriptions: 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.
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 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.
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 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.

BUG FIXES

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.
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 #138, and the code path that appeared to be handling `Net::Stripe::Card` was actually unreachable #100. We removed the dead code paths and made the conditional structure more explicit, per discussion in #133. We also added unit tests for all calling forms, per #139.
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 #138. We have also updated the structure of the method so that we always create a Net::Stripe::Customer object before posting #148 and cleaned up and centralized Net::Stripe:Token coercion code.
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 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.

ENHANCEMENTS

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 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.
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.
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.
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 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.
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.

UPDATES

update statement_description to statement_descriptor: 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.
update unit tests for Charge->status: 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.
add update_card(): This method allows updates to card address, expiration, metadata, etc for existing customer cards.
update Token attributes: Added type and client_ip attributes for Net::Stripe::Token.
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 Net::Stripe::List of Net::Stripe::Refund objects for the charge.
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.
add balance for Customer: Added 'balance' attribute and arguments for Customer objects and methods.
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.
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.
add Product: Added a Product object. Also added 'product' attribute and argument for Plan objects and methods.
add PaymentMethod and PaymentIntent: Added PaymentMethod and PaymentIntent objects and methods.