In-Person Payments

supports in-person payments on both TSYS and Paysafe, giving you the flexibility to choose the processor and terminal setup that best suits your business needs. This guide will walk you through the process of setting up your integration, from selecting your processor and terminals to handling key payment scenarios.

Design 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 online payments using , the process for in-person payments will be similar.

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}}' \

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}}"
  }'

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"
    }'

Key Scenarios to Handle

Partial authorizations

A Partial Authorization occurs when a payment is attempted for the full amount, but there are insufficient funds to cover it. Only the available amount is captured. It’s important that your software handles this flow, so that the merchant is aware when the full amount is not captured and can choose to create another payment for the difference.

When there is a partial authorization, the API status for the charge is succeeded. Developers should compare either charge.amount_captured or payment_intent.amount_received to the original charge amount to determine how much was actually received.

Same-day refunds

All refunds are initiated through the Create a RefundAPI endpoint.

For same-day refunds on payments made via a Paysafe terminal reader, the refund must be initiated through the terminal reader, which needs to be powered on and connected to the internet. If the terminal is offline, the same-day refund will not go through. Next-day or later refunds can be processed without the terminal being powered on or connected. Make sure your software is set up to handle these refund events: charge.refund.pending and charge.refunded.

Same-day refunds for payments made through TSYS terminal readers are not processed through the terminal.

Certify Your Integration

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

The developer tasks below are required to be completed in before launching your card-present solution with :

• Process payments:Create and complete 20 card-present payments.
• Configure webhooks:Configure and listen to refund webhooks.
• Process same-day refund:Process a same-day refund for 5 card-present payments. For Paysafe terminal readers, ensure that your software can handle charge.refund.pending and charge.refunded webhooks.
• Process next-day or later refund:Process a next-day or later refund for 5 card-present payments.
• Process next-day partial refunds:Partially refund 5 card-present payments.
• Create a partial authorization:Create at least one partial authorization. Trigger amount = $37.57 and only works for Paysafe terminal readers.
• Cancel a payment:Cancel at least one card-present payment by canceling the payment on the terminal reader and process the result.
• Cancel an incomplete payment:Cancel at least one incomplete card-present payment with the Cancel a Payment IntentAPI endpoint and process the result.
• Handle lost webhooks:Ensure that your software can handle lost payment_intent.succeeded webhooks.