🔐 What is a Token URL — and Why Is It Required?

To accept Tap to Pay on iPhone payments using Stripe, your app must first authenticate securely with Stripe’s API. This is done using a Connection Token, which is a short-lived key that authorizes the app to discover readers and create payment intents on your behalf.

Because the app runs on a device that should not hold secret Stripe keys, the secure way to retrieve a connection token is via a Token URL — a HTTPS endpoint on your server that returns a token generated by Stripe’s backend SDKs.

✅ Example Token URL implementation (PHP):

<?php
\Stripe\Stripe::setApiKey('sk_test_...');
$token = \Stripe\Terminal\ConnectionToken::create();
echo json_encode(['secret' => $token->secret]);
?>

This script returns a response like:

{ "secret": "tok_xxxx..." }

You then enter the full HTTPS URL to that script (e.g. https://yourdomain.com/api/token.php) into the app.

📌 Why It’s Needed

  • 🔒 Created server-side (never from the app)
  • 🕒 Short-lived (valid for 24 hours)
  • 🔁 Generated each time the app connects

Without a valid Token URL, the app cannot authenticate with Stripe and will not be able to start Tap to Pay sessions.

🔑 Authentication with Basic Auth

For added security, the Token URL is protected with HTTP Basic Authentication. This means:

  • Each user gets a unique username and password
  • These credentials are stored safely inside the app (via onboarding)
  • All requests from the app include the Authorization: Basic ... header automatically

This ensures that only you — or your app — can access your Token URL and perform secure operations such as generating tokens and capturing payments.

📧 How Receipts Work

After a successful payment, the app shows a prompt asking whether the customer wants a digital receipt.

  • If the customer enters an e-mail address, the app will send it to your backend
  • The backend then updates the PaymentIntent with receipt_email and finalizes (captures) the payment
  • Stripe will automatically email the receipt to the customer

If no e-mail is entered, the payment is still completed — just without a receipt.

⚙️ How to Get One

If you manage your own server, you can implement the script using PHP, Node.js, Python, etc.
Alternatively, if you don’t have a backend, you can subscribe to a hosted solution (e.g.
3leaf.it) that gives you a ready-to-use Token URL.

💡 Tip: You can test your Token URL in a browser — if it returns {"secret":"..."} (and asks for login), it’s working correctly.

Scroll to Top