The object you use to start reading a contactless payment or loyalty card.
Use a `PaymentCardReaderSession` object to read payment and loyalty cards from a
properly configured device. You don't create this object directly.
Instead, you obtain one by calling the ``PaymentCardReader/prepare(using:)``
method of your ``PaymentCardReader`` object, which returns a session
after the successful configuration of the device.
Maintain a strong reference to a session object for the duration of
the card-reading process. You may use the same session object to perform
multiple read operations, but you may perform only one read operation at a time
from the device.
Presents a sheet to read both contactless payments and loyalty cards
for a purchase or refund, and returns the relevant card data.
Call this method to read either a contactless payment card or a
loyalty card. This method displays a system sheet with instructions
on what the person needs to do. The system UI remains onscreen
until the system reads the person's card, you cancel the operation,
or an error occurs. If it reads a card successfully, the method returns
the card information as a result.
When the `stopOnVasResult` parameter is `true`:
- If the customer taps their loyalty card while the UI is present, the system
closes the sheet and returns ``VASReadResult`` as a result.
- If the customer taps their payment card while the UI is present, the system
closes the sheet and returns ``PaymentCardReadResult`` as a result.
When the `stopOnVasResult` parameter is `false`:
- If the customer taps their Apple Pay Wallet, containing both a relevant loyalty card and a payment card, the system closes the sheet and returns both ``PaymentCardReadResult`` and ``VASReadResult`` as a result.
- If the customer taps their Apple Pay Wallet, containing only a relevant loyalty card, the system closes the sheet and returns ``VASReadResult`` as a result.
- If the customer taps their payment card, the system closes the sheet and returns ``PaymentCardReadResult`` as a result.
- parameters:
- request: The transaction object you provide with the payment amount and currency details.
- vasRequest: The object that you use to specify the loyalty card request details,
such as the list of supported merchants.
- stopOnVASResult: A Boolean that indicates what type of result to return. See the discussion for details of how this parameter affects the return value.
- eventHandler: A handler you use to receive request-related updates. The handler
handler has no return value and takes a ``PaymentCardReaderSession/Event`` as a parameter.
Use the event parameter to determine what happened.
- returns: Either ``PaymentCardReadResult``, ``VASReadResult``, or both when
the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to read both contactless payments and loyalty cards
for a purchase or refund, and returns the relevant card data.
Call this method to read either a contactless payment card or a
loyalty card. This method displays a system sheet with instructions
on what the person needs to do. The system UI remains onscreen
until the system reads the person's card, you cancel the operation,
or an error occurs. If it reads a card successfully, the method returns
the card information as a result.
When the `stopOnVasResult` parameter is `true`:
- If the customer taps their loyalty card while the UI is present, the system
closes the sheet and returns ``VASReadResult`` as a result.
- If the customer taps their payment card while the UI is present, the system
closes the sheet and returns ``PaymentCardReadResult`` as a result.
When the `stopOnVasResult` parameter is `false`:
- If the customer taps their Apple Pay Wallet, containing both a relevant loyalty card and a payment card, the system closes the sheet and returns both ``PaymentCardReadResult`` and ``VASReadResult`` as a result.
- If the customer taps their Apple Pay Wallet, containing only a relevant loyalty card, the system closes the sheet and returns ``VASReadResult`` as a result.
- If the customer taps their payment card, the system closes the sheet and returns ``PaymentCardReadResult`` as a result.
- parameters:
- request: The transaction object you provide with the payment amount and currency details.
- vasRequest: The object that you use to specify the loyalty card request details,
such as the list of supported merchants.
- stopOnVASResult: A Boolean that indicates what type of result to return. See the discussion for details of how this parameter affects the return value.
- returns: Either ``PaymentCardReadResult``, ``VASReadResult``, or both when
the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to read a contactless payment card for a purchase or
a refund, and returns the encrypted card data.
Call this method as the first step in a financial transaction involving
Tap to Pay with iPhone. This method displays a system-provided sheet with instructions
on what the person needs to do. This UI remains onscreen until the system reads
the person's card, you cancel the operation, or an error occurs. After the
read operation concludes successfully, deliver the returned card information to
your payment service provider.
- parameters:
- request: The transaction object you provide with the payment amount and currency details.
- returns: A ``PaymentCardReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to verify a contactless payment card, and returns the card data.
Call this method when you want to verify someone's card with your payment
provider. When you call this method, the system displays UI with instructions
on what the person needs to do. This UI remains onscreen until the system reads
the person's card, you cancel the operation, or an error occurs.
- parameters:
- request: The object that contains the reason for the verification request.
For example, you might verify the card supports a specific currency.
- eventHandler: A handler you use to receive request-related updates while
the system has control of the screen. The handler has no return value and takes
a ``PaymentCardReaderSession/Event`` as a parameter. Use the event parameter
to determine what happened.
- returns: A ``PaymentCardReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to read a contactless payment card for a purchase or
a refund, and returns the encrypted card data.
Call this method as the first step in a financial transaction involving
Tap to Pay with iPhone. This method displays a system-provided sheet with instructions
on what the person needs to do. This UI remains onscreen until the system reads
the person's card, you cancel the operation, or an error occurs. After the
read operation concludes successfully, deliver the returned card information to
your payment service provider.
- parameters:
- request: The transaction object you provide with the payment amount and currency details.
- returns: A ``PaymentCardReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to verify a contactless payment card, and returns the card data.
Call this method when you want to verify someone's card with your payment
provider. When you call this method, the system displays UI with instructions
on what the person needs to do. This UI remains onscreen until the system reads
the person's card, you cancel the operation, or an error occurs.
- parameters:
- request: The object that contains the reason for the verification request.
For example, you might verify the card supports a specific currency.
- returns: A ``PaymentCardReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
method · iOS 15.4+
cancelRead
TypeScript
cancelRead(): Promise<boolean>
Swift declaration
func cancelRead() async throws -> Bool
Dismiss the sheet that prompts someone to present their card for reading.
You can cancel a read operation before the device detects the card and
starts reading it, but not after. Once the device begins reading the
card, you cannot dismiss the sheet.
The reader supports only one read operation at a time. This method affects
only the currently active read operation.
Presents a sheet to capture the PIN when required by the payment card issuer,
and returns the previously encrypted card data including newly captured PIN data.
Call this method when the payment card issuer requests a PIN for the current transaction.
When you call this method, the system displays UI with instructions
on what the person needs to do. This UI remains onscreen until the system reads
the person's PIN, you cancel the operation, or an error occurs.
> Important: The encrypted payment card data are only kept 55 seconds after previous read
if the PIN was not requested by the card.
After this delay, this method will return ``ReadError/pinEntryFailed``
- parameters:
- token: Valid and signed PIN token from a participating payment service provider.
- cardReaderTransactionID: The ``PaymentCardReadResult/id-swift.property-65or0`` of the previous read.
- returns: ``PaymentCardReadResult`` if the PIN was successfully captured.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
get · iOS 15.4+ · Deprecated in iOS 16.0
id
TypeScript
get id(): string
Swift declaration
final let id: String
A unique identifier for this object.
get · iOS 18.4+
currentOSVersionDeprecationDate
TypeScript
get currentOSVersionDeprecationDate(): (globalThis.Date) | null
Swift declaration
final let currentOSVersionDeprecationDate: Date?
The date when current OS version will be deprecated.
You should update the OS before the deprecation date.
Presents a sheet to read a loyalty card for Value Added Services (VAS), and returns the loyalty card data.
Call this method to read the data from a loyalty card. When you call this method, the system displays
UI with instructions on what the person needs to do. This UI remains onscreen
until the system reads the person's card, you cancel the operation, or an error occurs.
- parameters:
- request: The object that you use to specify the request details, such
as the list of supported merchants.
- eventHandler: A handler you use to receive request-related updates. The
handler has no return value and takes a ``PaymentCardReaderSession/Event``
as a parameter. Use the event parameter to determine what happened.
- returns: A ``VASReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
Presents a sheet to read a loyalty card for Value Added Services (VAS), and returns the loyalty card data.
Call this method to read the data from a loyalty card. When you call this method, the system displays
UI with instructions on what the person needs to do. This UI remains onscreen
until the system reads the person's card, you cancel the operation, or an error occurs.
- parameters:
- request: The object that you use to specify the request details, such
as the list of supported merchants.
- returns: A ``VASReadResult`` if the read operation was successful.
- throws: This method throws a ``ReadError`` if a person dismisses the sheet
or the sheet fails to appear.
