Physical Terminals

Overview

Basys Physical Terminals provide a comprehensive solution for processing in-person, card-present transactions. This guide walks you through the essential steps to interact with Basys Physical Terminals using our REST APIs. Follow these steps to quickly get started with integrating this solution with your application.

Prerequisites

Before proceeding with this guide, ensure you have:

  • An active Basys production environment account

  • At least one test physical terminal configured to your production gateway

  • Access to IQPro+

  • An application created in IQPro+ and integration credentials (client ID and secret)

  • Although not required, we recommend using Postman to become familiar with our APIs

  • Read our Authorization page prior to this proceeding

If you need assistance with onboarding or setting up any prerequisites, please contact Basys Integration Support:

Authentication

All API requests require OAuth 2.0 authentication using the client credentials flow.

Obtaining an Access Token

POST <https://account.basyspro.com/account.basyspro.com/B2C_1A_IQPROV2_INTEGRATOR/oauth2/v2.0/token>

Request Body Properties:

  • grant_type: client_credentials

  • client_id: Your client ID

  • client_secret: Your client secret

  • scope: https://account.basyspro.com/{tenant-id}/.default

Response:

{ 
    "access_token": "eyJ0eXAi...", 
    "expires_in": 3600,
    "token_type": "Bearer" 
}

Next: Store this access token securely — you'll need it for all subsequent API calls — but it will expire after two hours so be prepared to retrieve a new access token as needed.

Core Integration Flow

1. Retrieve Gateway Information

First, get your merchant’s gateway ID which is required for terminal operations.

GET <https://api.basyspro.com/iqsaas/v1/api/gateway> 
Authorization: Bearer {access_token}

Next: Store the gatewayId, provided in the response for future requests. This represents the merchant/business.

2. List Available Terminals

Using the gatewayId, retrieve all terminals associated with your gateway:

GET <https://api.basyspro.com/iqsaas/v1/api/gateway/{gatewayId}/terminal?offset=1&limit=100> 
Authorization: Bearer {access_token}

This endpoint returns details about your terminals including:

  • Terminal ID

  • Serial number

  • Model

  • Current status

Next: Store the terminalIdprovided in the response to specify which terminal to accept the payment on.

3. Initiate a Payment

To process a payment, create a payment intent by specifying the gatewayId and terminalId as URL parameters.

POST <https://api.basyspro.com/iqsaas/v1/api/gateway/{gatewayId}/terminal/{terminalId}/command/payment-intent> 
Authorization: Bearer {access_token}
Body:
{     
    "transactionId": "{{$guid}}",
    "tenderType": ["Unknown"],
    "transactionType": "Sale",
    "remit": {  
        "baseAmount": 0,
        "taxAmount": 0,
        "taxExempt": true,
        "currencyCode": "USD",
        "total": 0.25
    }
}

Key fields:

  • transactionId: Unique identifier for the transaction (can use a GUID)

  • tenderType: Payment method (“Unknown”, “Eft”, “EBTCash”, or “SnapFSA”)

  • transactionType: Transaction type ("Sale", “Authorize” or “Credit”)

  • remit: Payment details including:

    • baseAmount: Base transaction amount before tax

    • taxAmount: Tax amount

    • taxExempt: Boolean indicating if transaction is tax exempt

    • currencyCode: Three-letter currency code (e.g., "USD")

    • total: Total transaction amount

Payment Intent Response

You will receive an asynchronous response containing the transactionIdbefore the payment flow between the customer and device completes.

Next: use the transactionId to retrieve the transaction status.

4. Retrieve the Transaction Status

After creating a payment intent, use the transactionId to check its status and whether it was successful or not:

GET <https://api.basyspro.com/iqsaas/v1/api/gateway/{gatewayId}/terminal/{terminalId}/transaction/{transactionId}> 
Authorization: Bearer {access_token}

It is our recommended strategy to leverage our transaction webhook functionality to listen for transaction activity. However, if you are unable to support an endpoint to consume webhooks you can implement a polling strategy mentioned in the Best Practices -> Transaction Timing section below.

5. Void or Reverse a Transaction

To void a transaction:

PUT <https://api.basyspro.com/iqsaas/v1/api/gateway/{gatewayId}/transaction/{transactionId}/void> 
Authorization: Bearer {access_token}

This endpoint allows you to void (cancel) a transaction that has been successfully processed.

Note that voids can only be performed on transactions that haven't been settled, and settlement automatically occurs twenty five minutes after the transaction has been successfully processed.

If a transaction has already settled, then you will need to create a refund instead.

Best Practices

  1. Error Handling

    • Always check HTTP status codes

    • Implement proper retry logic for network failures

    • Store transaction IDs for reconciliation

  2. Security

    • Never expose your client credentials

    • Implement client-side encryption for sensitive data

  3. Transaction Management

    • Generate unique guids for value of transactionId

    • Keep transaction logs for reconciliation

  4. Transaction Timing

    • The payment intent endpoint returns a transactionId asynchronously. We recommend implementing a polling strategy with exponential backoff, starting at 2-second intervals, for up to 180 seconds (3 minutes) to ensure reliable capture of the transaction result. Most transactions complete significantly faster, but this maximum window accounts for edge cases and potential processing delays.

    • Our system has a maximum total processing window of 169 seconds, which accounts for the following maximum timeout values across our processing chain:

      • Initial terminal communication: 10 seconds

      • Terminal inactivity timeout: 60 seconds

      • Tokenization processing: 59 seconds

      • Payment processing: 40 seconds

Support

For additional support:

Next Steps

After implementing the basic integration:

  1. Add support for additional transaction types that your merchants may require.

  2. Make sure to handle errors and edge cases and capture logs within your implementation.

  3. Test your implementation thoroughly.

Available Devices and Hardware Specifications:

PAX A920 and A920Pro:

  • Chip & PIN, NFC Contactless, and Magnetic Stripe readers

  • “PIN on glass” for PIN entry

  • 4G LTE, WiFi, and Ethernet connectivity

  • 5.5" touchscreen (A920Pro) or 5.0” touchscreen (A920)

  • Embedded high speed printer

  • PCI PTS 5.x SRED

  • Cortex A53 processor

  • 5MP front + 8MP rear camera

  • 5150mAh / 3.7V long-lasting battery

Support for additional PAX devices coming in 2025 — see iqpro.com for more details.