Stripe.Request (stripity_stripe v2.17.3) View Source

A module for working with requests to the Stripe API.

Requests are composed in a functional manner. The request does not happen until it is configured and passed to make_request/1.

Currently encompasses only requests to the normal Stripe API. The OAuth endpoint is not yet supported.

Generally intended to be used internally, but can also be used by end-users to work around missing endpoints (if any).

At a minimum, a request must have the endpoint and method specified to be valid.

Link to this section Summary

Functions

Specify that a given path in the parameters should be cast to a simple ID.

Specify that a given set of parameters should be cast to a simple ID.

Normalise the argument to a simple Stripe ID.

Executes the request and returns the response for file uploads

Executes the request and returns the response.

Prefixes all :expand values provided in opts with the given prefix.

Specifies an endpoint for the request.

Specifies a method to use for the request.

Specify a single param to be included in the request.

Specifies the parameters to be used for the request.

Link to this section Types

Specs

error_code() :: :endpoint_fun_invalid_result | :invalid_endpoint

Specs

t() :: %Stripe.Request{
  cast_to_id: MapSet.t(),
  endpoint: String.t() | nil,
  headers: map() | nil,
  method: Stripe.API.method() | nil,
  opts: Keyword.t() | nil,
  params: map()
}

Link to this section Functions

Link to this function

cast_path_to_id(request, new_cast_to_id)

View Source

Specs

cast_path_to_id(t(), [atom()]) :: t()

Specify that a given path in the parameters should be cast to a simple ID.

Acts similar to cast_to_id/2 but specifies only one parameter to be cast, by specifying its path (as in the Access protocol). Used to cast nested objects to their IDs.

Link to this function

cast_to_id(request, new_cast_to_id)

View Source

Specs

cast_to_id(t(), [atom()]) :: t()

Specify that a given set of parameters should be cast to a simple ID.

Sometimes, it may be convenient to allow end-users to pass in structs (say, the card to charge) but the API requires only the ID of the object. This function will ensure that before the request is made, the parameters specified here will be cast to IDs – if the value of a parameter is a struct with an :id field, the value of that field will replace the struct in the parameter list.

If the function is called multiple times, the set of parameters to cast to ID is merged between the multiple calls.

Specs

get_id!(Stripe.id() | struct()) :: Stripe.id()

Normalise the argument to a simple Stripe ID.

Actively extracts the ID, given a struct with an :id field, or returns the binary if one is passed in.

Useful for eagerly getting the ID of an object passed in, for example when computing the endpoint to use:

def capture(id, params, opts) do
  new_request(opts)
  |> put_endpoint(@plural_endpoint <> "/#{get_id!(id)}/capture")
  ...
Link to this function

make_file_upload_request(request)

View Source

Specs

make_file_upload_request(t()) :: {:ok, struct()} | {:error, Stripe.Error.t()}

Executes the request and returns the response for file uploads

Specs

make_request(t()) :: {:ok, struct()} | {:error, Stripe.Error.t()}

Executes the request and returns the response.

Link to this function

new_request(opts \\ [], headers \\ %{})

View Source

Specs

new_request(Stripe.options(), map()) :: t()

Creates a new request.

Optionally accepts options for the request, such as using a specific API key. See t:Stripe.options for details.

Link to this function

prefix_expansions(request)

View Source

Specs

prefix_expansions(t()) :: t()

Prefixes all :expand values provided in opts with the given prefix.

When using object expansion on a list function for a resource, the values must be prefixed with data.. This is required because the stripe api nests the returned objects within data: {}.

For all create, update, cancel and retrieve functions this is not required.

opts = [expand: ["balance_transaction"]]
request = prefix_expansions(%Request{opts: opts})

request.opts == ["data.balance_transaction"]
Link to this function

put_endpoint(request, endpoint)

View Source

Specs

put_endpoint(t(), String.t()) :: t()

Specifies an endpoint for the request.

The endpoint should not include the v1 prefix or an initial slash, for example put_endpoint(request, "charges").

The endpoint can be a binary or a function which takes the parameters of the query and returns an endpoint. The function is not evaluated until just before the request is made so the actual parameters can be specified after the endpoint.

Link to this function

put_method(request, method)

View Source

Specs

put_method(t(), Stripe.API.method()) :: t()

Specifies a method to use for the request.

Accepts any of the standard HTTP methods as atoms, that is :get, :post, :put, :patch or :delete.

Link to this function

put_param(request, key, value)

View Source

Specs

put_param(t(), atom(), any()) :: t()

Specify a single param to be included in the request.

Link to this function

put_params(request, new_params)

View Source

Specs

put_params(t(), map()) :: t()

Specifies the parameters to be used for the request.

If the request is a POST request, these are encoded in the request body. Otherwise, they are encoded in the URL.

Calling this function multiple times will merge, not replace, the params currently specified.