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
- Design your integration
- Order developer terminals
- Integrate in-person payments
- 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.
- On-device tipping
- Receipts
- Card tokenization
- Manual capture
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:
- Email support to request an Activation Code.
- 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:
- Create and complete 20
card_present
payments. - Void 5
card_present
payments. - Refund 5
card_present
payments. - 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 thepayment_intent.amount
from the payment_intent.amount_received
.