How to Test Square Integration for Recurring Payments

Prerequisites for Testing Recurring Payments

Before you start testing, you need a Square Developer account and a sandbox environment. The sandbox mimics the live Square API but uses fake money and test card numbers. You also need a test customer profile and a saved card on file (a card ID) to create a subscription.

• Square Developer Account – Sign up at developer.squareup.com. Your sandbox credentials are separate from your production credentials.
• Sandbox Environment – In the Square Developer Dashboard, enable sandbox mode. All API calls to the sandbox endpoint (https://connect.squareupsandbox.com) will not affect real payments.
• Test Card Numbers – Square provides specific card numbers for sandbox testing. For example, use 4111 1111 1111 1111 for a successful payment and 4000 0000 0000 0002 for a declined payment.
• API Credentials – Generate a sandbox access token from the Developer Dashboard. Keep this token secret.

Step 1: Create a Test Customer and Save a Card on File

Recurring payments require a customer profile with a saved card. Use the Customers API to create a test customer in sandbox mode. Then use the Cards API to save a test card to that customer. The response will include a card_id that you use when creating the subscription.

Example API call (simplified):

POST /v2/customers
{"given_name": "Test", "family_name": "User", "email": "test@example.com"}

POST /v2/cards
{"card_nonce": "cnon:test-nonce-ok", "customer_id": "CUSTOMER_ID"}

Square sandbox accepts the nonce cnon:test-nonce-ok to simulate a valid card. The response returns a card_id.

Step 2: Create a Subscription Plan (Catalog Object)

Subscriptions in Square are linked to a subscription plan defined in the Catalog API. Create a plan with a price, billing frequency (e.g., monthly), and a trial period if needed. Use the Catalog API to create a SUBSCRIPTION_PLAN object.

Example plan creation:

POST /v2/catalog/object
{"type": "SUBSCRIPTION_PLAN", "id": "#plan", "subscription_plan_data": {"name": "Test Monthly Plan", "phases": [{"cadence": "MONTHLY", "periods": 12, "amount_money": {"amount": 1000, "currency": "USD"}}]}}

The response includes a plan_variation_id that you use to create the subscription.

Step 3: Create a Subscription

Now create a subscription for the test customer using the saved card and the plan variation ID. Use the Subscriptions API endpoint.

POST /v2/subscriptions
{"customer_id": "CUSTOMER_ID", "location_id": "LOCATION_ID", "plan_variation_id": "PLAN_VARIATION_ID", "card_id": "CARD_ID"}

If successful, the response includes a subscription_id and the status ACTIVE. The subscription will start immediately or on the specified start date.

Step 4: Trigger a Billing Cycle

Square subscriptions automatically bill on the schedule defined in the plan. To test a billing cycle without waiting, you can use the subscription/start or subscription/resume endpoints, or simply wait for the next scheduled charge. For faster testing, create a subscription with a short cadence (e.g., DAILY) or use the sandbox's ability to simulate time by adjusting the subscription's start date to the past.

Note: Square sandbox does not automatically advance time. You can manually trigger a charge by calling the charge endpoint with the card ID, but for true recurring testing, you may need to create a subscription and then use the subscription/event webhook to simulate a payment event.

Step 5: Verify the Payment and Subscription Status

After the billing cycle, check the subscription status using the Retrieve Subscription endpoint. The status should be ACTIVE if the payment succeeded, or PAST_DUE if it failed. Also verify that a payment object was created by calling the Payments API with the subscription ID or customer ID.

Verification checklist:

• Subscription status is ACTIVE after a successful charge.
• A payment record exists with the correct amount and currency.
• Webhook events (if configured) were sent to your endpoint.
• Test a failed payment by using a declined card number (e.g., 4000 0000 0000 0002) and confirm the subscription becomes PAST_DUE.

Testing Failed Payments and Retry Logic

Square automatically retries failed payments based on your account settings. In sandbox, you can simulate a failed payment by using a card that declines. After the first failure, the subscription status changes to PAST_DUE. Square will retry the payment after a few days. You can test the retry by calling the subscription/resume endpoint or by waiting for the automatic retry (which may not happen in sandbox). For thorough testing, manually trigger a retry using the charge endpoint with the same card ID.

Testing Webhooks for Recurring Payments

Webhooks are critical for automating responses to subscription events. Square sends webhook events for subscription.created, subscription.updated, payment.created, and payment.failed. To test webhooks:

1. Set up a webhook endpoint in your application (e.g., /webhook/square).
2. In the Square Developer Dashboard, add the endpoint URL under Webhooks.
3. Create a subscription or trigger a payment in sandbox.
4. Check your server logs to confirm the webhook payload was received.
5. Use a tool like webhook.site to capture and inspect the payload if your endpoint is not yet live.

Square sandbox sends real webhook events, so you can fully test your webhook handling logic.

Common Mistakes and How to Avoid Them

• Using production credentials in sandbox – Always double-check that your API calls go to connect.squareupsandbox.com and use a sandbox token.
• Not saving the card ID – You must save a card on file and use its ID when creating a subscription. A one-time nonce will not work for recurring payments.
• Forgetting to set a location ID – Subscriptions require a valid location ID. In sandbox, use the default location ID provided in your sandbox account.
• Ignoring webhook signatures – Square signs webhook payloads. Verify the signature in your endpoint to ensure the request is from Square.

Key Facts About Square Recurring Payments Testing

Limitations of Sandbox Testing

Square sandbox does not simulate all real-world scenarios. For example, it does not automatically advance time, so you cannot test a monthly subscription's second billing cycle without manual intervention. Also, sandbox does not support all payment methods (e.g., Afterpay, Cash App Pay) that may be available in production. Some webhook events may be delayed or not sent in sandbox. Always perform a final round of testing in production with a small amount of real money before going live.

Frequently Asked Questions

Can I test recurring payments without a real credit card?

Yes. Square sandbox provides test card numbers that simulate successful and failed payments. No real money is involved.

How do I simulate a failed recurring payment?

Use a test card number that Square designates for declines, such as 4000 0000 0000 0002. The subscription will become PAST_DUE.

Do I need to set up webhooks for testing?

Not strictly, but webhooks are essential for automating responses to subscription events. Testing webhooks in sandbox ensures your integration handles them correctly.

Can I test multiple subscriptions for the same customer?

Yes. A single customer can have multiple active subscriptions, each with a different plan or card.

How do I test subscription cancellation?

Use the Cancel Subscription endpoint. The subscription status changes to CANCELED and no further charges occur.

What happens if I use a production token in sandbox?

Your API call will fail with an authentication error. Always use the sandbox token for sandbox endpoints.

Is there a cost to use Square sandbox?

No. Square sandbox is free and does not charge any fees for test transactions.