Collect payments

Prepare your application and backend to collect payments using Stripe Terminal.

Note

For BBPOS WisePOS E readers, we recommend the server-driven integration, which uses the Stripe API instead of a Terminal SDK to collect payments.

Collecting payments with Stripe Terminal requires writing a payment flow in your application. Use the Stripe Terminal SDK to create and update a PaymentIntent, an object representing a single payment session.

Designed to be robust to failures, the Terminal integration splits the payment process into several steps, each of which can be retried safely:

Create a PaymentIntent
Collect a payment method
Process the payment
(Optional) Capture the payment

In Step 1, you can define whether to automatically or manually capture your payments. Authorization on the customer’s card takes place in Step 3, when the SDK processes the payment.

Create a PaymentIntent
Client-side
Server-side

The first step when collecting payments is to start the payment flow. When a customer begins checking out, your application must create a PaymentIntent object. This represents a new payment session on Stripe.

You can create a PaymentIntent on the client or server.

Use test amounts to try producing different results. An amount ending in 00 results in an approved payment.

Client-side

Create a PaymentIntent from your client:

Warning

If your app is connected to the Verifone P400, you can’t create a PaymentIntent from the iOS SDK. Instead, you must create the PaymentIntent server-side and retrieve it in your app using the Terminal.retrievePaymentIntent method in the SDK.

PaymentViewController.swift

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController {

    // ...

    // Action for a "Checkout" button
    func checkoutAction() {
        let params = PaymentIntentParameters(amount: 1000, currency: "usd")
        Terminal.shared.createPaymentIntent(params) { createResult, createError in
            if let error = createError {
                print("createPaymentIntent failed: \(error)")
            } else if let paymentIntent = createResult {
                print("createPaymentIntent succeeded")
                // ...
            }

        }
    }

    // ...
}

Server-side

You can create the PaymentIntent on your server if the information required to start a payment isn’t readily available in your app.

The following example shows how to create a PaymentIntent on your server:

Command Line

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1000 \
  -d "currency"="usd" \
  -d "payment_method_types[]"="card_present" \
  -d "capture_method"="manual"

For Terminal payments, the payment_method_types parameter must include card_present.

You can control the payment flow as follows:

To fully control the payment flow for card_present payments, set the capture_method to manual. This allows you to add a reconciliation step before finalizing the payment.
To authorize and capture payments in one step, set the capture_method to automatic.

Note

To accept Interac payments in Canada, you must also include interac_present in payment_method_types. For more details, visit our Canada documentation.

The PaymentIntent contains a client secret, a key that is unique to the individual PaymentIntent. To use the client secret, you must obtain it from the PaymentIntent on your server and pass it to the client side.

post '/create_payment_intent' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

First use the client secret to call retrievePaymentIntent, and then use the retrieved PaymentIntent to call collectPaymentMethod.

PaymentViewController.swift

func checkoutButtonAction() {
    // ... Fetch the client secret from your backend
    Terminal.shared.retrievePaymentIntent(clientSecret: clientSecret) { retrieveResult, retrieveError in
        if let error = retrieveError {
            print("retrievePaymentIntent failed: \(error)")
        }
        else if let paymentIntent = retrieveResult {
            print("retrievePaymentIntent succeeded: \(paymentIntent)")
            // ...
        }
    }
}

Collect a payment method
Client-side

After you’ve created a PaymentIntent, the next step is to collect a payment method with the SDK.

In order to collect a payment method, your app needs to be connected to a reader. The connected reader will wait for a card to be presented after your app calls collectPaymentMethod.

PaymentViewController.swift

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController, ReaderDisplayDelegate {


    // Label for displaying messages from the card reader
    let readerMessageLabel = UILabel(frame: .zero)
    var collectCancelable: Cancelable? = nil

    // ...

    // Action for a "Checkout" button
    func checkoutAction() {
        let params = PaymentIntentParameters(amount: 1000, currency: "usd")
        Terminal.shared.createPaymentIntent(params) { createResult, createError in
            if let error = createError {
                print("createPaymentIntent failed: \(error)")
            }
            else if let paymentIntent = createResult {
                print("createPaymentIntent succeeded")
                self.collectCancelable = Terminal.shared.collectPaymentMethod(paymentIntent) { collectResult, collectError in
                    if let error = collectError {
                        print("collectPaymentMethod failed: \(error)")
                    }
                    else if let paymentIntent = collectResult {
                        print("collectPaymentMethod succeeded")
                        // ... Process the payment
                    }
                }
            }

        }
    }
 }

 // MARK: BluetoothReaderDelegate - only needed for Bluetooth readers, this is the delegate set during connectBluetoothReader

 func reader(_ reader: Reader, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
     readerMessageLabel.text = Terminal.stringFromReaderInputOptions(inputOptions)
 }

 func reader(_ reader: Reader, didRequestReaderDisplayMessage displayMessage: ReaderDisplayMessage) {
     readerMessageLabel.text = Terminal.stringFromReaderDisplayMessage(displayMessage)
 }
 // MARK: ReaderDisplayDelegate

 func terminal(_ terminal: Terminal, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
     readerMessageLabel.text = Terminal.stringFromReaderInputOptions(inputOptions)
 }

 func terminal(_ terminal: Terminal, didRequestReaderDisplayMessage displayMessage: ReaderDisplayMessage) {
     readerMessageLabel.text = Terminal.stringFromReaderDisplayMessage(displayMessage)
 }

