stripity_stripe
v3.1.1

View Source Stripe.PaymentLink (stripity_stripe v3.1.1)

A payment link is a shareable URL that will take your customers to a hosted payment page. A payment link can be shared and used multiple times.

When a customer opens a payment link it will open a new checkout session to render the payment page. You can use checkout session events to track payments through payment links.

Related guide: Payment Links API

Link to this section Summary

Types

adjustable_quantity()

When set, provides configuration for this item’s quantity to be adjusted by the customer during checkout.

after_completion()

Behavior after the purchase is complete.

automatic_tax()

Configuration for automatic tax collection.

consent_collection()

Configure fields to gather active consent from customers.

custom_fields()
custom_text()

Display additional text for your customers using custom text.

dropdown()

Configuration for type=dropdown fields.

hosted_confirmation()

Configuration when type=hosted_confirmation.

invoice_creation()

Generate a post-purchase Invoice for one-time payments.

invoice_data()

Invoice PDF configuration.

label()

The label for the field, displayed to the customer.

line_items()
numeric()

Configuration for type=numeric fields.

options()
payment_intent_data()

A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.

phone_number_collection()

Controls phone number collection settings during checkout.

redirect()

Configuration when type=redirect.

rendering_options()
shipping_address()
shipping_address_collection()

Configuration for collecting the customer's shipping address.

shipping_options()
submit()
subscription_data()

When creating a subscription, the specified configuration data will be used. There must be at least one line item with a recurring price to use subscription_data.

t()

The payment_link type.

tax_id_collection()

Controls tax ID collection during checkout.

terms_of_service_acceptance()
text()

Configuration for type=text fields.

transfer_data()

The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.

Functions

create(params \\ %{}, opts \\ [])

Creates a payment link.

list(params \\ %{}, opts \\ [])

Returns a list of your payment links.

list_line_items(payment_link, params \\ %{}, opts \\ [])

When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

retrieve(payment_link, params \\ %{}, opts \\ [])

Retrieve a payment link.

update(payment_link, params \\ %{}, opts \\ [])

Updates a payment link.

Link to this section Types

Link to this type

adjustable_quantity()

View Source 
@type adjustable_quantity() :: %{
  optional(:enabled) => boolean(),
  optional(:maximum) => integer(),
  optional(:minimum) => integer()
}

When set, provides configuration for this item’s quantity to be adjusted by the customer during checkout.

Link to this type

after_completion()

View Source 
@type after_completion() :: %{
  optional(:hosted_confirmation) => hosted_confirmation(),
  optional(:redirect) => redirect(),
  optional(:type) => :hosted_confirmation | :redirect
}

Behavior after the purchase is complete.

Link to this type

automatic_tax()

View Source 
@type automatic_tax() :: %{optional(:enabled) => boolean()}

Configuration for automatic tax collection.

Link to this type

consent_collection()

View Source 
@type consent_collection() :: %{
  optional(:promotions) => :auto | :none,
  optional(:terms_of_service) => :none | :required
}

Configure fields to gather active consent from customers.

Link to this type

custom_fields()

View Source 
@type custom_fields() :: %{
  optional(:dropdown) => dropdown(),
  optional(:key) => binary(),
  optional(:label) => label(),
  optional(:numeric) => numeric(),
  optional(:optional) => boolean(),
  optional(:text) => text(),
  optional(:type) => :dropdown | :numeric | :text
}
Link to this type

custom_text()

View Source 
@type custom_text() :: %{
  optional(:shipping_address) => shipping_address() | binary(),
  optional(:submit) => submit() | binary(),
  optional(:terms_of_service_acceptance) =>
    terms_of_service_acceptance() | binary()
}

Display additional text for your customers using custom text.

Link to this type

dropdown()

View Source 
@type dropdown() :: %{optional(:options) => [options()]}

Configuration for type=dropdown fields.

Link to this type

hosted_confirmation()

View Source 
@type hosted_confirmation() :: %{optional(:custom_message) => binary()}

Configuration when type=hosted_confirmation.

Link to this type

invoice_creation()

View Source 
@type invoice_creation() :: %{
  optional(:enabled) => boolean(),
  optional(:invoice_data) => invoice_data()
}

Generate a post-purchase Invoice for one-time payments.

Link to this type

invoice_data()

View Source 
@type invoice_data() :: %{
  optional(:account_tax_ids) => [binary()] | binary(),
  optional(:custom_fields) => [custom_fields()] | binary(),
  optional(:description) => binary(),
  optional(:footer) => binary(),
  optional(:metadata) => %{optional(binary()) => binary()} | binary(),
  optional(:rendering_options) => rendering_options() | binary()
}

