SQUARE TERMINAL API

Connect your app to Square Terminal for in-person payments.

Whether you’re building a point-of-sale app or business management system, you can wirelessly connect your app to Square Terminal, the all-in-one credit card machine built by Square. Now developers on any platform can offer in-person payments with Square.


Step 1: Pair your app with Square Terminal.

Call the Devices API to generate a Device Code and display it to your user. Once your user logs in to Terminal using the code, a webhook event (which contains the device_id) will notify you that the device is ready to receive a checkout request from your system.

body = {
idempotency_key: '{{RANDOM_STRING}}',
 device_code: {
   name: 'Counter 1',
   product_type: 'TERMINAL_API',
   location_id: 'B5E4484SHHNYH',
 }
}

client.devices.create_device_code(body: body)

Step 2: Send a payment amount from your app to Terminal.

Call Create Terminal Checkout with a payment amount. When you do this, the device will prompt the buyer for payment.

body = {
 idempotency_key: '{{RANDOM_STRING}}',
 checkout: {
   amount_money: {
     amount: 2610,
     currency: 'EUR'
   },
   reference_id: 'id123',
   note: 'A brief note',
   device_options: {
     device_id: '{{DEVICE_ID}}'
   }
 }
}

client.terminal.create_terminal_checkout(body: body)

Step 3: Close the sale in your app.

After the payment succeeds, you’ll be notified via webhooks so you can close the sale on your end.

{
  "merchant_id": "7NZR...NPC",
  "type": "terminal.checkout.updated",
  "event_id": "7229a692-def5-4a7e-b4f3-80638aa2f24d",
  "created_at": "2020-04-10T14:43:55.262Z",
  "data": {
    "type": "checkout.event",
    "id": "dhgENdnFOPXqO",
    "object": {
      "checkout": {
        "amount_money": {
          "amount": 2610,
          "currency": "EUR"
        },
        "app_id": "sq0idp-734M...nm6g",
        "created_at": "2020-04-10T14:43:55.262Z",
        "deadline_duration": "PT5M",
        "device_options": {
          "device_id": "{{DEVICE_ID}}",
          "skip_receipt_screen": false,
          "tip_settings": {
            "allow_tipping": false
          }
        },
        "id": "dhgENdnFOPXqO",
        "note": "A brief note",
        "payment_ids": [
           "dgzrZT...PouaB"
         ],
         "reference_id": "id123",
         "status": "COMPLETED",
         "updated_at": "2020-04-10T14:44:06.039Z"
      }
    }
  }
}

Why Square Terminal?

Square Terminal is an all-in-one credit card machine for payments and receipts. It’s built by Square, so it’s secure, reliable, and an entirely fairer way to get paid.

Let Square handle payments for you.

To learn more, check out the Terminal API Documentation.