logo

Terminals

NOTE: This API is under active development and subject to change

JustiFi provides a card present solution which allows you to collect a payment via a terminal provider by 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 Payment Intent
  2. Send a payment intent to a terminal
  3. Terminal processes payment async
  4. Handle payment_intent.succeeded event (recommended)
  5. OR poll payment_intents API for status change (optional)

Create a payment intent

Create a Payment Intent with the amount you'd like to capture, and a description of the payment.

Send a payment intent to a terminal

POST to the terminal pay endpoint which will be used to send a your payment intent 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 payment_intent.succeeded event

Create an Event Publisher which publishes payment_intent.succeeded events. This will provide a means to ensure the payment was successful. You can also listen to payment events, for example a payment.failed event will be published each time a payment intent is attempted to be processed but the transaction fails for some reason.

Poll payment_intents API for status change

If you do not have the ability to handle event publishing, you could poll our payment intent API with the id of the payment intent you are processing. Contine to poll until the payment intent status attribute changes. We recommend using an event driven architecture.

Pay via Terminal

Send a payment intent to be processed via terminal, listen for payment_intent events (recommended) or poll payment intent API for payment outcome

Request
header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

id for the payment intent which you want to process via terminal

terminal_id
required
string <uuid>

id of the terminal on which you want to process a transaction

Responses
201

Payment Intent sent to terminal for processing

post/terminals/pay
Request samples
application/json
{
  • "payment_intent_id": "pi_abc123",
  • "terminal_id": "trm_abc123"
}
Response samples
application/json
{
  • "id": "tmses_abc123",
  • "type": "terminal_payment_intent",
  • "data": {
    },
  • "page_info": "string"
}

Refund via Terminal

Send an amount to be refunded via terminal, listen for payment_intent events (recommended) or poll payment intent API for payment outcome

Request
header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

id for the payment intent which you want to refund via terminal

terminal_id
required
string <uuid>

id of the terminal on which you want to process a refund

amount
integer

the amount which you'd like to refund. Omit this variable if you want to refund the original amount

Responses
201

Payment Intent sent to terminal for processing

post/terminals/refund
Request samples
application/json
{
  • "payment_intent_id": "pi_abc123",
  • "terminal_id": "trm_abc123",
  • "amount": 1000
}
Response samples
application/json
{
  • "id": "tmses_abc123",
  • "type": "terminal_payment_intent",
  • "data": {
    },
  • "page_info": "string"
}

List Terminals

Request
header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Responses
200

Successfully list terminals

get/terminals
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Terminal
Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a terminal


get/terminals/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "terminal",
  • "data": {
    },
  • "page_info": "string"
}
Get Terminal Status
Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get terminal status


get/terminals/{id}/status
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "terminal",
  • "data": {
    },
  • "page_info": "string"
}
➔ Next to JustiFi Web Components