Class SetupIntent

All Implemented Interfaces:
HasId, MetadataStore<SetupIntent>, StripeActiveObject, StripeObjectInterface

public class SetupIntent extends ApiResource implements HasId, MetadataStore<SetupIntent>
A SetupIntent guides you through the process of setting up and saving a customer's payment credentials for future payments. For example, you can use a SetupIntent to set up and save your customer's card without immediately collecting a payment. Later, you can use PaymentIntents to drive the payment flow.

Create a SetupIntent when you're ready to collect your customer's payment credentials. Don't maintain long-lived, unconfirmed SetupIntents because they might not be valid. The SetupIntent transitions through multiple statuses as it guides you through the setup process.

Successful SetupIntents result in payment credentials that are optimized for future payments. For example, cardholders in certain regions might need to be run through Strong Customer Authentication during payment method collection to streamline later off-session payments. If you use the SetupIntent with a Customer, it automatically attaches the resulting payment method to that Customer after successful setup. We recommend using SetupIntents or setup_future_usage on PaymentIntents to save payment methods to prevent saving invalid or unoptimized payment methods.

By using SetupIntents, you can reduce friction for your customers, even as regulations change over time.

Related guide: Setup Intents API

  • Constructor Details

    • SetupIntent

      public SetupIntent()
  • Method Details

    • getApplication

      public String getApplication()
      Get ID of expandable application object.
    • setApplication

      public void setApplication(String id)
    • getApplicationObject

      public Application getApplicationObject()
      Get expanded application.
    • setApplicationObject

      public void setApplicationObject(Application expandableObject)
    • getCustomer

      public String getCustomer()
      Get ID of expandable customer object.
    • setCustomer

      public void setCustomer(String id)
    • getCustomerObject

      public Customer getCustomerObject()
      Get expanded customer.
    • setCustomerObject

      public void setCustomerObject(Customer expandableObject)
    • getLatestAttempt

      public String getLatestAttempt()
      Get ID of expandable latestAttempt object.
    • setLatestAttempt

      public void setLatestAttempt(String id)
    • getLatestAttemptObject

      public SetupAttempt getLatestAttemptObject()
      Get expanded latestAttempt.
    • setLatestAttemptObject

      public void setLatestAttemptObject(SetupAttempt expandableObject)
    • getMandate

      public String getMandate()
      Get ID of expandable mandate object.
    • setMandate

      public void setMandate(String id)
    • getMandateObject

      public Mandate getMandateObject()
      Get expanded mandate.
    • setMandateObject

      public void setMandateObject(Mandate expandableObject)
    • getOnBehalfOf

      public String getOnBehalfOf()
      Get ID of expandable onBehalfOf object.
    • setOnBehalfOf

      public void setOnBehalfOf(String id)
    • getOnBehalfOfObject

      public Account getOnBehalfOfObject()
      Get expanded onBehalfOf.
    • setOnBehalfOfObject

      public void setOnBehalfOfObject(Account expandableObject)
    • getPaymentMethod

      public String getPaymentMethod()
      Get ID of expandable paymentMethod object.
    • setPaymentMethod

      public void setPaymentMethod(String id)
    • getPaymentMethodObject

      public PaymentMethod getPaymentMethodObject()
      Get expanded paymentMethod.
    • setPaymentMethodObject

      public void setPaymentMethodObject(PaymentMethod expandableObject)
    • getSingleUseMandate

      public String getSingleUseMandate()
      Get ID of expandable singleUseMandate object.
    • setSingleUseMandate

      public void setSingleUseMandate(String id)
    • getSingleUseMandateObject

      public Mandate getSingleUseMandateObject()
      Get expanded singleUseMandate.
    • setSingleUseMandateObject

      public void setSingleUseMandateObject(Mandate expandableObject)
    • cancel

      public SetupIntent cancel() throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • cancel

      public SetupIntent cancel(RequestOptions options) throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • cancel

      public SetupIntent cancel(Map<String,Object> params) throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • cancel

      public SetupIntent cancel(Map<String,Object> params, RequestOptions options) throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • cancel

      public SetupIntent cancel(SetupIntentCancelParams params) throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • cancel

      public SetupIntent cancel(SetupIntentCancelParams params, RequestOptions options) throws StripeException
      You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

      After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm() throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm(RequestOptions options) throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm(Map<String,Object> params) throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm(Map<String,Object> params, RequestOptions options) throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm(SetupIntentConfirmParams params) throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • confirm

      public SetupIntent confirm(SetupIntentConfirmParams params, RequestOptions options) throws StripeException
      Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

      If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

      Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

      Throws:
      StripeException
    • create

      public static SetupIntent create(Map<String,Object> params) throws StripeException
      Creates a SetupIntent object.

      After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

      Throws:
      StripeException
    • create

      public static SetupIntent create(Map<String,Object> params, RequestOptions options) throws StripeException
      Creates a SetupIntent object.

      After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

      Throws:
      StripeException
    • create

      public static SetupIntent create(SetupIntentCreateParams params) throws StripeException
      Creates a SetupIntent object.

      After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

      Throws:
      StripeException
    • create

      public static SetupIntent create(SetupIntentCreateParams params, RequestOptions options) throws StripeException
      Creates a SetupIntent object.

      After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

      Throws:
      StripeException
    • list

      public static SetupIntentCollection list(Map<String,Object> params) throws StripeException
      Returns a list of SetupIntents.
      Throws:
      StripeException
    • list

      public static SetupIntentCollection list(Map<String,Object> params, RequestOptions options) throws StripeException
      Returns a list of SetupIntents.
      Throws:
      StripeException
    • list

      public static SetupIntentCollection list(SetupIntentListParams params) throws StripeException
      Returns a list of SetupIntents.
      Throws:
      StripeException
    • list

      public static SetupIntentCollection list(SetupIntentListParams params, RequestOptions options) throws StripeException
      Returns a list of SetupIntents.
      Throws:
      StripeException
    • retrieve

      public static SetupIntent retrieve(String intent) throws StripeException
      Retrieves the details of a SetupIntent that has previously been created.

      Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string.

      When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

      Throws:
      StripeException
    • retrieve

      public static SetupIntent retrieve(String intent, RequestOptions options) throws StripeException
      Retrieves the details of a SetupIntent that has previously been created.

      Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string.

      When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

      Throws:
      StripeException
    • retrieve

      public static SetupIntent retrieve(String intent, Map<String,Object> params, RequestOptions options) throws StripeException
      Retrieves the details of a SetupIntent that has previously been created.

      Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string.

      When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

      Throws:
      StripeException
    • retrieve

      public static SetupIntent retrieve(String intent, SetupIntentRetrieveParams params, RequestOptions options) throws StripeException
      Retrieves the details of a SetupIntent that has previously been created.

      Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string.

      When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

      Throws:
      StripeException
    • update

      public SetupIntent update(Map<String,Object> params) throws StripeException
      Updates a SetupIntent object.
      Specified by:
      update in interface MetadataStore<SetupIntent>
      Throws:
      StripeException
    • update

      public SetupIntent update(Map<String,Object> params, RequestOptions options) throws StripeException
      Updates a SetupIntent object.
      Specified by:
      update in interface MetadataStore<SetupIntent>
      Throws:
      StripeException
    • update

      public SetupIntent update(SetupIntentUpdateParams params) throws StripeException
      Updates a SetupIntent object.
      Throws:
      StripeException
    • update

      public SetupIntent update(SetupIntentUpdateParams params, RequestOptions options) throws StripeException
      Updates a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits() throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits(RequestOptions options) throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits(Map<String,Object> params) throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits(Map<String,Object> params, RequestOptions options) throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits(SetupIntentVerifyMicrodepositsParams params) throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • verifyMicrodeposits

      public SetupIntent verifyMicrodeposits(SetupIntentVerifyMicrodepositsParams params, RequestOptions options) throws StripeException
      Verifies microdeposits on a SetupIntent object.
      Throws:
      StripeException
    • setResponseGetter

      public void setResponseGetter(StripeResponseGetter responseGetter)
      Mandate collection method

      Equal to paper.

      Specified by:
      setResponseGetter in interface StripeActiveObject
      Overrides:
      setResponseGetter in class ApiResource
      Parameters:
      responseGetter - the StripeResponseGetter instance to use for making further requests.
    • getAttachToSelf

      public Boolean getAttachToSelf()
      If present, the SetupIntent's payment method will be attached to the in-context Stripe Account.

      It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

    • getAutomaticPaymentMethods

      public SetupIntent.AutomaticPaymentMethods getAutomaticPaymentMethods()
      Settings for dynamic payment methods compatible with this Setup Intent.
    • getCancellationReason

      public String getCancellationReason()
      Reason for cancellation of this SetupIntent, one of abandoned, requested_by_customer, or duplicate.
    • getClientSecret

      public String getClientSecret()
      The client secret of this SetupIntent. Used for client-side retrieval using a publishable key.

      The client secret can be used to complete payment setup from your frontend. It should not be stored, logged, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.

    • getCreated

      public Long getCreated()
      Time at which the object was created. Measured in seconds since the Unix epoch.
    • getDescription

      public String getDescription()
      An arbitrary string attached to the object. Often useful for displaying to users.
    • getFlowDirections

      public List<String> getFlowDirections()
      Indicates the directions of money movement for which this payment method is intended to be used.

      Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

    • getLastSetupError

      public StripeError getLastSetupError()
      The error encountered in the previous SetupIntent confirmation.
    • getLivemode

      public Boolean getLivemode()
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.
    • getNextAction

      public SetupIntent.NextAction getNextAction()
      If present, this property tells you what actions you need to take in order for your customer to continue payment setup.
    • getObject

      public String getObject()
      String representing the object's type. Objects of the same type share the same value.

      Equal to setup_intent.

    • getPaymentMethodConfigurationDetails

      public SetupIntent.PaymentMethodConfigurationDetails getPaymentMethodConfigurationDetails()
      Information about the payment method configuration used for this Setup Intent.
    • getPaymentMethodOptions

      public SetupIntent.PaymentMethodOptions getPaymentMethodOptions()
      Payment method-specific configuration for this SetupIntent.
    • getPaymentMethodTypes

      public List<String> getPaymentMethodTypes()
      The list of payment method types (e.g. card) that this SetupIntent is allowed to set up.
    • getStatus

      public String getStatus()
      Status of this SetupIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, canceled, or succeeded.
    • getUsage

      public String getUsage()
      Indicates how the payment method is intended to be used in the future.

      Use on_session if you intend to only reuse the payment method when the customer is in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. If not provided, this value defaults to off_session.

    • setAttachToSelf

      public void setAttachToSelf(Boolean attachToSelf)
      If present, the SetupIntent's payment method will be attached to the in-context Stripe Account.

      It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

    • setAutomaticPaymentMethods

      public void setAutomaticPaymentMethods(SetupIntent.AutomaticPaymentMethods automaticPaymentMethods)
      Settings for dynamic payment methods compatible with this Setup Intent.
    • setCancellationReason

      public void setCancellationReason(String cancellationReason)
      Reason for cancellation of this SetupIntent, one of abandoned, requested_by_customer, or duplicate.
    • setClientSecret

      public void setClientSecret(String clientSecret)
      The client secret of this SetupIntent. Used for client-side retrieval using a publishable key.

      The client secret can be used to complete payment setup from your frontend. It should not be stored, logged, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.

    • setCreated

      public void setCreated(Long created)
      Time at which the object was created. Measured in seconds since the Unix epoch.
    • setDescription

      public void setDescription(String description)
      An arbitrary string attached to the object. Often useful for displaying to users.
    • setFlowDirections

      public void setFlowDirections(List<String> flowDirections)
      Indicates the directions of money movement for which this payment method is intended to be used.

      Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

    • setId

      public void setId(String id)
      Unique identifier for the object.
    • setLastSetupError

      public void setLastSetupError(StripeError lastSetupError)
      The error encountered in the previous SetupIntent confirmation.
    • setLivemode

      public void setLivemode(Boolean livemode)
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.
    • setMetadata

      public void setMetadata(Map<String,String> 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.
    • setNextAction

      public void setNextAction(SetupIntent.NextAction nextAction)
      If present, this property tells you what actions you need to take in order for your customer to continue payment setup.
    • setObject

      public void setObject(String object)
      String representing the object's type. Objects of the same type share the same value.

      Equal to setup_intent.

    • setPaymentMethodConfigurationDetails

      public void setPaymentMethodConfigurationDetails(SetupIntent.PaymentMethodConfigurationDetails paymentMethodConfigurationDetails)
      Information about the payment method configuration used for this Setup Intent.
    • setPaymentMethodOptions

      public void setPaymentMethodOptions(SetupIntent.PaymentMethodOptions paymentMethodOptions)
      Payment method-specific configuration for this SetupIntent.
    • setPaymentMethodTypes

      public void setPaymentMethodTypes(List<String> paymentMethodTypes)
      The list of payment method types (e.g. card) that this SetupIntent is allowed to set up.
    • setStatus

      public void setStatus(String status)
      Status of this SetupIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, canceled, or succeeded.
    • setUsage

      public void setUsage(String usage)
      Indicates how the payment method is intended to be used in the future.

      Use on_session if you intend to only reuse the payment method when the customer is in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. If not provided, this value defaults to off_session.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • canEqual

      protected boolean canEqual(Object other)
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • getId

      public String getId()
      Unique identifier for the object.
      Specified by:
      getId in interface HasId
    • getMetadata

      public Map<String,String> getMetadata()
      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.
      Specified by:
      getMetadata in interface MetadataStore<SetupIntent>