Collect payments

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.

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

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

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_CsnggH3iChIYjrFoue5y6M98
: \
  -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. To control the payment flow for card_present payments, set the capture_method to manual.

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

Use the client secret as a parameter when calling collectPaymentMethod.

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.

function checkout() {
  // clientSecret is the client_secret from the PaymentIntent you created in Step 1.
  terminal.collectPaymentMethod(clientSecret).then(function(result) {
    if (result.error) {
      // Placeholder for handling result.error
    } else {
      // Placeholder for processing result.paymentIntent
    }
  });
}

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

You can cancel collecting a payment method calling cancelCollectPaymentMethod in the JavaScript SDK.

Handle events

After successfully collecting a payment method from the customer, the next step is to process the payment with the SDK. You can either process automatically or display a confirmation screen, where the customer can choose to proceed with the payment or cancel (for example, to pay with cash, or use a different payment method).

When you’re ready to proceed with the payment, call processPayment with the updated PaymentIntent from Step 2. A successful processPayment call results in a PaymentIntent with a status of requires_capture.

terminal.processPayment(paymentIntent).then(function(result) {
  if (result.error) {
    // Placeholder for handling result.error
  } else if (result.paymentIntent) {
    // Placeholder for notifying your backend to capture result.paymentIntent.id
  }
});

Handle processing failures

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

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

Stripe Terminal uses a two-step process to prevent unintended and duplicate payments. When the SDK returns a processed PaymentIntent to your app, the payment is authorized but not captured. Read the auth and capture documentation for more information about the difference.

When your app receives a processed 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:

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

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

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 is not 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.