JustiFi

JustiFi Terminals API

JustiFi provides a card present solution which allows you to collect a payment via a terminal provider via one of our technology partners. To collect a payment via terminal, you must first ensure you ask the JustiFi team to enable the card present feature for your platform. Next, we will work to provision and configure terminals for your sub accounts. Once you have configured a terminal, you must complete the following steps to complete a payment: 1. Create a Checkout 2. Send a checkout to a terminal 3. Terminal processes payment async 4. Handle checkout.completed event (recommended) 5. OR poll checkouts API for status change (optional) ### Create a checkout [Create a Checkout](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout) with the amount you'd like to capture, and a description of the payment. ### Send a checkout to a terminal [POST to the terminal pay endpoint](https://docs.justifi.tech/api-spec#tag/Terminals/operation/payTerminal) which will be used to send your checkout to a terminal for processing. This process can take some time as it requires customer interaction. For this reason, the API will return immediately but the process is asynchronusly happening on a terminal. ### Terminal processes payment async At this point, the process is handed over to the terminal to complete. Once the payment transaction is completed, we will publish an event for you to continue the process and take further action, as noted in the next step. ### Handle checkout.completed event Create an [Event Publisher](https://docs.justifi.tech/api-spec#tag/Events) which publishes [`checkout.completed` events](https://docs.justifi.tech/api-spec#tag/Events/operation/checkoutEvent). This will provide a means to ensure the payment was successful. You can also listen to checkout completion events, for example a checkout.completion.failed event will be published each time a card is attempted to be processed but the transaction fails for some reason. ### Poll checkouts API for status change If you do not have the ability to handle event publishing, you could poll our checkout API with the id of the checkout you are processing. Contine to poll until the checkout status attribute changes. We recommend you use the checkout events instead of this approach.

Documentation GitHub OpenAPI

Operations 6

POST /terminals/pay Pay via Terminal #

GET /terminals List Terminals #

GET /terminals/{id} Get a Terminal #

PATCH /terminals/{id} Update a Terminal #

GET /terminals/{id}/status Get Terminal Status #

POST /terminals/{id}/identify Identify Terminal #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/justifi-terminals-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Terminals API
  termsOfService: https://justifi.ai/terms-and-conditions
  x-logo:
    url: https://justifi-brand-assets.s3.us-east-2.amazonaws.com/justifi-light-bg.png
  contact:
    email: api-development@justifi.ai
servers:
- url: https://api.justifi.ai/v1
  description: JustiFi API
tags:
- name: Terminals
  description: JustiFi provides a card present solution which allows you to collect a payment via a terminal provider via one of our technology partners.
paths:
  /terminals/pay:
    post:
      summary: Pay via Terminal
      description: Send a checkout to be processed via terminal, listen for checkout events (recommended) or poll checkout API for payment outcome
      operationId: payTerminal
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                payment_intent_id:
                  type: string
                  format: uuid
                  example: pi_abc123
                  description: '(deprecated, use checkout id) id for the payment intent which you want to process via terminal

                    '
                checkout_id:
                  type: string
                  format: uuid
                  example: cho_abc123
                  description: 'id of the checkout which you want to process via terminal

                    '
                terminal_id:
                  type: string
                  format: uuid
                  example: trm_abc123
                  description: 'id of the terminal on which you want to process a transaction

                    '
              required:
              - checkout_id
              - terminal_id
      responses:
        '201':
          description: Checkout sent to terminal for processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: terminal_sessions
                    id:
                      example: tses_FQz6I0hMTrcU9Ur7TpOPZ
                    data:
                      properties:
                        id:
                          type: string
                          format: uuid
                          example: tses_FQz6I0hMTrcU9Ur7TpOPZ
                        session_type:
                          type: string
                          example: payment
                        status:
                          type: string
                          example: created
                        payment_id:
                          type: string
                          format: uuid
                          example: py_abc123
                        payment_intent_id:
                          type: string
                          format: uuid
                        terminal_id:
                          type: string
                          format: uuid
                          example: trm_abc123
                        account_id:
                          type: string
                          format: uuid
                          example: acc_abc123
                        platform_account_id:
                          type: string
                          format: uuid
                          example: acc_abc123
                        checkout_id:
                          type: string
                          format: uuid
                          example: cho_abc123
  /terminals:
    get:
      summary: List Terminals
      operationId: listTerminals
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/sub-account'
      - in: query
        name: status
        schema:
          type: string
          enum:
          - connected
          - disconnected
          - unknown
          - pending_configuration
          - archived
        required: false
        example: active
        description: 'filter records by the terminal status. Accepts multiple comma separated status values.

          '
      - in: query
        name: terminal_id
        schema:
          type: string
        required: false
        example: trm_abc123
        description: 'filter records by terminal id

          '
      - in: query
        name: provider_id
        schema:
          type: string
        required: false
        example: '23456789'
        description: 'filter records by provider id, also called device id (DID). Accepts multiple comma separated provider ids.

          '
      - in: query
        name: terminal_order_id
        schema:
          type: string
        required: false
        example: tord_123xyz
        description: 'filter records by terminal order id

          '
      - in: query
        name: verified_after
        schema:
          type: string
          format: date-time
        required: false
        example: '2024-01-01T00:00:00Z'
        description: 'filter records which were verified after the date and time (UTC) specified. Dates without time specified will default to 00:00:00

          '
      - in: query
        name: verified_before
        schema:
          type: string
          format: date-time
        required: false
        example: '2024-01-01T00:00:00Z'
        description: 'filter records which were verified before the date and time (UTC) specified. Dates without time specified will default to 00:00:00

          '
      - in: query
        name: verified_on
        schema:
          type: string
          format: date
        required: false
        example: '2024-01-01'
        description: 'filter records which were verified on the date specified between 00:00:00 and 23:59:59 (UTC)

          '
      responses:
        '200':
          description: Successfully list terminals
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/Terminal'
  /terminals/{id}:
    get:
      summary: Get a Terminal
      operationId: getTerminal
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a terminal
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: terminal
                    data:
                      $ref: '#/components/schemas/Terminal'
    patch:
      summary: Update a Terminal
      operationId: updateTerminal
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                nickname:
                  type: string
                  description: terminal nickname
                  example: My Favorite Terminal
      responses:
        '200':
          description: Successfully update a terminal
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: terminal
                    data:
                      $ref: '#/components/schemas/Terminal'
  /terminals/{id}/status:
    get:
      summary: Get Terminal Status
      operationId: getTerminalStatus
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get terminal status
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: terminal
                    data:
                      $ref: '#/components/schemas/TerminalStatus'
  /terminals/{id}/identify:
    post:
      summary: Identify Terminal
      operationId: postIdentifyTerminal
      description: 'This API will attempt to display the nickname or serial number on

        the screen of the given terminal for 20 seconds.'
      tags:
      - Terminals
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '204':
          description: The request was sent to the terminal
