Skip to content

Latest commit

 

History

History
171 lines (127 loc) · 5.02 KB

README.md

File metadata and controls

171 lines (127 loc) · 5.02 KB

Collect in-person payments with Stripe Terminal's API

Table of contents

  1. Installation and Configuration
  2. Creating a Location
  3. Creating a Reader
  4. Running the sample

This integration shows you how to accept in-person payments with Stripe Terminal.

With Terminal you can build a point-of-sales application and integrate with a card reader using Stripe's Terminal APIs or Terminal's SDK.

Once your user and cashier are ready to complete their transaction, use the Stripe Terminal SDK or Terminal APIs to prompt the reader to collect payment. 🥳

How to run locally

The recommended approach is to install with the Stripe CLI:

stripe samples create terminal

Then pick:

server-driven

This sample includes several different server implementations and several different client implementations. The servers all implement the same routes and the clients all work with the same server routes.

Pick a server:

Pick a client:

Installing and cloning manually

If you do not want to use the Stripe CLI, you can manually clone and configure the sample yourself:

git clone https://github.com/stripe-samples/terminal

Rename and move the .env.example file into a file named .env in the specific folder of the server language you want to use. For example:

cp .env.example server-driven/server/node/.env

Example .env file:

STRIPE_SECRET_KEY=<replace-with-your-secret-key>
STATIC_DIR="../../client"

You will need a Stripe account in order to run the demo. Once you set up your account, go to the Stripe developer dashboard to find your API keys.

The other environment variables are configurable:

STATIC_DIR tells the server where the client files are located and does not need to be modified unless you move the server files.

Creating a Location

Locations help you manage readers and their activity by associating them with a physical operating site.

You can create a Location in the Dashboard or with the API. This sample requires at least one Location, because Locations are required to register Readers.

You can quickly create a location using the Stripe API like so:

curl https://api.stripe.com/v1/terminal/locations \
  -u sk_test_123: \
  -d "display_name"="HQ" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"="CA" \
  -d "address[country]"="US" \
  -d "address[postal_code]"="94110" \

This will return the JSON: -->

{
  "id": "tml_ElKc2wnORlbxOx",
  "object": "terminal.location",
  "address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1272 Valencia Street",
    "line2": "",
    "postal_code": "94110",
    "state": "CA"
  },
  "display_name": "HQ",
  "livemode": false,
  "metadata": {}
}

Creating a Reader

Stripe Terminal only works with our pre-certified readers. This demo assumes that you're using the BBPOS WisePOS E. Stripe also

You can create a Reader in the Dashboard or with the API. This sample requires at least one Reader.

If you're testing this integration with a physical device, connect it WiFi and generate a pairing code. If you're using the simulated reader, set registration_code to simulated-wpe.

curl https://api.stripe.com/v1/terminal/readers \
  -u sk_test_test: \
  -d "registration_code"="{{READER_REGISTRATION_CODE}}" \
  -d "label"="Stripe Sample Reader" \
  -d "location"="{{LOCATION_ID}}" #generated in previous step

This will return the JSON: -->

{
  "id": "tmr_ElKwIQjhcdTvWi",
  "object": "terminal.reader",
  "action": null,
  "device_sw_version": "",
  "device_type": "simulated_wisepos_e",
  "ip_address": "0.0.0.0",
  "label": "simulated-wpe-e435045e-9251-4e8e-8dc6-068192a466d8",
  "livemode": false,
  "location": "tml_ElKc2wnORlbxOx",
  "metadata": {},
  "serial_number": "e435045e-9251-4e8e-8dc6-068192a466d8",
  "status": "online"
}

Running the sample

Pick the server language you want and follow the instructions in the server folder README on how to run.

For example, if you want to run the Node server:

cd server/node
# There's a README in this folder with instructions to run the server.
npm install
npm start

The sample will run in the browser at localhost:4242.