This method collects encrypted payment method data using the connected card reader, and associates the encrypted data with the local PaymentIntent.

Caution

Collecting a payment method happens locally and requires no authorization or updates to the Payment Intents API object until the next step, process the payment.

Optionally inspect payment method details Beta

For advanced use cases, you may optionally examine the payment method details of the presented card and perform your own business logic prior to authorization.

Use the initWithUpdatePaymentIntent parameter in CollectionConfiguration to attach a PaymentMethod to the server-side PaymentIntent. This data is returned in the collectPaymentMethod response.

PaymentViewController.swift

class PaymentViewController: UIViewController, ReaderDisplayDelegate {
    // ...

    // Action for a "Checkout" button
    func checkoutAction() {
        let params = PaymentIntentParameters(amount: 1000, currency: "usd")
        Terminal.shared.createPaymentIntent(params) { createResult, createError in
            if let error = createError {
                print("createPaymentIntent failed: \(error)")
            }
            else if let paymentIntent = createResult {
                print("createPaymentIntent succeeded")
                let collectConfig = CollectConfiguration(initWithUpdatePaymentIntent: true)
                self.collectCancelable = Terminal.shared.collectPaymentMethod(paymentIntent: paymentIntent, collectConfig: collectConfig) {
                  collectResult, collectError in
                    if let error = collectError {
                        print("collectPaymentMethod failed: \(error)")
                    }
                    else if let paymentIntent = collectResult {
                        print("collectPaymentMethod succeeded")
                        if let paymentMethod = paymentIntent.paymentMethod,
                            let card = paymentMethod.cardPresent ?? paymentMethod.interacPresent {

                            // ... Perform business logic on card
                        }

                        // ... Process the payment
                    }
                }
            }

        }
    }
 }

Note

This method attaches the collected encrypted payment method data with an update to the PaymentIntent object. It requires no authorization until the next step, process the payment.

This advanced use case isn’t supported on the Verifone P400 or with simulated Terminal readers.

You can cancel collecting a payment method using the Cancelable object returned by the iOS SDK.

Handle events

When collecting a payment method using a reader like the BBPOS Chipper 2X BT, without a built-in display, your app must be able to display events from the payment method collection process to users. These events help users successfully collect payments (for example, retrying a card, trying a different card, or using a different read method).

When a transaction begins, the SDK passes a ReaderInputOptions value to your app’s reader display handler, denoting the acceptable types of input (for example, Swipe, Insert, Tap). In your app’s checkout UI, prompt the user to present a card using one of these options.

During the transaction, the SDK might request your app to display additional prompts (for example, Retry Card) to your user by passing a ReaderDisplayMessage value to your app’s reader display handler. Make sure your checkout UI displays these messages to the user.

Note

Your application doesn’t need to display events from the payment method collection process to users because the reader displays them. To clear the payment method on a transaction, you can cancel the request.

PaymentViewController.swift

// MARK: BluetoothReaderDelegate - only needed for Bluetooth readers, this is the delegate set during connectBluetoothReader

 func reader(_ reader: Reader, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
     readerMessageLabel.text = Terminal.stringFromReaderInputOptions(inputOptions)
 }

 func reader(_ reader: Reader, didRequestReaderDisplayMessage displayMessage: ReaderDisplayMessage) {
     readerMessageLabel.text = Terminal.stringFromReaderDisplayMessage(displayMessage)
 }

Collect payments with Tap to Pay on iPhone

When your application is ready to collect a payment, the Stripe iOS SDK takes over the display to handle the collection process. After calling the collect payment method, your application remains running, but the iPhone displays a full-screen prompt to the cardholder, instructing them to present their card or NFC-based mobile wallet. If there’s an error reading the card, a prompt for retry displays. A successful presentation returns a success indication, and then control returns to your application to process the payment.

Payment collection

