PaymentIntent Types

`PaymentIntent.Type`

Represents a Stripe PaymentIntent as returned by the Terminal SDK.

string

required

The PaymentIntent’s unique identifier.

amount

number

required

Amount intended to be collected, in the smallest currency unit (e.g., cents for USD).

currency

string

required

Three-letter ISO currency code in lowercase.

captureMethod

string

required

How the payment is captured: automatic or manual.

charges

Charge[]

required

List of charges associated with this PaymentIntent. See Charge.

created

string

required

ISO 8601 timestamp of when the PaymentIntent was created.

livemode

boolean

required

Whether the PaymentIntent was created in live mode.

sdkUuid

string

required

A UUID assigned by the SDK to uniquely identify this PaymentIntent locally (used for offline reconciliation).

status

PaymentIntent.Status

The PaymentIntent’s current status. See PaymentIntent.Status.

amountCapturable

number

Amount that can be captured from this PaymentIntent.

amountDetails

AmountDetails

Breakdown of the amount, including tip, donation, and surcharge. See AmountDetails.

amountReceived

number

Amount that was collected.

amountRequested

number

The originally requested amount.

amountSurcharge

number

The surcharge amount, if any.

amountTip

number

The tip amount, if any.

applicationFeeAmount

number

The amount of the application fee.

canceledAt

string

ISO 8601 timestamp of when the PaymentIntent was canceled.

cancellationReason

string

Reason the PaymentIntent was canceled.

clientSecret

string

The client secret of this PaymentIntent.

confirmationMethod

string

Confirmation method: automatic or manual.

customer

string

ID of the Stripe Customer object associated with this PaymentIntent.

description

string

An arbitrary string attached to the PaymentIntent.

lastPaymentError

ApiErrorInformation

Details about the last payment error. See ApiErrorInformation.

metadata

Record<string, string>

Set of key-value pairs attached to the PaymentIntent.

nextAction

NextAction

Details of the next action to complete the payment, if required.

offlineDetails

OfflineDetails

Details about an offline payment. See OfflineDetails.

onBehalfOf

string

The Stripe account ID for which this payment is being collected.

paymentMethod

PaymentMethod.Type

The PaymentMethod attached to this PaymentIntent. See PaymentMethod.Type.

paymentMethodId

string

The ID of the PaymentMethod.

paymentMethodOptions

PaymentMethodOptions

Options for the PaymentMethod. See PaymentMethodOptions.

paymentMethodTypes

number[]

List of payment method type codes allowed for this PaymentIntent.

receiptEmail

string

Email address to send the receipt to.

setupFutureUsage

string

Indicates how the PaymentMethod should be used for future payments: off_session or on_session.

statementDescriptor

string

Statement descriptor shown on the customer’s bank statement.

statementDescriptorSuffix

string

Suffix appended to the statement descriptor.

transferGroup

string

A string that identifies the resulting payment as part of a group.

`PaymentIntent.Status`

The current state of a PaymentIntent.

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

Value	Description
`canceled`	The PaymentIntent was canceled
`processing`	Payment is being processed
`requiresAction`	Further action is required (e.g., customer authentication)
`requiresCapture`	Payment is authorized and awaiting capture
`requiresConfirmation`	Awaiting confirmation
`requiresPaymentMethod`	No payment method has been attached yet
`succeeded`	Payment was successfully collected
`unknown`	Status cannot be determined

`Charge`

A charge attempt associated with a PaymentIntent.

string

required

The charge’s unique identifier.

amount

number

required

The amount charged, in the smallest currency unit.

amountRefunded

number

required

The amount refunded.

captured

boolean

required

Whether the charge was captured.

currency

string

required

Three-letter ISO currency code.

livemode

boolean

required

Whether the charge was made in live mode.

paid

boolean

required

Whether the charge was paid.

refunded

boolean

required

Whether the charge has been fully refunded.

applicationFee

string

ID of the application fee associated with this charge.

applicationFeeAmount

number

The application fee amount.

authorizationCode

string

Authorization code for the charge.

balanceTransaction

string

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

calculatedStatementDescriptor

string

The full statement descriptor sent to the card network.

created

string

ISO 8601 timestamp of when the charge was created.

customer

string

ID of the customer associated with this charge.

description

string

Description of the charge.

generatedFrom

GeneratedFrom

Details about the source that generated this charge.

Show GeneratedFrom properties

charge

string

ID of the original charge.

paymentMethodDetails

PaymentMethodDetails

Payment method details from the source charge.

setupAttempt

string

ID of the setup attempt that generated this charge.

metadata

Record<string, string>

Set of key-value pairs attached to the charge.

onBehalfOf

string

The Stripe account the charge was made on behalf of.