Invoice PDF configuration.

Link to this type

label()

View Source 
@type label() :: %{optional(:custom) => binary(), optional(:type) => :custom}

The label for the field, displayed to the customer.

Link to this type

line_items()

View Source 
@type line_items() :: %{
  optional(:adjustable_quantity) => adjustable_quantity(),
  optional(:price) => binary(),
  optional(:quantity) => integer()
}
Link to this type

numeric()

View Source 
@type numeric() :: %{
  optional(:maximum_length) => integer(),
  optional(:minimum_length) => integer()
}

Configuration for type=numeric fields.

Link to this type

options()

View Source 
@type options() :: %{optional(:label) => binary(), optional(:value) => binary()}
Link to this type

payment_intent_data()

View Source 
@type payment_intent_data() :: %{
  optional(:capture_method) => :automatic | :automatic_async | :manual,
  optional(:description) => binary(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:setup_future_usage) => :off_session | :on_session,
  optional(:statement_descriptor) => binary(),
  optional(:statement_descriptor_suffix) => binary()
}

A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.

Link to this type

phone_number_collection()

View Source 
@type phone_number_collection() :: %{optional(:enabled) => boolean()}

Controls phone number collection settings during checkout.

We recommend that you review your privacy policy and check with your legal contacts.

Link to this type

redirect()

View Source 
@type redirect() :: %{optional(:url) => binary()}

Configuration when type=redirect.

Link to this type

rendering_options()

View Source 
@type rendering_options() :: %{
  optional(:amount_tax_display) => :exclude_tax | :include_inclusive_tax
}
Link to this type

shipping_address()

View Source 
@type shipping_address() :: %{optional(:message) => binary()}
Link to this type

shipping_address_collection()

View Source 
@type shipping_address_collection() :: %{
  optional(:allowed_countries) => [
    :AC
    | :AD
    | :AE
    | :AF
    | :AG
    | :AI
    | :AL
    | :AM
    | :AO
    | :AQ
    | :AR
    | :AT
    | :AU
    | :AW
    | :AX
    | :AZ
    | :BA
    | :BB
    | :BD
    | :BE
    | :BF
    | :BG
    | :BH
    | :BI
    | :BJ
    | :BL
    | :BM
    | :BN
    | :BO
    | :BQ
    | :BR
    | :BS
    | :BT
    | :BV
    | :BW
    | :BY
    | :BZ
    | :CA
    | :CD
    | :CF
    | :CG
    | :CH
    | :CI
    | :CK
    | :CL
    | :CM
    | :CN
    | :CO
    | :CR
    | :CV
    | :CW
    | :CY
    | :CZ
    | :DE
    | :DJ
    | :DK
    | :DM
    | :DO
    | :DZ
    | :EC
    | :EE
    | :EG
    | :EH
    | :ER
    | :ES
    | :ET
    | :FI
    | :FJ
    | :FK
    | :FO
    | :FR
    | :GA
    | :GB
    | :GD
    | :GE
    | :GF
    | :GG
    | :GH
    | :GI
    | :GL
    | :GM
    | :GN
    | :GP
    | :GQ
    | :GR
    | :GS
    | :GT
    | :GU
    | :GW
    | :GY
    | :HK
    | :HN
    | :HR
    | :HT
    | :HU
    | :ID
    | :IE
    | :IL
    | :IM
    | :IN
    | :IO
    | :IQ
    | :IS
    | :IT
    | :JE
    | :JM
    | :JO
    | :JP
    | :KE
    | :KG
    | :KH
    | :KI
    | :KM
    | :KN
    | :KR
    | :KW
    | :KY
    | :KZ
    | :LA
    | :LB
    | :LC
    | :LI
    | :LK
    | :LR
    | :LS
    | :LT
    | :LU
    | :LV
    | :LY
    | :MA
    | :MC
    | :MD
    | :ME
    | :MF
    | :MG
    | :MK
    | :ML
    | :MM
    | :MN
    | :MO
    | :MQ
    | :MR
    | :MS
    | :MT
    | :MU
    | :MV
    | :MW
    | :MX
    | :MY
    | :MZ
    | :NA
    | :NC
    | :NE
    | :NG
    | :NI
    | :NL
    | :NO
    | :NP
    | :NR
    | :NU
    | :NZ
    | :OM
    | :PA
    | :PE
    | :PF
    | :PG
    | :PH
    | :PK
    | :PL
    | :PM
    | :PN
    | :PR
    | :PS
    | :PT
    | :PY
    | :QA
    | :RE
    | :RO
    | :RS
    | :RU
    | :RW
    | :SA
    | :SB
    | :SC
    | :SE
    | :SG
    | :SH
    | :SI
    | :SJ
    | :SK
    | :SL
    | :SM
    | :SN
    | :SO
    | :SR
    | :SS
    | :ST
    | :SV
    | :SX
    | :SZ
    | :TA
    | :TC
    | :TD
    | :TF
    | :TG
    | :TH
    | :TJ
    | :TK
    | :TL
    | :TM
    | :TN
    | :TO
    | :TR
    | :TT
    | :TV
    | :TW
    | :TZ
    | :UA
    | :UG
    | :US
    | :UY
    | :UZ
    | :VA
    | :VC
    | :VE
    | :VG
    | :VN
    | :VU
    | :WF
    | :WS
    | :XK
    | :YE
    | :YT
    | :ZA
    | :ZM
    | :ZW
    | :ZZ
  ]
}