Process the payment
Client-side

After successfully collecting a payment method from the customer, the next step is to process the payment with the SDK. When you’re ready to proceed with the payment, call processPayment with the updated PaymentIntent from Step 2.

For manual capture of payments, a successful processPayment call results in a PaymentIntent with a status of requires_capture.
For automatic capture of payments, the PaymentIntent transitions to a succeeded state.

PaymentViewController.swift

// Action for a "Checkout" button
func checkoutAction() {
  let params = PaymentIntentParameters(amount: 1000, currency: "usd")
  Terminal.shared.createPaymentIntent(params) { createResult, createError in
      if let error = createError {
          print("createPaymentIntent failed: \(error)")
      } else if let paymentIntent = createResult {
          print("createPaymentIntent succeeded")
          self.collectCancelable = Terminal.shared.collectPaymentMethod(paymentIntent) { collectResult, collectError in
              if let error = collectError {
                  print("collectPaymentMethod failed: \(error)")
              } else if let collectPaymentMethodPaymentIntent = collectResult {
                  print("collectPaymentMethod succeeded")
                  // ... Process the payment
                  Terminal.shared.processPayment(collectPaymentMethodPaymentIntent) { processResult, processError in
                      if let error = processError {
                          print("processPayment failed: \(error)")
                      } else if let processPaymentPaymentIntent = processResult {
                          print("processPayment succeeded")
                          // Notify your backend to capture the PaymentIntent
                          APIClient.shared.capturePaymentIntent(processPaymentPaymentIntent.stripeId) { captureError in
                              if let error = captureError {
                                  print("capture failed: \(error)")
                              } else {
                                  print("capture succeeded")
                              }
                          }
                      }
                  }
              }
          }
      }
  }

Warning

You must manually capture PaymentIntents within two days or the authorization expires and funds are released to the customer.

Handle processing failures

When processing a payment fails, the SDK returns an error that includes the updated PaymentIntent. Your application needs to inspect the PaymentIntent to decide how to deal with the error.

PaymentIntent Status	Meaning	Resolution
`requires_payment_method`	Payment method declined	Try collecting a different payment method by calling `collectPaymentMethod` again with the same PaymentIntent.
`requires_confirmation`	Temporary connectivity problem	Call `processPayment` again with the same PaymentIntent to retry the request.
PaymentIntent is `nil`	Request to Stripe timed out, unknown PaymentIntent status	Retry processing the original PaymentIntent. Don’t create a new one, as that could result in multiple authorizations for the cardholder.

If you encounter multiple, consecutive timeouts, there might be a problem with your connectivity. Make sure that your app can communicate with the internet.

Capture the payment
Server-side

If you defined capture_method as manual during PaymentIntent creation in Step 1, the SDK returns an authorized but not captured PaymentIntent to your application. Learn more about the difference between authorization and capture.

When your app receives a confirmed PaymentIntent from the SDK, make sure it notifies your backend to capture the payment. Create an endpoint on your backend that accepts a PaymentIntent ID and sends a request to the Stripe API to capture it:

Command Line

curl -X POST https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

A successful capture call results in a PaymentIntent with a status of succeeded.

Note

To ensure the application fee captured is correct for connected accounts, inspect each PaymentIntent and modify the application fee, if needed, prior to manually capturing the payment.

Reconcile payments

To monitor the payments activity of your business, you may want to reconcile PaymentIntents with your internal orders system on your server at the end of a day’s activity.

A PaymentIntent that retains a requires_capture status may represent two things:

Unnecessary authorization on your customer’s card statement

Cause: User abandons your app’s checkout flow in the middle of a transaction
Solution: If the uncaptured PaymentIntent isn’t associated with a completed order on your server, you can cancel it. A canceled PaymentIntent can no longer be used to perform charges.

Incomplete collection of funds from a customer

Cause: Failure of the request from your app notifying your backend to capture the payment
Solution: If the uncaptured PaymentIntent is associated with a completed order on your server, and no other payment has been taken for the order (for example, a cash payment), you can capture it.

Collect tips US only

In the US, eligible users can collect tips when capturing payments.

Collect payments

Note

Create a PaymentIntentClient-sideServer-side

Client-side

Warning

Server-side

Note

Collect a payment method Client-side

Caution

Optionally inspect payment method details Beta

Note

Handle events

Note

Collect payments with Tap to Pay on iPhone

Process the paymentClient-side

Warning

Handle processing failures

Capture the paymentServer-side

Note

Reconcile payments

Collect tips US only

Create a PaymentIntent
Client-side
Server-side

Collect a payment method
Client-side

Process the payment
Client-side

Capture the payment
Server-side