Skip to main content
The Terminal API enables you to create and manage checkout, refund, and action requests for Square Terminal devices. This allows you to build custom point-of-sale experiences that integrate with Square’s hardware.

​
Overview

The Terminal client provides methods for:
  • Creating and managing terminal checkouts for accepting payments
  • Processing refunds through terminal devices
  • Sending custom actions to terminal devices
  • Managing terminal device states

​
Client Initialization

import (
    "context"
    "github.com/square/square-go-sdk/square"
)

client := square.NewClient(
    square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)

​
Methods

​
DismissTerminalAction

Dismisses a Terminal action request if the status and type of the request permits it.
terminal.go:15882
request := &square.DismissTerminalActionRequest{
    ActionID: "action_id",
}
response, err := client.Terminal.DismissTerminalAction(
    context.TODO(),
    request,
)
​
actionID
string
required
Unique ID for the TerminalAction associated with the action to be dismissed.
​
action
TerminalAction
The dismissed terminal action.

​
DismissTerminalCheckout

Dismisses a Terminal checkout request if the status and type of the request permits it.
terminal.go:15943
request := &square.DismissTerminalCheckoutRequest{
    CheckoutID: "checkout_id",
}
response, err := client.Terminal.DismissTerminalCheckout(
    context.TODO(),
    request,
)
​
checkoutID
string
required
Unique ID for the TerminalCheckout associated with the checkout to be dismissed.
​
checkout
TerminalCheckout
The dismissed terminal checkout.

​
DismissTerminalRefund

Dismisses a Terminal refund request if the status and type of the request permits it.
terminal.go:16003
request := &square.DismissTerminalRefundRequest{
    TerminalRefundID: "terminal_refund_id",
}
response, err := client.Terminal.DismissTerminalRefund(
    context.TODO(),
    request,
)
​
terminalRefundID
string
required
Unique ID for the TerminalRefund associated with the refund to be dismissed.
​
refund
TerminalRefund
The dismissed terminal refund.

​
Use Cases

​
Accept In-Person Payments

Use Terminal checkouts to process payments through Square Terminal devices: 
checkout := &square.CreateTerminalCheckoutRequest{
    IdempotencyKey: "unique-key-123",
    Checkout: &square.TerminalCheckout{
        AmountMoney: &square.Money{
            Amount:   1000,  // $10.00
            Currency: square.CurrencyUsd,
        },
        DeviceOptions: &square.DeviceCheckoutOptions{
            DeviceID: "device_id",
        },
    },
}

response, err := client.Terminal.CreateCheckout(context.TODO(), checkout)

​
Process Refunds

Issue refunds directly through terminal devices: 
refund := &square.CreateTerminalRefundRequest{
    IdempotencyKey: "unique-refund-key-456",
    Refund: &square.TerminalRefund{
        PaymentID: "payment_id",
        AmountMoney: &square.Money{
            Amount:   500,  // $5.00
            Currency: square.CurrencyUsd,
        },
        DeviceID: "device_id",
    },
}

response, err := client.Terminal.CreateRefund(context.TODO(), refund)

​
Best Practices

  • Always use idempotency keys to prevent duplicate transactions
  • Handle device unavailability gracefully with timeouts
  • Implement proper error handling for network issues
  • Use dismiss methods to cancel pending requests when needed
  • Monitor terminal device status before initiating requests

Build docs developers (and LLMs) love

Get started for freeTalk to us