Configuration for collecting the customer's shipping address.

Link to this type

shipping_options()

View Source 
@type shipping_options() :: %{optional(:shipping_rate) => binary()}
Link to this type

submit()

View Source 
@type submit() :: %{optional(:message) => binary()}
Link to this type

subscription_data()

View Source 
@type subscription_data() :: %{
  optional(:description) => binary(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:trial_period_days) => integer()
}

When creating a subscription, the specified configuration data will be used. There must be at least one line item with a recurring price to use subscription_data.

Link to this type

t()

View Source 
@type t() :: %Stripe.PaymentLink{
  active: boolean(),
  after_completion: term(),
  allow_promotion_codes: boolean(),
  application: (binary() | term() | term()) | nil,
  application_fee_amount: integer() | nil,
  application_fee_percent: term() | nil,
  automatic_tax: term(),
  billing_address_collection: binary(),
  consent_collection: term() | nil,
  currency: binary(),
  custom_fields: term(),
  custom_text: term(),
  customer_creation: binary(),
  id: binary(),
  invoice_creation: term() | nil,
  line_items: term(),
  livemode: boolean(),
  metadata: term(),
  object: binary(),
  on_behalf_of: (binary() | Stripe.Account.t()) | nil,
  payment_intent_data: term() | nil,
  payment_method_collection: binary(),
  payment_method_types: term() | nil,
  phone_number_collection: term(),
  shipping_address_collection: term() | nil,
  shipping_options: term(),
  submit_type: binary(),
  subscription_data: term() | nil,
  tax_id_collection: term(),
  transfer_data: term() | nil,
  url: binary()
}

The payment_link type.

  • active Whether the payment link's url is active. If false, customers visiting the URL will be shown a page saying that the link has been deactivated.
  • after_completion
  • allow_promotion_codes Whether user redeemable promotion codes are enabled.
  • application The ID of the Connect application that created the Payment Link.
  • application_fee_amount The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner's Stripe account.
  • application_fee_percent This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.
  • automatic_tax
  • billing_address_collection Configuration for collecting the customer's billing address.
  • consent_collection When set, provides configuration to gather active consent from customers.
  • currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
  • custom_fields Collect additional information from your customer using custom fields. Up to 2 fields are supported.
  • custom_text
  • customer_creation Configuration for Customer creation during checkout.
  • id Unique identifier for the object.
  • invoice_creation Configuration for creating invoice for payment mode payment links.
  • line_items The line items representing what is being sold.
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  • object String representing the object's type. Objects of the same type share the same value.
  • on_behalf_of The account on behalf of which to charge. See the Connect documentation for details.
  • payment_intent_data Indicates the parameters to be passed to PaymentIntent creation during checkout.
  • payment_method_collection Configuration for collecting a payment method during checkout.
  • payment_method_types The list of payment method types that customers can use. When null, Stripe will dynamically show relevant payment methods you've enabled in your payment method settings.
  • phone_number_collection
  • shipping_address_collection Configuration for collecting the customer's shipping address.
  • shipping_options The shipping rate options applied to the session.
  • submit_type Indicates the type of transaction being performed which customizes relevant text on the page, such as the submit button.
  • subscription_data When creating a subscription, the specified configuration data will be used. There must be at least one line item with a recurring price to use subscription_data.
  • tax_id_collection
  • transfer_data The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.
  • url The public URL that can be shared with customers.
Link to this type

tax_id_collection()

View Source 
@type tax_id_collection() :: %{optional(:enabled) => boolean()}

Controls tax ID collection during checkout.

Link to this type

terms_of_service_acceptance()

View Source 
@type terms_of_service_acceptance() :: %{optional(:message) => binary()}
Link to this type

text()

View Source 
@type text() :: %{
  optional(:maximum_length) => integer(),
  optional(:minimum_length) => integer()
}