paymentIntentId

string

ID of the PaymentIntent associated with this charge.

paymentMethodDetails

PaymentMethodDetails

Details about the payment method used. See PaymentMethodDetails.

receiptEmail

string

Email to which the receipt was sent.

receiptNumber

string

Receipt number for this charge.

receiptUrl

string

URL of the charge’s receipt.

statementDescriptorSuffix

string

Suffix on the statement descriptor.

status

string

Status of the charge: succeeded, pending, or failed.

`PaymentMethodDetails`

Details about the payment method used in a charge or refund.

type

string

required

The payment method type (e.g., cardPresent, interacPresent, wechatPay).

cardPresentDetails

CardPresentDetails

Details for card-present payments. See CardPresentDetails.

interacPresentDetails

CardPresentDetails

Details for Interac-present payments (same shape as CardPresentDetails).

wechatPayDetails

WechatPayDetails

Details for WeChat Pay payments. See WechatPayDetails.

affirmDetails

AffirmDetails

Details for Affirm payments. See AffirmDetails.

paynowDetails

PaynowDetails

Details for PayNow payments. See PaynowDetails.

paypayDetails

PaypayDetails

Details for PayPay payments. See PaypayDetails.

cardDetails

CardDetails

Details for card (not card-present) payments. See CardDetails.

`CardPresentDetails`

Details about a card-present transaction.

last4

string

required

Last four digits of the card number.

expMonth

string

required

Card expiration month.

expYear

string

required

Card expiration year.

funding

string

required

Card funding type: credit, debit, prepaid, or unknown.

brand

string

required

Card brand: e.g., visa, mastercard, amex.

preferredLocales

string[]

required

List of preferred locales for the cardholder.

issuer

string

required

The card issuer.

iin

string

required

Issuer identification number (first 6 digits of the card).

network

string

required

Card network (e.g., visa, mastercard).

description

string

required

A human-readable description of the card.

wallet

Wallet

required

Wallet details if the card was presented via a digital wallet. See Wallet.

cardholderName

string

Name of the cardholder.

generatedCard

string

ID of the generated card (used for saving the card).

receipt

ReceiptDetails

EMV receipt data. See ReceiptDetails.

emvAuthData

string

Raw EMV authorization data.

country

string

Two-letter country code of the card’s issuing country.

location

string

ID of the location where the payment was taken.

reader

string

ID of the reader used for this payment.

`ReceiptDetails`

EMV receipt data from a card-present transaction.

accountType

string

required

Account type used for the transaction.

applicationCryptogram

string

required

The application cryptogram.

applicationPreferredName

string

required

The application preferred name.

authorizationCode

string

required

Authorization code from the issuer.

authorizationResponseCode

string

required

Authorization response code.

cvm

string

required

Cardholder verification method used.

dedicatedFileName

string

required

EMV dedicated file name.

terminalVerificationResult

string

required

Terminal verification result bytes.

Details about a card payment method (not card-present).

brand

string

Card brand.

country

string

Two-letter country code of the issuing country.

expMonth

number

Expiration month.

expYear

number

Expiration year.

funding

string

Card funding type.

generatedFrom

GeneratedFrom

Details about the source that generated this card.

last4

string

Last four digits of the card number.

`CreatePaymentIntentParams`

Parameters for creating a new PaymentIntent.

amount

number

required

Amount to collect in the smallest currency unit.

currency

string

required

Three-letter ISO currency code.

captureMethod

'automatic' | 'manual'

How the payment is captured. Defaults to automatic.

setupFutureUsage

'off_session' | 'on_session'

Indicates the intended future usage of the payment method.

onBehalfOf

string

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

transferDataDestination

string

The destination account for the transfer.

applicationFeeAmount

number

Amount of the application fee.

description

string

An arbitrary description for the PaymentIntent.

statementDescriptor

string

Statement descriptor shown on the customer’s bank statement (up to 22 characters).

statementDescriptorSuffix

string

Suffix appended to the statement descriptor.

receiptEmail

string

Email address to send the receipt to.

customer

string

ID of the customer to associate with this PaymentIntent.

transferGroup

string

A string that identifies the resulting payment as part of a group.

metadata

Record<string, string>

Arbitrary key-value metadata.

paymentMethodOptions

PaymentMethodOptions

Additional options for the payment method. See PaymentMethodOptions.

offlineBehavior

'prefer_online' | 'require_online' | 'force_offline'

Controls offline payment behavior.

paymentMethodTypes

string[]

List of allowed payment method types. (iOS only)

`PaymentMethodOptions`

Additional options for the payment method on a PaymentIntent.

requestedPriority

string

required

The requested priority for the payment method.

requestExtendedAuthorization

boolean

