Common Pitfalls and Solutions

Applies to: Checkout API | Orders API | Payments API

This guide addresses the most common issues developers encounter when implementing the Checkout API, particularly around payment link behavior, Dashboard visibility, and order management.

• Customer confusion: Expecting API links to work multiple times leads to failed payments
• Seller confusion: Sellers looking for API-generated links in Dashboard won't find them
• Integration issues: Treating these as interchangeable breaks payment flows

API-generated payment links (CreatePaymentLink) are single-use only. After successful payment, the link shows a thank you page and cannot process another payment.

• Create a new payment link for each transaction
• Never share the same API-generated link with multiple customers
• If you need reusable links, direct sellers to create them via Square Dashboard

Sellers expect to see all payment links in their Square Dashboard, but API-generated links are never visible there by design.

Build your own management interface if sellers need to:

• View active payment links
• Track payment link usage
• Cancel unused links

• API links are meant for programmatic, one-time transactions
• Showing thousands of single-use links would clutter the Dashboard
• Dashboard links serve a different purpose (reusable, seller-managed)

Orders with fulfillments created via payment links remain in OPEN status even after successful payment. They never automatically transition to COMPLETED.

1. Customer pays successfully → Payment status: COMPLETED ✅
2. Order status remains: OPEN ⚠️
3. Fulfillment cannot be updated programmatically ❌

Current Limitation: Orders must be manually completed in Square Dashboard's Orders Manager.

Workaround options:

1. Educate sellers: Train them to manually complete orders in Orders Manager
2. Track separately: Maintain order completion status in your own system

Deleting payment links has different effects depending on timing, which can lead to unintended data loss or orphaned orders.

When orders created from payment links don't include customer_id, it's hard to associate orders with customers.

1. Check for customer ID on order
2. If not on order, retrieve associated payment
3. Read customer ID on payment

If your integration isn't working as expected, follow these debugging steps to find the most likely cause:

1. Check the URL pattern - Is it /checkout (Dashboard) or /order (API)?
2. Verify single use - Has this payment link already been used?
3. Check Dashboard expectations - Are you looking for API links in Dashboard?
4. Review order status - Are you expecting automatic completion with fulfillments?
5. Examine deletion timing - Are you deleting before or after payment?

✅ DO:

• Create new payment links for each transaction
• Build your own tracking system for API-generated links
• Handle order completion manually or track separately
• Delete payment links after successful payment (if desired)
• Retrieve customer info from payments, not orders

❌ DON'T:

• Expect API payment links to be reusable
• Look for API links in Square Dashboard
• Expect orders with fulfillments to auto-complete
• Assume Dashboard and API links work the same way

• Checkout API Overview - Complete API introduction
• Manage Checkout - CRUD operations for payment links
• Square Order Checkout - Working with orders
• Guidelines and Limitations - Complete limitations reference