The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Net::Stripe - API client for Stripe.com

VERSION

version 0.40_002

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.

WARNING

This SDK is "version agnostic" of the Stripe API https://github.com/lukec/stripe-perl/issues/80 and at the time of this release Stripe has some major changes afoot https://github.com/lukec/stripe-perl/issues/115

If you're considering using this please click "Watch" on this github project https://github.com/lukec/stripe-perl/ where discussion on these topics takes place.

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.

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

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

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

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

  • 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

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

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

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

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

Returns a Net::Stripe::Customer object.

$stripe->post_subscription(customer => $customer, plan => 'testplan');

get_subscription

Returns a customer's subscription.

Returns a Net::Stripe::Subscription.

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

delete_subscription

Cancel a customer's subscription.

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

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

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

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

  • 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

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

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

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.

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

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

Returns hashref of the form

{
  deleted => <bool>
}

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.

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

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

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.

add update_card()

This method allows updates to card address, expiration, metadata, etc for existing customer cards.

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.

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.

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.

SEE ALSO

https://stripe.com, https://stripe.com/docs/api

AUTHORS

  • Luke Closs

  • Rusty Conover

CONTRIBUTORS

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

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.