Checkout API: definitive cancellation barrier and CreatePaymentLink idempotency retention

[pierluc62]

Hello Square Developer Support,

We are integrating single-use Checkout API payment links with limited-capacity appointment slots. We need to avoid making a slot available again while a previously submitted payment could still complete. This is a technical API question; no customer information, credentials, or live transaction details are included.

1. Does a successful DeletePaymentLink response with the matching cancelled_order_id, followed by RetrieveOrder returning CANCELED, definitively prevent a payment submitted before deletion from later becoming COMPLETED? If not, which supported operation or provider state establishes a definitive cancellation barrier?

2. How can we exhaustively reconcile all in-progress payments belonging to that order before making the appointment slot available again? ListPayments is eventually consistent and has no order_id filter. Does Order.tenders include every payment authorization already in progress, or is a different reconciliation method required?

3. What is the guaranteed retention period for a CreatePaymentLink idempotency key? If the creation response is lost, how should we recover the original link without risking a second payable link after the key expires?

In disposable Sandbox tests, deleting an unpaid link returned cancelled_order_id and the order became CANCELED with tenders omitted. Deleting a link after a successful simulated payment returned only the link id, while the order stayed OPEN with a tender and the payment stayed COMPLETED. These tests do not establish the behavior of an authorization already in flight during deletion.

Related discussions reviewed:

DeletePaymentLink not working properly sometimes

Hello, We are using the delete payment link api endpoint, when a user wants to cancel the payment session. It’s usually works, but sometimes doesn’t work as expected. We get HTTP 200 OK to the DELETE api call, but the response doesn’t contain the order id, only the payment link id. After this the payment link is still alive, the order is still in PROPOSED state. In this cases we can call the DELETE payment link endpoint multiple times, we always get the same answer. What we noticed: its always…

Delete Payment Link API didn't return the cancelled_order_id and the link didn't expire

Hi, We’ve encountered a case where our customer was able to complete a payment even after the payment link was deleted using the Delete Payment Link API: According to the documentation, the API response should include two pieces of information: → The ID of the deleted payment link → The cancelled order ID (cancelled_order_id) But in this case, we only received the payment link ID in the response — the cancelled order ID was missing. My questions: → Why was the cancelled_order_id not r…

These discuss missing cancelled_order_id. Our question is specifically the definitive in-flight payment guarantee when cancelled_order_id DOES match and the order is CANCELED.

We currently keep uncertain payment attempts and appointment slots protected. Could you confirm the supported safe cancellation and recovery procedure, and whether the guarantees are the same in Sandbox and Production?

Thank you.

[helner-square]

Hi @pierluc62,

Hi, thanks for the detailed write-up, here is what we are able to confirm based on your questions

Canceling a known approved payment: For a payment in APPROVED status, use CancelPayment and verify that the response returns the intended payment with status = CANCELED.

In Payments API:

• The payment initially returns APPROVED, with card status AUTHORIZED.
• Explicit cancellation returns CANCELED, with card status VOIDED.
• Retrieving the payment confirms the canceled state.
• A subsequent CompletePayment request is rejected because the payment was canceled.

This provides a payment-level cancellation barrier for that specific payment.

Reading Order.tenders

• The approved payment appeared in Order.tenders with its matching payment_id.
• After cancellation, the tender remained, with card status VOIDED.

A tender’s presence therefore does not mean payment completed. Use its payment_id with GetPayment to check the current payment status.

Payment-link deletion results

Confirmed:

• Deleting an unpaid link returned the matching cancelled_order_id; the retrieved order became CANCELED.
• Deleting a link after a successful simulated payment returned only the link ID. The order remained OPEN, its tender remained present, and the payment stayed COMPLETED.

For tracking, persist your link and order IDs, use order.reference_id to associate the order with your booking attempt, and correlate payment notifications using Payment.order_id. Confirm successful payment through Payment.status = COMPLETED, rather than the order’s OPEN state.

[pierluc62]

Thank you for confirming the payment-level cancellation barrier and the need to re-read the specific payment status. We have also reproduced authorization, explicit cancellation, and rejection of subsequent completion in Sandbox only. This is not a production or booking-integration validation.

Two parts of the original question remain open:

1. Does Square provide a documented guarantee that, after deleting a Checkout payment link and re-reading its matching order as CANCELED, no previously initiated checkout can subsequently produce a successful payment for that order? If not guaranteed, please confirm that we should not use link deletion alone as a barrier for releasing a booking slot.
2. What is the documented retention period for CreatePaymentLink idempotency keys? If Square provides no contractual minimum or published duration, please confirm that an application must not assume a safe retry window after an unknown result.

We are pursuing the server-controlled Payments API path with an identified payment while retaining a slot whenever an outcome is uncertain. We need the answers above to close the Checkout alternative accurately, not to infer a broader guarantee from the successful Sandbox tests.

Thanks,
Pierre-Luc
Goelan bleu