关于Square PoS API预授权/预扣费的技术问询

Great question—this is a perfect fit for Square's core features, and you absolutely can build the workflow you're describing: pre-authorizing a card on entry, then charging the actual calculated amount when the user exits. Here's how to break it down:

Key Square Features to Use #

Square supports two critical tools for this unattended scenario:

• Authorization Holds: A temporary hold on a card's funds (no actual charge yet) that you can later capture for the exact amount owed.
• Card on File (CoF): Saving a user's card details securely (compliant with PCI standards) so you can charge it later without re-swiping.

Step-by-Step Workflow #

1. On Entry: Capture Card & Create Pre-Authorization #

When the user swipes their card to gain access:

• Use Square's card reader to get a source_id (tokenized card data—never store raw card info yourself).
• Create a pre-authorized payment by calling the CreatePayment endpoint with autocomplete=false. Set the hold amount to your maximum possible charge (e.g., $100 for a full day of access) to cover any potential stay duration.
• Optional but recommended: Link the card to a Customer profile using the CreateCustomer or UpdateCustomer endpoint to save it as Card on File. This gives you flexibility if you need to re-authorize later (e.g., for extended stays).

Example pre-authorization request:

POST /v2/payments
{
  "source_id": "sq-123-abc-token-from-swipe",
  "amount_money": {
    "amount": 10000, // $100 hold (in cents)
    "currency": "USD"
  },
  "autocomplete": false,
  "customer_id": "sq-cust-456-def",
  "note": "Unattended access pre-authorization"
}

Save the returned payment_id and customer_id in your system, tied to the user's entry timestamp.

2. On Exit: Calculate & Capture the Actual Charge #

When the user swipes to exit:

• Calculate the total owed based on their stay duration.
• Call the CompletePayment endpoint using the payment_id from the pre-authorization. Specify the exact amount you want to charge (it must be less than or equal to the original hold amount).
• If you saved the card as Card on File and the pre-authorization expired (holds typically last 7-30 days depending on the card network), you can create a new payment directly using the saved card ID instead of re-swiping.

Example capture request:

POST /v2/payments/{payment_id}/complete
{
  "amount_money": {
    "amount": 2500, // $25 actual charge (in cents)
    "currency": "USD"
  }
}

Critical Considerations #

• Compliance: You must get explicit user consent to save their card as Card on File (Square enforces this to meet PCI standards). For unattended setups, post a clear notice near the reader explaining that their card will be held and charged based on stay duration.
• Hold Expiry: Pre-authorizations expire—if a user stays longer than the hold's validity period, you'll need to create a new hold before capturing. Plan for this in your system logic.
• Failure Handling: Build fallback logic for cases where the pre-authorization fails (e.g., insufficient funds). You might block access or prompt the user to try another card.
• Testing: Use Square's Sandbox environment to test the full workflow without real charges. You can generate test card numbers to simulate swipes.

Tools to Use #

• Square Connect API for backend logic (creating payments, managing customers)
• Square Terminal or Contactless + Chip Reader for unattended card swipes
• Square PoS SDK if you're building a custom app for the reader

内容的提问来源于stack exchange，提问作者Ray