Did you know that you can accept in-person payments with Stripe? In this series, we’re going to dive headfirst into building an in-person payments integration using Stripe Terminal.
In our last post, we started building a web-based point-of-sale application on Replit. As an initial step, we created a backend route for retrieving Stripe Terminal card readers. We finished up by using our newly created backend route to list our online readers in our reader dropdown, connecting our app to our active card readers.
In this blog post, we’re going to learn how to use the Payment Intents and Terminal APIs to create and handoff payments to our card readers, so that we can process them. We’ll also learn how to simulate tapping a credit card on a simulated reader.
That’s right, by the end of the blog post, you’ll be able to process and complete in-person payments with Stripe Terminal!
New to this series? Be sure to check out our first post on how to set up a card reader for testing and development and our second post on connecting them to a web application.
Processing payments with your point-of-sale app
If you’ve been following along with the series, you‘ve registered real or simulated card readers and started a web application that lists which readers are online. Now, we’ll finally give our app the ability to process payments.
A successful Stripe Terminal payment has three steps:
First, you set the reader to payment acceptance mode. In this step, the cashier enters an amount and pushes a button so that the reader transitions to the payment acceptance screen.
Next, you authorize the payment. At this stage, the cardholder taps, dips, or swipes their card device while the card reader is in payment acceptance mode. The card reader then securely forwards the card details to the card network for temporary authorization.
Finally, you confirm the payment. The cashier finalizes the transaction by manually confirming (or capturing) the charge. At this step, the charge has actually been finalized.
The additional step of confirming the transaction manually after it has been authorized may seem redundant, but it helps reduce fraud or unintended transactions. It’s also why you may see cashiers pressing a button on their point-of-sale console even after you’ve tapped your credit card.
Setting the reader to payment acceptance mode
At this point, our app has a form for submitting a reader ID and amount, so let's create an API route for processing a payment using that information. This route will ensure that when a cashier helps a customer checkout at the counter, the right amount will appear on the right card reader so that they can complete their payment.
💡If you need a starting point for your app, feel free to start off from this repl. It has all the code from the previous post.
If you want to see the end result, check out this repl.
On the backend, we’ll create a POST
/process-payment
route that will expect a request body with an amount
, representing the price in cents, and a reader_id
, representing the reader’s unique identifier. We’ll tell Stripe to create a payment by passing the amount
to stripe.paymentIntents.create()
along with the required currency
, capture_method
, and payment_method_type
parameters. This will create a Payment Intent, a special object that Stripe uses for managing payment states. We’ll destructure and alias the Payment Intent’s id
as paymentIntentId
.
We can tell Stripe to prompt a specific reader to payment acceptance mode for our payment by calling stripe.terminal.readers.process_payment()
with the card reader’s ID (readerId
) and the payment’s ID (paymentIntentId
) as arguments.
Now, when /process-payment
is called with a valid amount
and readerId
, Stripe will create a payment of the specified amount and forward it to the specified card reader. Now we just need to update our frontend, so that we can send it a readerId
and amount
when we submit our form to /process-payment
.
On the frontend, we’ll create a submit event listener that passes our amount and reader ID to /process-payment
. If we receive an error, we’ll add it to our #messages
div
just below our form and exit the function. Otherwise, we’ll add a message to #messages
indicating that we’ve successfully created our payment for our reader and redirect to the /readers.html
page, a page for controlling the reader after it’s prompted.
Now when we submit our form, we’ll create a payment and send it to our reader. Once that's done, we'll transition the web app to the /readers
page.
If you look for your payment in the Stripe dashboard, you’ll notice that it has created a new payment. We’ve successfully passed a payment to our Stripe Terminal reader. Huzzah! 🥳
Now we just need to test a cardholder actually tapping or dipping their card against our physical or simulated reader.
Authorizing a payment in test mode
If you have a physical BBPOS WisePOS E card reader, testing a payment attempt is easy because the reader will actually transition to the payment acceptance screen. Tap your test card against the reader and it’ll pretend to authorize the payment.
If you’re using a simulated reader, you’ll need to use the Terminal Reader test helper to simulate a cardholder dipping or tapping their card against the simulated reader. This is helpful for development without a reader, but it’s also a good tool for integration tests. You should probably learn to use it even if you have a physical WisePOS E reader on hand.
Let's build a route for authorizing simulated payments on simulated readers. On the backend, in /server/server.js
, add another POST
API route. Here we’ll destructure readerId
from the request body and pass it as an argument stripe.testHelpers.terminal.readers.presentPaymentMethod()
. This will tell Stripe to simulate a cardholder tapping or inserting their card on the reader.
On the frontend, in /client/reader.js
, we’ll add another event listener for DOMContentLoaded
and get the reader_id
and payment_intent_id
parameters from the URL and assign them to readerId
and paymentIntentId
, respectively. We’ll need the readerId
for reader actions like simulating the payment. The paymentIntentId
will come in handy when it’s time to capture the payment in the next section.
Add a click
event listener to our Simulate Payment button. Make a POST
request to /simulate-payment
with the readerId
. As before, add a message if there are any errors. Otherwise, we’ll add a message to our #messages
div
to show that the simulated payment was successful.
Go try out your Simulate Payment button in your app.
If you click on the link that’s generated by the addMessage
helper, it’ll take you to the payment in the Stripe Dashboard. You’ll see that the payment has a card attached to it and is uncaptured, which means that the transaction has been authorized but not finalized.
Congratulations: you’ve successfully simulated your first test Terminal authorization using the simulated card reader!🎉
Now we just need to add our own capture functionality to our point-of-sale app.🤔
Capturing authorized payments
Stripe Terminal authorizations only last 48 hours. After that, the authorization drops off and is released back to the card’s balance. Remember: if you don’t capture your payments, you won’t get paid!
Let’s create one last API endpoint for telling Stripe to finalize the payment. On the backend, in /server/server.js
, we’ll create a new POST
route, /capture-payment
. This route will expect a request body with a paymentIntentId
. We’ll capture the payment by calling stripe.paymentIntents.capture()
passing in the paymentIntentId
as the sole argument.
On the frontend, in client/reader.js
, we’ll add a click
event listener for our Capture button. It’ll use the payment_intent_id
from the URL parameters. If the attempt succeeds, we’ll forward the user to /success.html
, passing along the Payment Intent ID, so that we can render the payment details.
Now we’re able to finalize our payment by clicking the Capture button after once a payment has been authorized. Remember how we mentioned that sometimes cashiers need to press a button to complete the transaction? In the context of our point-of-sale app, that’s the Capture button.
We’re officially able to accept and finalize in-person payments with Stripe Terminal.🚀
Next up: Canceling in-flight in-person payments
Creating and completing payments with a Stripe Terminal reader is all well and good, but occasionally a customer will change their order mid-payment. In our final post, we’ll learn how to cancel in-flight payments.
Stay connected
Want to stay up to date on Stripe’s latest integrations, features, and open-source projects?
📣 Follow us on Twitter
💬 Join the official Discord server
📺 Subscribe to our Youtube channel
📧 Sign up for the Dev Digest
About the author
Charles Watkins is a Developer Advocate at Stripe where he writes, codes, and livestreams about online payments. In his spare time, he enjoys drawing, gaming, and rewatching the first five seasons of Game of Thrones.
Top comments (0)