Square and Twilio integrate through Square Webhooks and the Twilio Messages API to send SMS payment receipts at the point of sale, appointment reminders before booked services, and payment request links for invoices sent to customers who prefer to pay by mobile. This integration suits retail businesses, salons, and service providers that run Square for point-of-sale and appointment booking and want to add SMS as a communication channel alongside Square's built-in email and Square Messages feature. The connection uses Square's event subscription system to detect payment, booking, and invoice events and routes the relevant customer phone to Twilio for SMS dispatch.
What You Need Before You Start
Create a Square application in the Square Developer Dashboard at developer.squareup.com under Applications, click New Application, name it Twilio SMS Notifier, and copy the Application ID and Personal Access Token from the application's Credentials tab for use in API calls and webhook configuration. Register a Square webhook subscription by calling POST https://connect.squareup.com/v2/webhooks/subscriptions with the Authorization header set to Bearer {accessToken} and a body containing notification_url set to your middleware endpoint and event_types containing payment.completed, booking.created, booking.updated, and invoice.payment_made to capture the key events. Copy the Square webhook signature key from the webhook subscription response under signature_key, as all Square webhook deliveries include an X-Square-Hmacsha256-Signature header that your middleware must verify by computing HMAC-SHA256 of the notification URL concatenated with the raw request body using the signature key. From Twilio, collect your Account SID, Auth Token, and an SMS-capable phone number, and note that Square Customer objects include a phone_number field in E.164 format if the customer was created with a phone, but point-of-sale transactions can complete without linking to a customer record.
Step-by-Step Integration Guide
In your middleware webhook handler, verify the Square signature by computing HMAC-SHA256 with your webhook signature key over the concatenation of your notification_url and the raw request body, Base64-encoding the result, and comparing it against the X-Square-Hmacsha256-Signature header value. For payment.completed events, extract the payment.customer_id from the webhook payload and fetch the customer record by calling GET https://connect.squareup.com/v2/customers/{customerId} with your Bearer token, reading the phone_number field from the response, then dispatch a Twilio SMS receipt containing the payment amount from payment.amount_money.amount divided by 100, the currency from payment.amount_money.currency, and the last 4 digits of the card from payment.card_details.card.last_4. For booking.created events from Square Appointments, extract the customer_id and the start_at timestamp from the booking object, fetch the customer phone, format the start_at ISO 8601 timestamp into a human-readable date and time using the location timezone retrieved from GET https://connect.squareup.com/v2/locations/{locationId}, and send a Twilio confirmation SMS with the appointment date, time, and service name from the booking's appointment_segments array. For invoice.payment_made events, extract the invoice.primary_recipient.customer_id, fetch the customer phone, and send a Twilio payment confirmation SMS with the payment amount and the invoice number from invoice.invoice_number.
Common Issues and How to Fix Them
Square point-of-sale transactions frequently complete without a customer_id in the payment object when the cashier does not look up or create a customer during checkout, causing the customer_id field to be null and the phone lookup to fail. Add a fallback that checks the payment.buyer_email_address field and looks up the customer by email using the Square customers search endpoint with a filter on email_address, and if still no customer is found, log the transaction ID for a batch enrichment process. Square webhook deliveries can arrive out of order when multiple events occur for the same customer in quick succession, and processing a payment.completed event before its associated booking.created event can cause the SMS to reference a booking that your system has not yet recorded. Process each webhook event type independently and avoid cross-referencing event state from different event types in the same middleware invocation to prevent ordering-dependent bugs. Square's phone_number field on Customer objects is stored in E.164 format when created via the API but may be in local format when the customer was created via the Square POS terminal where staff enter it manually. Validate and normalize every phone number using a library before passing to Twilio, rejecting invalid numbers gracefully and logging them to your missing-phone queue rather than attempting to dispatch to a malformed number.
How to Get More from This Integration
Build an appointment reminder sequence by running a daily scheduled job that calls the Square bookings API with the start_at_min filter set to tomorrow and start_at_max set to tomorrow plus 24 hours, fetching each booking's customer phone, and sending a Twilio reminder SMS 24 hours before the appointment time with the location name, service name, and appointment time. Create a Square Invoice payment link SMS by generating a Square invoice via the Square invoices API, publishing it, fetching the public_url from the published invoice response, and sending it to the customer's phone via Twilio SMS for mobile-friendly invoice payment. Add a post-transaction review request by queuing a delayed job at payment.completed time that fires 2 days later, checks that the payment status is still COMPLETED using the Square payments API, and sends a Twilio SMS requesting a Google review with a pre-built short link, timing the request when customer satisfaction is highest. Extend the integration to Square Loyalty by calling the Square loyalty accounts search API with a query on phone_number after a payment.completed event, and if the customer has a loyalty account, including their current point balance in the Twilio SMS receipt to encourage repeat visits.
Conclusion
Square and Twilio together add SMS receipts, appointment reminders, and payment confirmations to your Square-based business without replacing any existing Square workflows. Reach out to Telphi Consulting to build and deploy a Square Twilio SMS integration tailored to your business type.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.