Collect card 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_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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.

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’s 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.

The client_secret is all you need in your client-side application to proceed to payment method collection.

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

To collect a payment method, your app needs to be connected to a reader. The connected reader waits for a card to be presented after your app calls collectPaymentMethod.

async () => {
  // clientSecret is the client_secret from the PaymentIntent you created in Step 1.
  const result = await terminal.collectPaymentMethod(clientSecret);
  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.

Optionally inspect payment method details

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

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

async () => {
  // clientSecret is the client_secret from the PaymentIntent you created in Step 1.
  const result = await terminal.collectPaymentMethod(clientSecret, {
    config_override: {
      update_payment_intent: true
    }
  });
  if (result.error) {
    // Placeholder for handling result.error
  } else {
    const pm = result.paymentIntent.payment_method
    const card = pm?.card_present ?? pm?.interac_present

    // Placeholder for business logic on card before processing result.paymentIntent
  }
}

You can access attributes like card brand, funding, and other useful data at this point.

Cancel collection

Programmatic cancellation

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

Customer-initiated cancellation

When you set enable_customer_cancellation to true for a transaction, smart reader users see a cancel button.

Tapping the cancel button cancels the active transaction.

terminal.collectPaymentMethod(
  clientSecret,
  {
    config_override: {
      enable_customer_cancellation: true
    }
  }
)

Handle events

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.

async () => {
  const result = await terminal.processPayment(paymentIntent);
  if (result.error) {
    // Placeholder for handling result.error
  } else if (result.paymentIntent) {
    // Placeholder for notifying your backend to capture result.paymentIntent.id
  }
}

Handle 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.

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

Avoiding double charges

The PaymentIntent object enables money movement at Stripe—use a single PaymentIntent to represent a transaction.

Re-use the same PaymentIntent after a card is declined (for example, if it has insufficient funds), so your customer can try again with a different card.

If you edit the PaymentIntent, you must call collectPaymentMethod to update the payment information on the reader.

A PaymentIntent must be in the requires_payment_method state before Stripe can process it. An authorized, captured, or canceled PaymentIntent can’t be processed by a reader.

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:

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

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

Reconcile payments

To monitor the payments activity of your business, you might 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 might 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. You can’t use a canceled PaymentIntent 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.