Docs
Payments
Collect a Payment
In-Person Payments

In-Person Payments

Collect in-person payments with .

Supported countries

  • United States
  • Canada (available in Q4 2024)

Features

  • Card, Apple Pay, Google Pay, Samsung Pay
  • On-device tipping
  • Receipts
  • Card tokenization
  • Auth and capture
  • Terminal management
  • Real-time terminal monitoring
  • Point-to-Point Encryption (P2PE)
  • PCI compliance

Scope of integration

  1. Design your integration
  2. Order developer terminals
  3. Integrate in-person payments
  4. Test your integration

Design Your Integration

Choose your terminals

currently offers two types of terminal readers to suit different business needs:

  • VL100: Best for countertop use
  • VL110: Best for handheld use

Check out our online store (opens in a new tab) for more information.

Identify required functionality

There are several in-person payments features to choose from which you can implement during your integration.

Order Developer Terminals

To test your integration, you’ll need a developer terminal. The easiest and most convenient option is to order a developer terminal (opens in a new tab) from . The terminal will arrive within a few business days, fully activated and ready to use. Simply connect it to Wi-Fi to get started.

If you already own a developer terminal, you can use it as long as it is a VL100 or VL110 model and suitable for test environments. To use your own terminal:

  1. Email support to request an Activation Code.
  2. Enter the Activation Code onto the terminal to associate it with your test account.

Collect an In-Person Payment

If you are already familiar with collecting card-not-present transactions using , the process for card-present transactions will be similar.

Retrieve the terminal id

When a merchant orders a terminal, associates the device’s serial number with the merchant’s account and assigns a unique terminal_reader_id. Before processing a payment, List all Terminal ReadersAPI linked to the merchant’s account to specify the device from which the payment will be collected.

curl -L {{PRODUCTION_API_URL}}/v1/terminal-readers/{{TERMINAL_ID}} \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  

Create a card-present payment method

To Create a Payment MethodAPI for an in-person payment, set the type=card_present and include the terminal_reader_id of the intended device.

Create a Payment Method sample request

curl -L '{{PRODUCTION_API_URL}}/v1/payment-methods' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
   "type": "card_present",
   "terminal_reader_id": "{{TERMINAL_READER_ID}}"
}'

Collect the payment

Begin by creating a payment intent. Specify the payment_method_type property as card_present and use the payment_method_id obtained from the previous step. Confirming the Payment Intent transitions its status to requires_action, indicating that the Payment Intent has been sent to the terminal, prompting the customer to complete the payment.

Create a Payment Intent sample request

curl -L '{{PRODUCTION_API_URL}}/v1/payment-intents' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
   "amount": 1000,
   "currency": "usd",
   "payment_method_types": [
      "card_present"
   ],
   "confirm": true,
   "capture_method": "automatic",
   "payment_method_id": "pm_oeWN5ipwtWkF0N2n7t1zs"
}'

Complete the payment

Swipe or tap a payment method on the terminal to complete the payment.

Confirm payment intent success

Create a Webhook EndpointAPI for payment_intent_events to receive updates about the success of the Payment Intent and the associated transaction details.

Certify Your Integration

After completing your integration, you need to certify it by performing specific transactions. If you've implemented additional in-person features such as tip settings or card saving, ensure you test those flows as well.

Complete the following scenarios in Sandbox:

  1. Create and complete 20 card_present payments.
  2. Void 5 card_present payments.
  3. Refund 5 card_present payments.
  4. Partially refund 5 card_present payments.

Once you’ve completed these test transactions, send an email to to have your integration certified.

FAQ

How do I calculate the tip amount?To calculate the tip amount when tips are enabled, subtract the payment_intent.amount from the payment_intent.amount_received.
What payment methods are supported?Card, Apple Pay, Google Pay, and Samsung Pay are supported for in-person payments. HSA/FSA cards are not supported at this time.