Class: Stripe::APIResource

Inherits:
StripeObject show all
Includes:
Stripe::APIOperations::Request
Defined in:
lib/stripe/api_resource.rb

Direct Known Subclasses

Account, AccountLink, AccountSession, AlipayAccount, ApplePayDomain, ApplicationFee, ApplicationFeeRefund, Stripe::Apps::Secret, BalanceTransaction, BankAccount, Billing::Alert, Billing::CreditBalanceTransaction, Billing::CreditGrant, Billing::Meter, Billing::MeterEvent, Billing::MeterEventAdjustment, Billing::MeterEventSummary, BillingPortal::Configuration, BillingPortal::Session, Capability, Card, CashBalance, Charge, Checkout::Session, Climate::Order, Climate::Product, Climate::Supplier, ConfirmationToken, CountrySpec, Coupon, CreditNote, Customer, CustomerBalanceTransaction, CustomerCashBalanceTransaction, CustomerSession, Dispute, Entitlements::ActiveEntitlement, Entitlements::Feature, EphemeralKey, Event, ExchangeRate, File, FileLink, FinancialConnections::Account, FinancialConnections::Session, FinancialConnections::Transaction, Forwarding::Request, FundingInstructions, Identity::VerificationReport, Identity::VerificationSession, Invoice, InvoiceItem, InvoiceRenderingTemplate, Issuing::Authorization, Issuing::Card, Issuing::Cardholder, Issuing::Dispute, Issuing::PersonalizationDesign, Issuing::PhysicalBundle, Issuing::Token, Issuing::Transaction, LineItem, LoginLink, Mandate, PaymentIntent, PaymentLink, PaymentMethod, PaymentMethodConfiguration, PaymentMethodDomain, Payout, Person, Plan, Price, Product, ProductFeature, PromotionCode, Quote, Radar::EarlyFraudWarning, Radar::ValueList, Radar::ValueListItem, Refund, Reporting::ReportRun, Reporting::ReportType, Reversal, Review, SetupAttempt, SetupIntent, ShippingRate, Sigma::ScheduledQueryRun, SingletonAPIResource, Source, Subscription, SubscriptionItem, SubscriptionSchedule, Tax::Calculation, Tax::CalculationLineItem, Tax::Registration, Tax::Transaction, Tax::TransactionLineItem, TaxCode, TaxId, TaxRate, Terminal::Configuration, Terminal::ConnectionToken, Terminal::Location, Terminal::Reader, TestHelpers::TestClock, Token, Topup, Transfer, Treasury::CreditReversal, Treasury::DebitReversal, Treasury::FinancialAccount, Treasury::FinancialAccountFeatures, Treasury::InboundTransfer, Treasury::OutboundPayment, Treasury::OutboundTransfer, Treasury::ReceivedCredit, Treasury::ReceivedDebit, Treasury::Transaction, Treasury::TransactionEntry, UsageRecord, V2::Billing::MeterEvent, V2::Billing::MeterEventAdjustment, V2::Billing::MeterEventSession, V2::Event, V2::EventDestination, WebhookEndpoint

Constant Summary collapse

OBJECT_NAME =

TODO: (major) Remove OBJECT_NAME and stop using const_get here This is a workaround to avoid breaking users who have defined their own APIResource subclasses with a custom OBJECT_NAME. We should never fallback on this case otherwise.

""

Constants inherited from StripeObject

StripeObject::RESERVED_FIELD_NAMES

Instance Attribute Summary collapse

Attributes inherited from StripeObject

#last_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Stripe::APIOperations::Request

included

Methods inherited from StripeObject

#==, #[], #[]=, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #each, #eql?, #hash, #initialize, #inspect, #keys, #marshal_dump, #marshal_load, protected_fields, #serialize_params, #to_hash, #to_json, #to_s, #update_attributes, #values

Constructor Details

This class inherits a constructor from Stripe::StripeObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Stripe::StripeObject

Instance Attribute Details

#save_with_parent ⇒ Object

A flag that can be set a behavior that will cause this resource to be encoded and sent up along with an update of its parent resource. This is usually not desirable because resources are updated individually on their own endpoints, but there are certain cases, replacing a customer’s source for example, where this is allowed.



12
13
14
 
# File 'lib/stripe/api_resource.rb', line 12

def save_with_parent
  @save_with_parent
end

Class Method Details

.class_name ⇒ Object 



23
24
25
 
