SetupIntent Types

TypeScript types for creating, collecting, and confirming Stripe Terminal setup intents and processing refunds.

SetupIntent.Type

Represents a Stripe SetupIntent as returned by the Terminal SDK.

id · string · required

The SetupIntent’s unique identifier.

sdkUuid · string · required

A UUID assigned by the SDK to uniquely identify this SetupIntent locally.

livemode · boolean · required

Whether this SetupIntent was created in live mode.

application · string

ID of the Connect application that created the SetupIntent.

cancellationReason · string

Reason the SetupIntent was canceled.

clientSecret · string

The client secret of this SetupIntent.

created · string

ISO 8601 timestamp of when the SetupIntent was created.

customer · string

ID of the customer associated with this SetupIntent.

description · string

An arbitrary string attached to the SetupIntent.

lastSetupError · ApiErrorInformation

Details of the most recent setup error. See ApiErrorInformation.

latestAttempt · SetupIntent.SetupAttempt

The most recent setup attempt. See SetupIntent.SetupAttempt.

mandate · string

ID of the mandate created by this SetupIntent.

metadata · Record<string, string>

Arbitrary key-value metadata.

nextAction · NextAction

Details of the next action required to complete the setup.

onBehalfOf · string

The Stripe account ID on whose behalf the setup is made.

paymentMethod · PaymentMethod.Type

The PaymentMethod attached to this SetupIntent.

paymentMethodId · string

ID of the PaymentMethod.

paymentMethodOptions · PaymentMethodOptions

Options for the payment method.

paymentMethodTypes · string[]

List of allowed payment method types.

singleUseMandate · string

ID of the single-use mandate created by this SetupIntent.

status · SetupIntent.Status

The current status of the SetupIntent. See SetupIntent.Status.

usage · SetupIntent.Usage

Intended usage of the payment method: offSession or onSession.

---

SetupIntent.Status

The current state of a SetupIntent.

type Status =
  | 'canceled'
  | 'processing'
  | 'requiresAction'
  | 'requiresConfirmation'
  | 'requiresPaymentMethod'
  | 'succeeded'
  | 'unknown';

Value	Description
canceled	The SetupIntent was canceled
processing	Setup is being processed
requiresAction	Further action is required
requiresConfirmation	Awaiting confirmation
requiresPaymentMethod	No payment method has been attached yet
succeeded	Setup completed successfully
unknown	Status cannot be determined

---

SetupIntent.SetupAttempt

Details about a single attempt to set up a payment method.

id · string · required

The setup attempt’s unique identifier.

livemode · boolean · required

Whether the attempt was made in live mode.

status · string · required

The status of this setup attempt.

paymentMethodDetails · SetupIntent.SetupAttemptPaymentMethodDetails · required

Details about the payment method used in this attempt. See SetupAttemptPaymentMethodDetails.

applicationId · string

ID of the Connect application.

created · string

ISO 8601 timestamp of when the attempt was created.

customer · string

ID of the customer associated with this attempt.

onBehalfOfId · string

ID of the Stripe account on whose behalf the attempt is made.

paymentMethodId · string

ID of the payment method used.

setupIntentId · string

ID of the parent SetupIntent.

usage · SetupIntent.Usage

Intended usage: offSession or onSession.

---

SetupIntent.SetupAttemptPaymentMethodDetails

Payment method details captured during a setup attempt.

type · PaymentMethodType · required

The payment method type.

cardPresent · SetupIntent.SetupAttemptCardPresentDetails · required

Card-present details. See SetupAttemptCardPresentDetails.

interacPresent · SetupIntent.SetupAttemptCardPresentDetails · required

Interac-present details.

---

SetupIntent.SetupAttemptCardPresentDetails

Card details captured during a setup attempt.

emvAuthData · string · required

Raw EMV authorization data.

generatedCard · string · required

ID of the generated card payment method.

---

CreateSetupIntentParams

Parameters for creating a new SetupIntent.

customer · string

ID of the customer to associate with this SetupIntent.

description · string

An arbitrary description for the SetupIntent.

metadata · Record<string, string>

Arbitrary key-value metadata.

onBehalfOf · string

The Stripe account ID on whose behalf the setup is made.

paymentMethodTypes · string[]

List of allowed payment method types.

usage · string

Intended usage of the payment method: off_session or on_session.

---

CollectSetupIntentPaymentMethodParams

Parameters for collecting a payment method for a SetupIntent.

setupIntent · SetupIntent.Type · required

The SetupIntent to collect a payment method for.

allowRedisplay · AllowRedisplay