Request extended authorization.

requestIncrementalAuthorizationSupport

boolean

Request incremental authorization support.

requestPartialAuthorization

string

Request partial authorization.

captureMethod

'manual' | 'manual_preferred'

Override the capture method for this payment method.

`CollectPaymentMethodParams`

Parameters for collecting a payment method from a customer.

paymentIntent

PaymentIntent.Type

required

The PaymentIntent to collect a payment method for.

skipTipping

boolean

When true, skips the tipping screen.

tipEligibleAmount

number

The portion of the amount eligible for tipping.

updatePaymentIntent

boolean

Whether to update the PaymentIntent on the server before collecting.

customerCancellation

CustomerCancellation

Controls whether the customer can cancel the payment collection. See CustomerCancellation.

requestDynamicCurrencyConversion

boolean

Request dynamic currency conversion (DCC) if available.

surchargeNotice

string

Notice text to display when a surcharge applies.

allowRedisplay

AllowRedisplay

Controls whether the collected payment method may be redisplayed to the customer. See AllowRedisplay.

motoConfiguration

MotoConfiguration

Configuration for Mail Order / Telephone Order (MOTO) payments. See MotoConfiguration.

`ConfirmPaymentMethodParams`

Parameters for confirming a collected payment method.

paymentIntent

PaymentIntent.Type

required

The PaymentIntent to confirm.

surcharge

Surcharge

Surcharge details to apply at confirmation. See Surcharge.

returnUrl

string

URL to redirect to after completing the action (used for redirect-based payment methods).

`ProcessPaymentIntentParams`

Combined parameters for collecting and confirming a payment in a single call. Includes all fields from both CollectPaymentMethodParams and ConfirmPaymentMethodParams.

paymentIntent

PaymentIntent.Type

required

The PaymentIntent to process.

skipTipping

boolean

Skip the tipping screen.

tipEligibleAmount

number

Amount eligible for tipping.

updatePaymentIntent

boolean

Update the PaymentIntent on the server before processing.

customerCancellation

CustomerCancellation

Customer cancellation control. See CustomerCancellation.

requestDynamicCurrencyConversion

boolean

Request DCC if available.

surchargeNotice

string

Surcharge notice text.

allowRedisplay

AllowRedisplay

Allow-redisplay setting. See AllowRedisplay.

motoConfiguration

MotoConfiguration

MOTO configuration. See MotoConfiguration.

surcharge

Surcharge

Surcharge to apply. See Surcharge.

returnUrl

string

Return URL for redirect-based payment methods.

`CancelPaymentMethodParams`

Parameters for canceling an in-progress payment method collection.

paymentIntent

PaymentIntent.Type

required

The PaymentIntent whose collection should be canceled.

`Surcharge`

Surcharge details applied at payment confirmation.

amount

number

required

The surcharge amount in the smallest currency unit.

Consent details for the surcharge. See SurchargeConsent.

`SurchargeConsent`

Details of customer consent for a surcharge.

notice

string

required

The notice text shown to the customer.

collection

SurchargeConsentCollection

required

Whether surcharge consent collection is enabled or disabled. See SurchargeConsentCollection.

`SurchargeConsentCollection`

type SurchargeConsentCollection = 'disabled' | 'enabled';

`MotoConfiguration`

Configuration for Mail Order / Telephone Order (MOTO) payments.

skipCvc

boolean

When true, skips CVC collection for MOTO payments.

`AllowRedisplay`

Controls whether a collected payment method can be shown to the customer again in future sessions.

type AllowRedisplay = 'always' | 'limited' | 'unspecified';

Value	Description
`always`	The payment method can always be redisplayed
`limited`	The payment method can be redisplayed only in limited contexts
`unspecified`	No redisplay preference specified

`CustomerCancellation`

Controls whether the customer can cancel the payment collection flow.

type CustomerCancellation = 'enableIfAvailable' | 'disableIfAvailable' | 'unspecified';

Value	Description
`enableIfAvailable`	Show a cancel button if the hardware supports it
`disableIfAvailable`	Hide the cancel button if the hardware supports it
`unspecified`	Use the platform default

`PaymentStatus`

The current state of the Terminal SDK’s payment collection flow.

type PaymentStatus = 'notReady' | 'ready' | 'processing' | 'waitingForInput';

Value	Description
`notReady`	The SDK is not ready to collect payments
`ready`	Ready to collect a payment
`processing`	A payment is being processed
`waitingForInput`	Waiting for customer input

`OfflineDetails`

Details about a payment that was captured while offline.

storedAtMs

string

required

Timestamp (in milliseconds) of when the payment was stored offline.

requiresUpload

boolean

required

Whether the payment still needs to be forwarded to Stripe.