# File 'lib/stripe/api_resource.rb', line 23

def self.class_name
  name.split("::")[-1]
end

.custom_method(name, http_verb:, http_path: nil) ⇒ Object

Adds a custom method to a resource class. This is used to add support for non-CRUDL API requests, e.g. capturing charges. custom_method takes the following parameters:

  • name: the name of the custom method to create (as a symbol)

  • http_verb: the HTTP verb for the API request (:get, :post, or :delete)

  • http_path: the path to append to the resource’s URL. If not provided,

    the name is used as the path

For example, this call:

custom_method :capture, http_verb: post

adds a ‘capture` class method to the resource class that, when called, will send a POST request to `/v1/<object_name>/capture`.



80
81
82
 
# File 'lib/stripe/api_resource.rb', line 80

def self.custom_method(name, http_verb:, http_path: nil)
  Util.custom_method self, self, name, http_verb, http_path
end

.object_name ⇒ Object 



19
20
21
 
# File 'lib/stripe/api_resource.rb', line 19

def self.object_name
  const_get(:OBJECT_NAME)
end

.resource_url ⇒ Object 



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/stripe/api_resource.rb', line 27

def self.resource_url
  if name.include?("Stripe::V2")
    raise NotImplementedError,
          "V2 resources do not have a defined URL. Please use the StripeClient " \
          "to make V2 requests"
  end

  if self == APIResource
    raise NotImplementedError,
          "APIResource is an abstract class. You should perform actions " \
          "on its subclasses (Charge, Customer, etc.)"
  end
  # Namespaces are separated in object names with periods (.) and in URLs
  # with forward slashes (/), so replace the former with the latter.
  "/v1/#{object_name.downcase.tr('.', '/')}s"
end

.retrieve(id, opts = {}) ⇒ Object 



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/stripe/api_resource.rb', line 111

def self.retrieve(id, opts = {})
  if name.include?("Stripe::V2")
    raise NotImplementedError,
          "It is not possible to retrieve v2 objects on the resource. Please use the StripeClient instead."
  end

  opts = Util.normalize_opts(opts)
  instance = new(id, opts)
  instance.refresh
end

.save_nested_resource(name) ⇒ Object

A metaprogramming call that specifies that a field of a resource can be its own type of API resource (say a nested card under an account for example), and if that resource is set, it should be transmitted to the API on a create or update. Doing so is not the default behavior because API resources should normally be persisted on their own RESTful endpoints.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/stripe/api_resource.rb', line 50

def self.save_nested_resource(name)
  define_method(:"#{name}=") do |value|
    super(value)

    # The parent setter will perform certain useful operations like
    # converting to an APIResource if appropriate. Refresh our argument
    # value to whatever it mutated to.
    value = send(name)

    # Note that the value may be subresource, but could also be a scalar
    # (like a tokenized card's ID for example), so we check the type before
    # setting #save_with_parent here.
    value.save_with_parent = true if value.is_a?(APIResource)

    value
  end
end

Instance Method Details

#refresh ⇒ Object 



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/stripe/api_resource.rb', line 95

def refresh
  if self.class.name.include?("Stripe::V2")
    raise NotImplementedError,
          "It is not possible to refresh v2 objects. Please retrieve the object using the StripeClient instead."
  end

  @obj = @requestor.execute_request_initialize_from(:get, resource_url, :api, self, params: @retrieve_params)
  initialize_from(
    @obj.last_response.data,
    @obj.instance_variable_get(:@opts),
    @obj.last_response,
    api_mode: :v1,
    requestor: @requestor
  )
end

#request_stripe_object(method:, path:, params:, base_address: :api, opts: {}) ⇒ Object 



122
123
124
125
 
# File 'lib/stripe/api_resource.rb', line 122

def request_stripe_object(method:, path:, params:, base_address: :api, opts: {})
  APIRequestor.active_requestor.execute_request_initialize_from(method, path, base_address, self,
                                                                params: params, opts: opts)
end

#resource_url ⇒ Object 



84
85
86
87
88
89
90
91
92
93
 
# File 'lib/stripe/api_resource.rb', line 84

def resource_url
  unless (id = self["id"])
    raise InvalidRequestError.new(
      "Could not determine which URL to request: #{self.class} instance " \
      "has invalid ID: #{id.inspect}",
      "id"
    )
  end
  "#{self.class.resource_url}/#{CGI.escape(id)}"
end