Controls whether the payment method can be redisplayed in future sessions. See AllowRedisplay.

customerCancellation · CustomerCancellation

Controls whether the customer can cancel collection. See CustomerCancellation.

motoConfiguration · MotoConfiguration

MOTO payment configuration. See MotoConfiguration.

collectionReason · CollectionReason

The reason for collecting the payment method. See CollectionReason.

---

ProcessSetupIntentParams

Parameters for processing a SetupIntent (collect and confirm in one call).

setupIntent · SetupIntent.Type · required

The SetupIntent to process.

allowRedisplay · AllowRedisplay

Redisplay control.

customerCancellation · CustomerCancellation

Customer cancellation control.

motoConfiguration · MotoConfiguration

MOTO configuration.

collectionReason · CollectionReason

Reason for collecting the payment method.

---

ConfirmSetupIntentMethodParams

Parameters for confirming a SetupIntent after collecting the payment method.

setupIntent · SetupIntent.Type · required

The SetupIntent to confirm.

---

CancelSetupIntentMethodParams

Parameters for canceling an in-progress SetupIntent collection.

setupIntent · SetupIntent.Type · required

The SetupIntent to cancel.

---

CollectionReason

The reason for collecting a payment method during setup.

type CollectionReason = 'saveCard' | 'verify' | 'unspecified';

Value	Description
saveCard	Collecting the card for future use
verify	Verifying the card without saving it for future use
unspecified	No specific reason provided

---

SetupIntentResultType

The return type of SetupIntent operations.

type SetupIntentResultType =
  | { setupIntent: SetupIntent.Type; error?: undefined }
  | { setupIntent?: undefined; error: StripeError };

---

Refund.Props

Represents a Stripe Refund as returned by the Terminal SDK.

id · string · required

The refund’s unique identifier.

amount · number

The amount refunded, in the smallest currency unit.

balanceTransaction · string

ID of the balance transaction that describes the impact of this refund.

chargeId · string

ID of the charge that was refunded.

created · string

ISO 8601 timestamp of when the refund was created.

currency · string

Three-letter ISO currency code.

description · string

An arbitrary description for the refund.

failureBalanceTransaction · string

ID of the balance transaction that reverses this refund if it fails.

failureReason · string

Reason the refund failed.

metadata · Record<string, string>

Arbitrary key-value metadata.

paymentIntentId · string

ID of the PaymentIntent that was refunded.

paymentMethodDetails · PaymentMethodDetails

Payment method details used for the refund.

reason · string

Reason for the refund: duplicate, fraudulent, or requested_by_customer.

receiptNumber · string

Transaction-specific information about the refund.

sourceTransferReversal · string

ID of the transfer reversal created when this refund is applied to a destination charge.

status · Refund.Status

The refund’s current status.

transferReversal · string

ID of the transfer reversal associated with this refund.

---

Refund.Status

type Status = 'succeeded' | 'failed' | 'pending' | 'unknown';

---

RefundParams

Union of RefundParamsWithPaymentIntentId and RefundParamsWithChargeId.

type RefundParams = RefundParamsWithPaymentIntentId | RefundParamsWithChargeId;

RefundParamsWithPaymentIntentId

Refund parameters when referencing a PaymentIntent.

paymentIntentId · string · required

ID of the PaymentIntent to refund.

clientSecret · string · required

The client secret of the PaymentIntent.

amount · number · required

Amount to refund in the smallest currency unit.

currency · string · required

Three-letter ISO currency code.

refundApplicationFee · boolean

Whether to refund the application fee.

reverseTransfer · boolean

Whether to reverse the transfer.

customerCancellation · CustomerCancellation

Controls whether the customer can cancel the refund flow.

metadata · Record<string, string>

Arbitrary key-value metadata.

RefundParamsWithChargeId

Refund parameters when referencing a Charge directly.

chargeId · string · required

ID of the Charge to refund.

amount · number · required

Amount to refund in the smallest currency unit.

currency · string · required

Three-letter ISO currency code.

refundApplicationFee · boolean

Whether to refund the application fee.

reverseTransfer · boolean

Whether to reverse the transfer.

customerCancellation · CustomerCancellation

Controls whether the customer can cancel the refund flow.

metadata · Record<string, string>

Arbitrary key-value metadata.

---

ProcessRefundResultType

The return type of processRefund().

type ProcessRefundResultType = {
  refund?: Refund.Props;
  error?: StripeError;
};

refund · Refund.Props

The processed refund, if successful.

error · StripeError

An error, if the refund failed.