In-Person Payments

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 from Paydude. 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 Paydude, the process for in-person payments will be similar.

curl -L https://api.sandbox-paymentsonline.io/v1/terminal-readers/{{TERMINAL_ID}} \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'payments-api-key: {{SECRET_KEY}}' \

curl -L 'https://api.sandbox-paymentsonline.io/v1/payment-methods' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'payments-api-key: {{SECRET_KEY}}' \
    -d '{
    "type": "card_present",
    "terminal_reader_id": "{{TERMINAL_READER_ID}}"
  }'

curl -L 'https://api.sandbox-paymentsonline.io/v1/payment-intents' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'payments-api-key: {{SECRET_KEY}}' \
    -d '{
    "amount": 1000,
    "currency": "usd",
    "payment_method_types": [
      "card_present"
    ],
    "confirm": true,
    "capture_method": "automatic",
    "payment_method_id": "{{PAYMENT_METHOD_ID}}"
    }'

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. Same-day refunds must be for the full payment amount. A payment can be partially refunded the next day, after it has batched and settled.

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 Paydude:

• Process payments:Create and complete 20 card-present payments.
• Configure webhooks:Configure and listen to refund 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.
• 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.