cardPresentDetails

OfflineCardPresentDetails

required

Card details captured offline. See OfflineCardPresentDetails.

amountDetails

AmountDetails

required

Amount breakdown. See AmountDetails.

`OfflineCardPresentDetails`

Card details captured during an offline payment.

brand

string

required

Card brand.

cardholderName

string

required

Cardholder name.

expMonth

number

required

Card expiration month.

expYear

number

required

Card expiration year.

last4

string

required

Last four digits of the card.

readMethod

string

required

How the card was read (e.g., contactEmv, contactlessEmv).

receiptDetails

ReceiptDetails

required

EMV receipt data.

`AmountDetails`

Breakdown of the payment amount.

tip

Amount

Tip amount details.

donation

Amount

Donation amount details.

surcharge

Amount

Surcharge amount details.

`Amount`

amount

number

The amount in the smallest currency unit.

`PaymentIntentResultType`

The return type of payment intent operations. Can carry a paymentIntent, an error, or both (when the intent is created offline but confirmation fails).

type PaymentIntentResultType =
  | { paymentIntent: PaymentIntent.Type; error?: undefined }
  | { paymentIntent?: undefined; error: StripeError }
  | { paymentIntent: PaymentIntent.Type; error: StripeError };

The third variant — where both paymentIntent and error are present — occurs in offline scenarios where the intent was stored but the upload failed. Always check for error even when paymentIntent is present.

`PaymentMethodType`

The type of payment method used in a transaction.

type PaymentMethodType =
  | 'cardPresent'
  | 'interacPresent'
  | 'card'
  | 'wechatPay'
  | 'affirm'
  | 'paynow'
  | 'paypay';

`PaymentMethod.Type`

A Stripe PaymentMethod object as returned by the Terminal SDK.

string

required

The PaymentMethod’s unique identifier.

type

PaymentMethodType

required

The type of payment method.

customer

string

required

The ID of the customer this payment method belongs to.

livemode

boolean

required

Whether this payment method was created in live mode.

cardPresentDetails

CardPresentDetails

Card-present details, if applicable.

interacPresentDetails

CardPresentDetails

Interac-present details, if applicable.

wechatPayDetails

WechatPayDetails

WeChat Pay details, if applicable.

affirmDetails

AffirmDetails

Affirm details, if applicable.

paynowDetails

PaynowDetails

PayNow details, if applicable.

paypayDetails

PaypayDetails

PayPay details, if applicable.

cardDetails

CardDetails

Card (non-present) details, if applicable.

metadata

Record<string, string>

Arbitrary key-value metadata attached to the payment method.

`PaymentOption`

Represents one of multiple payment options available on a reader that supports both card and QR-based payments.

index

number

required

Index of the option, passed to selectPaymentOption() to select it.

type

'card' | 'nonCard' | 'unknown'

required

Whether this option is card-present or a non-card method (e.g., QR code).

label

string

Human-readable label for the option.

paymentMethodType

string

The underlying payment method type identifier.

`QrCodeDisplayData`

Data required to render a QR code for the customer to scan.

imageUrlPng

string

required

URL to a PNG image of the QR code.

imageUrlSvg

string

required

URL to an SVG image of the QR code.

expiresAtMs

number

required

Unix timestamp in milliseconds when the QR code expires.

paymentMethodType

string

required

The payment method type this QR code is for.

`PaymentMethodSelectionHandler`

Callback invoked when a mobile Bluetooth reader supports multiple payment options and the application must present them to the customer.

type PaymentMethodSelectionHandler = (
  paymentIntent: PaymentIntent.Type,
  availablePaymentOptions: PaymentOption[],
  callback: {
    selectPaymentOption: (paymentOptionType: string) => Promise<{ error?: StripeError }>;
    failPaymentMethodSelection: (error?: string) => Promise<{ error?: StripeError }>;
  }
) => void;

Callback method	Description
`selectPaymentOption(paymentOptionType)`	Call with the selected option type to proceed
`failPaymentMethodSelection(error?)`	Call to abort payment method selection with an optional error message

`QrCodeDisplayHandler`

Callback invoked when the SDK needs the application to display a QR code to the customer.

type QrCodeDisplayHandler = (
  paymentIntent: PaymentIntent.Type,
  qrData: QrCodeDisplayData,
  callback: {
    confirmQrCodeDisplayed: () => Promise<{ error?: StripeError }>;
    failQrCodeDisplay: (error?: string) => Promise<{ error?: StripeError }>;
  }
) => void;

Callback method	Description
`confirmQrCodeDisplayed()`	Call after the QR code has been displayed to the customer
`failQrCodeDisplay(error?)`	Call if the QR code cannot be displayed

Components

Hooks

Types