components:
  schemas:
    Envelope:
      type: object
      properties:
        id:
          description: the object id, also found in the data object
          type: string
          format: uuid
          example: prefix_xyz (same as id of data object)
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the attributes for the object
          type: object
        page_info:
          description: information for cursor style pagination, is null for single records
          type: null
    Terminal:
      type: object
      properties:
        id:
          description: unique terminal id
          type: string
          example: trm_abc123
        account_id:
          description: id of the account associated with the terminal
          type: string
          format: uuid
          example: acc_123xyz
        platform_account_id:
          type: string
          format: uuid
          description: id of the platform account associated with the terminal
          example: acct_789abc
        provider:
          description: terminal provider
          type: enum[verifone verifone_simulator]
          example: verifone
        status:
          description: last known terminal status. For performance reasons, this field is only updated when you check the terminal status via API.
          type: enum[connected, disconnected, unknown, pending_configuration, archived]
          example: disconnected
        provider_id:
          description: terminal identification from provider, also called device id (DID)
          type: string
          example: '23456789'
        provider_serial_number:
          description: serial number of the terminal device. Present after device was configured by entering the provider id (also called device id) into device.
          type: string
          example: 888-222-444
        nickname:
          description: terminal custom identification, can be added and modified via update terminal API
          type: string
          example: My Favorite Terminal
        verified_at:
          type: string
          format: date-time
          example: '2024-01-01T15:00:00Z'
        model_name:
          type: string
          description: name of terminal device model
          example: e285
        terminal_order_created_at:
          type: string
          format: date-time
          description: timestamp of when the terminal order was placed
          example: '2024-01-01T15:00:00Z'
        status_last_requested_at:
          type: string
          format: date-time
          description: timestamp of last terminal status request
          example: '2024-01-01T15:00:00Z'
        created_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
    Envelope-list:
      type: object
      properties:
        id:
          description: the object id
          type: number
          example: 1
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the list of objects
          type: array
        page_info:
          description: information for cursor style pagination
          $ref: '#/components/schemas/PageInfo'
    PageInfo:
      type: object
      properties:
        end_cursor:
          description: the encoded id of the last record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd
        has_next:
          description: true if the collection contains records following the current list
          type: boolean
          default: false
        has_previous:
          description: true if the collection contains records ahead of the current list
          type: boolean
          default: false
        start_cursor:
          description: the encoded id of the first record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd
    TerminalStatus:
      type: object
      properties:
        id:
          description: unique terminal id
          type: string
          example: trm_abc123
        status:
          description: current terminal status
          example: CONNECTED
          type: string
        last_date_time_connected:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        last_date_time_active:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
  parameters:
    id-path:
      in: path
      name: id
      schema:
        type: string
        format: uuid
      required: true
    authorization-header:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
      example: Bearer {access_token}
      description: the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token)
    sub-account:
      in: header
      name: Sub-Account
      schema:
        type: string
      required: false
      example: acc_123xyz
      description: 'the id of the [sub account](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) that this request applies to

        '
x-tagGroups:
- name: Authorization
  tags:
  - API Credentials
  - Web Component Tokens
- name: For Platforms
  tags:
  - Sub Accounts
  - Platform Wallet Accounts
  - Onboarding via Component
  - Hosted Onboarding
  - Onboarding via API
  - Fee Configurations
  - Proceeds
  - Reports
- name: Payment Resources
  tags:
  - Payments
  - Payment Methods
  - Tokenize via Component
  - Payment Method Groups
  - Refunds
  - Disputes
  - Payouts
  - Payout Holds
  - Balance Transactions
  - Ach Return Fees
  - Payment Method Migration
- name: Checkout Resources
  tags:
  - Checkouts
  - Checkout via Component
  - Checkout via API
- name: Insurance Resources
  tags:
  - Bind Insurance
- name: Entity Resources
  tags:
  - Business
  - Identity
  - Address
  - Document
  - Bank Account
  - Terms and Conditions
  - Provisioning
- name: Card Present Resources
  tags:
  - Terminals
  - Terminals Orders
- name: Libraries
  tags:
  - JustiFi Web Components
  - JustiFi SDK
- name: Event Publishing
  tags:
  - Events
  - Webhook Delivery