Configuration for type=text fields.

Link to this type

transfer_data()

View Source 
@type transfer_data() :: %{
  optional(:amount) => integer(),
  optional(:destination) => binary()
}

The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.

Link to this section Functions

Link to this function

create(params \\ %{}, opts \\ [])

View Source 
@spec create(
  params :: %{
    optional(:after_completion) => after_completion(),
    optional(:allow_promotion_codes) => boolean(),
    optional(:application_fee_amount) => integer(),
    optional(:application_fee_percent) => number(),
    optional(:automatic_tax) => automatic_tax(),
    optional(:billing_address_collection) => :auto | :required,
    optional(:consent_collection) => consent_collection(),
    optional(:currency) => binary(),
    optional(:custom_fields) => [custom_fields()],
    optional(:custom_text) => custom_text(),
    optional(:customer_creation) => :always | :if_required,
    optional(:expand) => [binary()],
    optional(:invoice_creation) => invoice_creation(),
    optional(:line_items) => [line_items()],
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:on_behalf_of) => binary(),
    optional(:payment_intent_data) => payment_intent_data(),
    optional(:payment_method_collection) => :always | :if_required,
    optional(:payment_method_types) => [
      :affirm
      | :afterpay_clearpay
      | :alipay
      | :au_becs_debit
      | :bacs_debit
      | :bancontact
      | :blik
      | :boleto
      | :card
      | :cashapp
      | :eps
      | :fpx
      | :giropay
      | :grabpay
      | :ideal
      | :klarna
      | :konbini
      | :link
      | :oxxo
      | :p24
      | :paynow
      | :paypal
      | :pix
      | :promptpay
      | :sepa_debit
      | :sofort
      | :us_bank_account
      | :wechat_pay
    ],
    optional(:phone_number_collection) => phone_number_collection(),
    optional(:shipping_address_collection) => shipping_address_collection(),
    optional(:shipping_options) => [shipping_options()],
    optional(:submit_type) => :auto | :book | :donate | :pay,
    optional(:subscription_data) => subscription_data(),
    optional(:tax_id_collection) => tax_id_collection(),
    optional(:transfer_data) => transfer_data()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates a payment link.

Details

  • Method: post
  • Path: /v1/payment_links
Link to this function

list(params \\ %{}, opts \\ [])

View Source 
@spec list(
  params :: %{
    optional(:active) => boolean(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of your payment links.

Details

  • Method: get
  • Path: /v1/payment_links
Link to this function

list_line_items(payment_link, params \\ %{}, opts \\ [])

View Source 
@spec list_line_items(
  payment_link :: binary(),
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(Stripe.Item.t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Details

  • Method: get
  • Path: /v1/payment_links/{payment_link}/line_items
Link to this function

retrieve(payment_link, params \\ %{}, opts \\ [])

View Source 
@spec retrieve(
  payment_link :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieve a payment link.

Details

  • Method: get
  • Path: /v1/payment_links/{payment_link}
Link to this function

update(payment_link, params \\ %{}, opts \\ [])

View Source 
@spec update(
  payment_link :: binary(),
  params :: %{
    optional(:active) => boolean(),
    optional(:after_completion) => after_completion(),
    optional(:allow_promotion_codes) => boolean(),
    optional(:automatic_tax) => automatic_tax(),
    optional(:billing_address_collection) => :auto | :required,
    optional(:custom_fields) => [custom_fields()] | binary(),
    optional(:custom_text) => custom_text(),
    optional(:customer_creation) => :always | :if_required,
    optional(:expand) => [binary()],
    optional(:invoice_creation) => invoice_creation(),
    optional(:line_items) => [line_items()],
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:payment_intent_data) => payment_intent_data(),
    optional(:payment_method_collection) => :always | :if_required,
    optional(:payment_method_types) =>
      [
        :affirm
        | :afterpay_clearpay
        | :alipay
        | :au_becs_debit
        | :bacs_debit
        | :bancontact
        | :blik
        | :boleto
        | :card
        | :cashapp
        | :eps
        | :fpx
        | :giropay
        | :grabpay
        | :ideal
        | :klarna
        | :konbini
        | :link
        | :oxxo
        | :p24
        | :paynow
        | :paypal
        | :pix
        | :promptpay
        | :sepa_debit
        | :sofort
        | :us_bank_account
        | :wechat_pay
      ]
      | binary(),
    optional(:shipping_address_collection) =>
      shipping_address_collection() | binary(),
    optional(:subscription_data) => subscription_data()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates a payment link.

Details

  • Method: post
  • Path: /v1/payment_links/{payment_link}