Build Your Own Token URL for the 3leaf Payment Terminal App

By /

Build Your Own Token URL for the 3leaf Payment Terminal App

By Martin / October 16, 2025

With the 3leaf Payment Terminal app, you can use your own Token URL and manage your own Stripe environment — including your secret API key and Location ID.

This guide explains how to build a fully compatible Token URL endpoint, what requirements it must meet, and how email receipts are handled during capture.

🔐 What the Token URL Does

The Token URL is a secure HTTPS endpoint hosted on your server. The app communicates with it to perform two key actions:

  1. GET – Request a short-lived Stripe Terminal Connection Token
  2. POST – Capture a completed PaymentIntent, optionally adding a customer email for receipt delivery

⚙️ How It Works

When the 3leaf app connects to your Token URL, it sends either a GET or a POST request.

GET request

Used during reader discovery and connection. Your endpoint must return a valid Stripe Terminal Connection Token, for example:

{"secret": "tok_12345_secret_abc"}

POST request

Sent after the customer has tapped to pay. It includes the payment_intent ID — and, if provided by the customer, an optional email address.

Your server should:

  1. Update the PaymentIntent with receipt_email (if included)
  2. Capture the PaymentIntent
{
  "payment_intent": "pi_3NZk9...",
  "email": "customer@example.com"
}

🔒 Required Security

Your Token URL must be protected using Basic Authentication. The app automatically sends the username and password stored during onboarding.

A failed login must respond with:

{"error": "Unauthorized"}

and HTTP status 401.

Never expose your Stripe secret key or remove Basic Auth. The endpoint should only accept requests from the 3leaf Payment Terminal app.

✅ Requirements for Compatibility

For your Token URL to work correctly with the 3leaf Payment Terminal app, it must:

  • Respond to both GET and POST requests
  • Return JSON with UTF-8 encoding
  • Use HTTPS (no plain HTTP)
  • Require Basic Auth (username + password)
  • Use a valid Stripe Secret Key (live mode)
  • Support receipt_email and PaymentIntent capture
  • Include your Stripe Location ID inside the app settings (via onboarding or manual setup)

✉️ Email Receipts

If the customer provides an email address during checkout, it’s automatically sent with the POST request. Your endpoint should attach it to the PaymentIntent using the receipt_email field, and Stripe will handle the email delivery automatically.

🚀 Ready to Deploy

Once your Token URL is set up and secured, simply enter it in the app (along with your Location ID and credentials). You’ll be ready to process real Tap to Pay transactions on iPhone using your own Stripe account.

Keep it secure, keep it simple — and you’ll be ready to go live in minutes.

Scroll to Top