View Source Stripe.PaymentLink (stripity_stripe v3.2.0)

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

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.

after_submit()
automatic_tax()

Configuration for automatic tax collection.

completed_sessions()

Configuration for the completed_sessions restriction type.

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.

end_behavior()

Defines how the subscription should behave when the user's free trial ends.

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.

payment_method_reuse_agreement()

Determines the display of payment method reuse agreement text in the UI. If set to hidden, it will hide legal text related to the reuse of a payment method.

phone_number_collection()

Controls phone number collection settings during checkout.

redirect()

Configuration when type=redirect.

rendering_options()
restrictions()

Settings that restrict the usage of a payment link.

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.

trial_settings()

Settings related to subscription trials.

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.

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

after_submit()

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

automatic_tax()

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

Configuration for automatic tax collection.

Link to this type

completed_sessions()

View Source 
@type completed_sessions() :: %{optional(:limit) => integer()}

Configuration for the completed_sessions restriction type.

Link to this type

consent_collection()

View Source 
@type consent_collection() :: %{
  optional(:payment_method_reuse_agreement) => payment_method_reuse_agreement(),
  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(:name) => binary(), optional(:value) => binary()}
Link to this type

custom_text()

View Source 
@type custom_text() :: %{
  optional(:after_submit) => after_submit() | binary(),
  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

end_behavior()

View Source 
@type end_behavior() :: %{
  optional(:missing_payment_method) => :cancel | :create_invoice | :pause
}

Defines how the subscription should behave when the user's free trial ends.

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(),
  optional(:transfer_group) => binary()
}

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

Link to this type

payment_method_reuse_agreement()

View Source 
@type payment_method_reuse_agreement() :: %{optional(:position) => :auto | :hidden}

Determines the display of payment method reuse agreement text in the UI. If set to hidden, it will hide legal text related to the reuse of a payment method.

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

restrictions()

View Source 
@type restrictions() :: %{optional(:completed_sessions) => completed_sessions()}

Settings that restrict the usage of a payment link.

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(),
  optional(:trial_settings) => trial_settings()
}

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(),
  inactive_message: binary() | nil,
  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(),
  restrictions: term() | nil,
  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.
  • inactive_message The custom message to be displayed to a customer when a payment link is no longer active.
  • 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
  • restrictions Settings that restrict the usage of a payment link.
  • 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 type

trial_settings()

View Source 
@type trial_settings() :: %{optional(:end_behavior) => end_behavior()}

Settings related to subscription trials.

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(:inactive_message) => 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(:restrictions) => restrictions(),
    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(:inactive_message) => binary() | 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(:restrictions) => restrictions() | 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}