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 card machine built by Square. Now developers on any platform can offer in-person payments with Square.

Get started

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 card machine for payments and receipts. It’s built by Square, so it’s secure, reliable, and an entirely fairer way to get paid.