popertots
12af3af3b3
Add StatusCode/Category/Field to squareAPIError and an IsNotFound helper so 400/401/404/429/5xx are distinguishable structurally instead of by substring. Validate cnon:/ccof: token prefixes in createPayment/createCardOnFile (PCI parity with the mock). Reject ccof charges without customer_id in the mock so dev parity catches the production bug. Emit Deadline as the RFC 3339 duration (PT5M) and correct the deprecated-comment.
884 lines
31 KiB
Go
884 lines
31 KiB
Go
package square
|
|
|
|
import (
|
|
"bytes"
|
|
"context"
|
|
"crypto/sha256"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"log"
|
|
"net/http"
|
|
"net/url"
|
|
"os"
|
|
"strings"
|
|
"time"
|
|
)
|
|
|
|
// ErrCheckoutPending is returned by GetCheckout when a terminal checkout has
|
|
// not yet completed. Handlers use errors.Is(err, ErrCheckoutPending) rather
|
|
// than string comparison, so behaviour is identical across the mock and the
|
|
// real HTTP client.
|
|
var ErrCheckoutPending = errors.New("checkout pending")
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Square REST API constants.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
const (
|
|
squareSandboxURL = "https://connect.squareupsandbox.com"
|
|
squareProductionURL = "https://connect.squareup.com"
|
|
squareAPIVersion = "2026-05-20"
|
|
defaultHTTPTimeout = 30 * time.Second
|
|
)
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// HTTP client — shared by ProdClient (!dev) and devProdClient (dev).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
type httpClient struct {
|
|
baseURL string
|
|
token string
|
|
locationID string
|
|
deviceID string
|
|
http *http.Client
|
|
}
|
|
|
|
func newHTTPClient() *httpClient {
|
|
env := os.Getenv("SQUARE_ENVIRONMENT")
|
|
baseURL := squareSandboxURL
|
|
if env == "production" {
|
|
baseURL = squareProductionURL
|
|
}
|
|
return &httpClient{
|
|
baseURL: baseURL,
|
|
token: os.Getenv("SQUARE_ACCESS_TOKEN"),
|
|
locationID: os.Getenv("SQUARE_LOCATION_ID"),
|
|
deviceID: os.Getenv("SQUARE_TERMINAL_DEVICE_ID"),
|
|
http: &http.Client{Timeout: defaultHTTPTimeout},
|
|
}
|
|
}
|
|
|
|
func (c *httpClient) doJSON(ctx context.Context, method, path string, body, target any) error {
|
|
if c.token == "" {
|
|
return fmt.Errorf("square: SQUARE_ACCESS_TOKEN is not set")
|
|
}
|
|
var reqBody []byte
|
|
if body != nil {
|
|
var err error
|
|
reqBody, err = json.Marshal(body)
|
|
if err != nil {
|
|
return fmt.Errorf("square: marshal request: %w", err)
|
|
}
|
|
}
|
|
url := c.baseURL + path
|
|
req, err := http.NewRequestWithContext(ctx, method, url, bytes.NewReader(reqBody))
|
|
if err != nil {
|
|
return fmt.Errorf("square: create request: %w", err)
|
|
}
|
|
req.Header.Set("Content-Type", "application/json")
|
|
req.Header.Set("Square-Version", squareAPIVersion)
|
|
req.Header.Set("Authorization", "Bearer "+c.token)
|
|
|
|
resp, err := c.http.Do(req)
|
|
if err != nil {
|
|
return fmt.Errorf("square: %s %s: %w", method, path, err)
|
|
}
|
|
defer resp.Body.Close()
|
|
|
|
respBody, err := io.ReadAll(resp.Body)
|
|
if err != nil {
|
|
return fmt.Errorf("square: read response: %w", err)
|
|
}
|
|
if resp.StatusCode >= 300 {
|
|
var errResp struct{ Errors []SquareError `json:"errors"` }
|
|
if json.Unmarshal(respBody, &errResp) == nil && len(errResp.Errors) > 0 {
|
|
se := errResp.Errors[0]
|
|
msg := fmt.Sprintf("square: %s %s: [%s/%s] %s (field: %s)", method, path, se.Category, se.Code, se.Detail, se.Field)
|
|
return &squareAPIError{
|
|
Code: se.Code,
|
|
Detail: se.Detail,
|
|
Category: se.Category,
|
|
Field: se.Field,
|
|
StatusCode: resp.StatusCode,
|
|
err: errors.New(msg),
|
|
}
|
|
}
|
|
return fmt.Errorf("square: %s %s: HTTP %d: %s", method, path, resp.StatusCode, string(respBody))
|
|
}
|
|
if target != nil && len(respBody) > 0 {
|
|
if err := json.Unmarshal(respBody, target); err != nil {
|
|
return fmt.Errorf("square: unmarshal response: %w", err)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Square JSON types — exact wire-format match with Square's REST API.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
type sqMoney struct {
|
|
Amount int64 `json:"amount"`
|
|
Currency string `json:"currency"`
|
|
}
|
|
|
|
// --- Payment types ---
|
|
|
|
type sqCreatePaymentRequest struct {
|
|
SourceID string `json:"source_id"`
|
|
IdempotencyKey string `json:"idempotency_key"`
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
Autocomplete *bool `json:"autocomplete,omitempty"`
|
|
LocationID string `json:"location_id,omitempty"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
CustomerID string `json:"customer_id,omitempty"`
|
|
Note string `json:"note,omitempty"`
|
|
TipMoney *sqMoney `json:"tip_money,omitempty"`
|
|
VerificationToken string `json:"verification_token,omitempty"`
|
|
BuyerEmailAddress string `json:"buyer_email_address,omitempty"`
|
|
}
|
|
|
|
type sqCreatePaymentResponse struct {
|
|
Payment sqPayment `json:"payment"`
|
|
}
|
|
|
|
type sqPayment struct {
|
|
ID string `json:"id"`
|
|
Status string `json:"status"`
|
|
TotalMoney sqMoney `json:"total_money"`
|
|
TipMoney *sqMoney `json:"tip_money,omitempty"`
|
|
SourceType string `json:"source_type"`
|
|
CardDetails *sqCardDetails `json:"card_details,omitempty"`
|
|
LocationID string `json:"location_id"`
|
|
OrderID string `json:"order_id,omitempty"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
CustomerID string `json:"customer_id,omitempty"`
|
|
BuyerEmail string `json:"buyer_email_address,omitempty"`
|
|
ReceiptNumber string `json:"receipt_number,omitempty"`
|
|
ReceiptURL string `json:"receipt_url,omitempty"`
|
|
ProcessingFee []sqFee `json:"processing_fee,omitempty"`
|
|
CreatedAt string `json:"created_at"`
|
|
UpdatedAt string `json:"updated_at,omitempty"`
|
|
}
|
|
|
|
type sqCardDetails struct {
|
|
Card sqCard `json:"card"`
|
|
EntryMethod string `json:"entry_method"`
|
|
CVVStatus string `json:"cvv_status,omitempty"`
|
|
AVSStatus string `json:"avs_status,omitempty"`
|
|
}
|
|
|
|
type sqCard struct {
|
|
ID string `json:"id"`
|
|
CardBrand string `json:"card_brand"`
|
|
Last4 string `json:"last_4"`
|
|
ExpMonth int `json:"exp_month"`
|
|
ExpYear int `json:"exp_year"`
|
|
CardholderName string `json:"cardholder_name,omitempty"`
|
|
Fingerprint string `json:"fingerprint"`
|
|
CustomerID string `json:"customer_id,omitempty"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
Enabled bool `json:"enabled"`
|
|
Version int64 `json:"version"`
|
|
CreatedAt string `json:"created_at"`
|
|
}
|
|
|
|
// sqFee matches Square's processing_fee object. The fee amount lives in
|
|
// amount_money.amount, NOT a top-level amount field — reading the wrong shape
|
|
// made every PaymentResult.Fees 0 against the real API (N-9).
|
|
type sqFee struct {
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
Type string `json:"type"`
|
|
}
|
|
|
|
// --- Terminal Checkout types ---
|
|
|
|
type sqTerminalCheckoutRequest struct {
|
|
IdempotencyKey string `json:"idempotency_key"`
|
|
Checkout sqTerminalCheckoutPayload `json:"checkout"`
|
|
}
|
|
|
|
type sqTerminalCheckoutPayload struct {
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
Note string `json:"note,omitempty"`
|
|
CustomerID string `json:"customer_id,omitempty"`
|
|
DeviceOptions *sqDeviceOptions `json:"device_options,omitempty"`
|
|
}
|
|
|
|
// sqTipSettings maps to Square's DeviceCheckoutOptions.tip_settings object
|
|
// (nested INSIDE device_options — a top-level tip_settings is silently ignored
|
|
// by Square's TerminalCheckout API, losing terminal tip revenue). Only
|
|
// allow_tipping is emitted — Square's wire field for enabling terminal tips.
|
|
type sqTipSettings struct {
|
|
AllowTipping bool `json:"allow_tipping"`
|
|
}
|
|
|
|
// sqDeviceOptions maps to Square's DeviceCheckoutOptions object inside the
|
|
// TerminalCheckout payload. device_id is REQUIRED; tip_settings lives here
|
|
// (not at the checkout top level) so terminal tips are actually collected.
|
|
type sqDeviceOptions struct {
|
|
DeviceID string `json:"device_id"`
|
|
TipSettings *sqTipSettings `json:"tip_settings,omitempty"`
|
|
}
|
|
|
|
type sqTerminalCheckoutResponse struct {
|
|
Checkout sqTerminalCheckout `json:"checkout"`
|
|
}
|
|
|
|
type sqTerminalCheckout struct {
|
|
ID string `json:"id"`
|
|
Status string `json:"status"`
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
Note string `json:"note,omitempty"`
|
|
PaymentIDs []string `json:"payment_ids,omitempty"`
|
|
// Deadline (deadline_duration) is a LIVE TerminalCheckout field: an RFC 3339
|
|
// duration (e.g. "PT5M") telling the terminal how long the checkout stays
|
|
// active. Square defaults it to 5 minutes. It is NOT an absolute timestamp
|
|
// and NOT deprecated. Kept as a string because the app only copies it
|
|
// through to CheckoutResult.Deadline.
|
|
Deadline string `json:"deadline_duration,omitempty"`
|
|
CreatedAt string `json:"created_at"`
|
|
UpdatedAt string `json:"updated_at"`
|
|
}
|
|
|
|
type sqGetPaymentResponse struct {
|
|
Payment sqPayment `json:"payment"`
|
|
}
|
|
|
|
// --- Refund types ---
|
|
|
|
type sqRefundPaymentRequest struct {
|
|
PaymentID string `json:"payment_id"`
|
|
IdempotencyKey string `json:"idempotency_key"`
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
Reason string `json:"reason,omitempty"`
|
|
}
|
|
|
|
type sqRefundPaymentResponse struct {
|
|
Refund sqRefund `json:"refund"`
|
|
}
|
|
|
|
type sqListRefundsResponse struct {
|
|
Refunds []sqRefund `json:"refunds"`
|
|
Cursor string `json:"cursor"`
|
|
}
|
|
|
|
type sqRefund struct {
|
|
ID string `json:"id"`
|
|
Status string `json:"status"`
|
|
AmountMoney sqMoney `json:"amount_money"`
|
|
PaymentID string `json:"payment_id"`
|
|
LocationID string `json:"location_id"`
|
|
Reason string `json:"reason,omitempty"`
|
|
CreatedAt string `json:"created_at"`
|
|
}
|
|
|
|
// --- Card types ---
|
|
|
|
type sqCreateCardRequest struct {
|
|
IdempotencyKey string `json:"idempotency_key"`
|
|
SourceID string `json:"source_id"`
|
|
Card sqCardPayload `json:"card"`
|
|
}
|
|
|
|
type sqCardPayload struct {
|
|
ExpMonth *int `json:"exp_month,omitempty"`
|
|
ExpYear *int `json:"exp_year,omitempty"`
|
|
CardholderName string `json:"cardholder_name,omitempty"`
|
|
CustomerID string `json:"customer_id,omitempty"`
|
|
ReferenceID string `json:"reference_id,omitempty"`
|
|
}
|
|
|
|
type sqCreateCardResponse struct {
|
|
Card sqCard `json:"card"`
|
|
}
|
|
|
|
type sqListCardsResponse struct {
|
|
Cards []sqCard `json:"cards"`
|
|
Cursor string `json:"cursor"`
|
|
}
|
|
|
|
type sqDisableCardResponse struct {
|
|
Card sqCard `json:"card"`
|
|
}
|
|
|
|
// --- Customer types ---
|
|
|
|
type sqCreateCustomerRequest struct {
|
|
IdempotencyKey string `json:"idempotency_key"`
|
|
EmailAddress string `json:"email_address"`
|
|
GivenName string `json:"given_name,omitempty"`
|
|
}
|
|
|
|
type sqCreateCustomerResponse struct {
|
|
Customer sqCustomer `json:"customer"`
|
|
}
|
|
|
|
// sqCustomer maps to Square's Customer object. Only fields this application
|
|
// consumes are included.
|
|
type sqCustomer struct {
|
|
ID string `json:"id"`
|
|
EmailAddress string `json:"email_address"`
|
|
GivenName string `json:"given_name"`
|
|
CreatedAt string `json:"created_at"`
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Package-level HTTP functions — shared by ProdClient and devProdClient.
|
|
// Each builds a fresh httpClient from env vars and makes the Square API call.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// validSquareID reports whether id is safe to embed in a Square REST URL path
|
|
// segment. Square IDs are alphanumeric plus '_' and '-' and well under 64
|
|
// characters; anything else could produce a malformed URL or enable path
|
|
// traversal in a future caller.
|
|
func validSquareID(id string) bool {
|
|
if len(id) == 0 || len(id) > 64 {
|
|
return false
|
|
}
|
|
for i := 0; i < len(id); i++ {
|
|
c := id[i]
|
|
if !(c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' || c == '_' || c == '-') {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
|
|
// isTokenLike returns true for Square source_id tokens: cnon:xxx nonces and
|
|
// ccof:xxx card IDs. Raw PANs (all digits) are NOT token-like and are rejected.
|
|
// This is the single source of truth for token validation, shared by the real
|
|
// HTTP client and the dev mock so PCI-DSS parity holds in both builds.
|
|
func isTokenLike(s string) bool {
|
|
return strings.HasPrefix(s, "cnon:") || strings.HasPrefix(s, "ccof:")
|
|
}
|
|
|
|
// tokenPrefix returns a PCI-safe abbreviation of a card token for error and
|
|
// log messages: the first 8 characters plus an ellipsis and the total length.
|
|
// The full token (a raw PAN, single-use nonce, or card reference) must NEVER
|
|
// be echoed — handlers log these errors, so embedding the raw value would land
|
|
// client-submitted card data verbatim in server logs.
|
|
func tokenPrefix(s string) string {
|
|
if len(s) > 8 {
|
|
return fmt.Sprintf("%s... (len %d)", s[:8], len(s))
|
|
}
|
|
return fmt.Sprintf("%s (len %d)", s, len(s))
|
|
}
|
|
|
|
func createPaymentHTTP(ctx context.Context, req CreatePaymentReq) (*PaymentResult, error) {
|
|
return createPaymentHTTPWithClient(ctx, req, newHTTPClient())
|
|
}
|
|
|
|
func createPaymentHTTPWithClient(ctx context.Context, req CreatePaymentReq, hc *httpClient) (*PaymentResult, error) {
|
|
// PCI-DSS parity with the dev mock: reject raw PANs before they reach
|
|
// Square. source_id must be a cnon: nonce or ccof: card ID — anything else
|
|
// (e.g. a plain card number) is refused client-side so no card data is ever
|
|
// sent to the API in a non-token form.
|
|
if !isTokenLike(req.SourceID) {
|
|
return nil, fmt.Errorf("square: invalid card token %s — use a card nonce (cnon:xxx) or card ID (ccof:xxx)", tokenPrefix(req.SourceID))
|
|
}
|
|
body := sqCreatePaymentRequest{
|
|
SourceID: req.SourceID,
|
|
IdempotencyKey: req.IdempotencyKey,
|
|
AmountMoney: sqMoney{Amount: req.Amount, Currency: req.Currency},
|
|
Autocomplete: req.Autocomplete,
|
|
LocationID: firstNonEmpty(req.LocationID, hc.locationID),
|
|
ReferenceID: req.ReferenceID,
|
|
CustomerID: req.CustomerID,
|
|
Note: req.Note,
|
|
VerificationToken: req.VerificationToken,
|
|
BuyerEmailAddress: req.BuyerEmail,
|
|
}
|
|
if req.TipMoney != nil {
|
|
body.TipMoney = &sqMoney{Amount: *req.TipMoney, Currency: req.Currency}
|
|
}
|
|
var resp sqCreatePaymentResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/payments", body, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
return paymentFromSquare(&resp.Payment), nil
|
|
}
|
|
|
|
func createCheckoutHTTP(ctx context.Context, req CreateCheckoutReq) (*CheckoutResult, error) {
|
|
return createCheckoutHTTPWithClient(ctx, req, newHTTPClient())
|
|
}
|
|
|
|
func createCheckoutHTTPWithClient(ctx context.Context, req CreateCheckoutReq, hc *httpClient) (*CheckoutResult, error) {
|
|
// device_options is REQUIRED by Square's TerminalCheckout API. Prefer the
|
|
// per-request device ID, falling back to the env-configured terminal
|
|
// (SQUARE_TERMINAL_DEVICE_ID) so the field is always present.
|
|
deviceID := req.DeviceID
|
|
if deviceID == "" {
|
|
deviceID = hc.deviceID
|
|
}
|
|
body := sqTerminalCheckoutRequest{
|
|
IdempotencyKey: req.IdempotencyKey,
|
|
Checkout: sqTerminalCheckoutPayload{
|
|
AmountMoney: sqMoney{Amount: req.Amount, Currency: req.Currency},
|
|
ReferenceID: req.ReferenceID,
|
|
Note: req.Note,
|
|
CustomerID: req.CustomerID,
|
|
DeviceOptions: &sqDeviceOptions{
|
|
DeviceID: deviceID,
|
|
},
|
|
},
|
|
}
|
|
// AllowTipping must reach Square as device_options.tip_settings.allow_tipping
|
|
// — without it the terminal never prompts for a tip and tip revenue is
|
|
// silently lost. A top-level tip_settings would be ignored by Square.
|
|
if req.AllowTipping {
|
|
body.Checkout.DeviceOptions.TipSettings = &sqTipSettings{AllowTipping: true}
|
|
}
|
|
var resp sqTerminalCheckoutResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/terminals/checkouts", body, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
return checkoutFromSquare(&resp.Checkout), nil
|
|
}
|
|
|
|
func getCheckoutHTTP(ctx context.Context, checkoutID string) (*PaymentResult, error) {
|
|
return getCheckoutHTTPWithClient(ctx, checkoutID, newHTTPClient())
|
|
}
|
|
|
|
func getCheckoutHTTPWithClient(ctx context.Context, checkoutID string, hc *httpClient) (*PaymentResult, error) {
|
|
if !validSquareID(checkoutID) {
|
|
return nil, fmt.Errorf("square: invalid checkout id %q", checkoutID)
|
|
}
|
|
var tcResp sqTerminalCheckoutResponse
|
|
if err := hc.doJSON(ctx, http.MethodGet, "/v2/terminals/checkouts/"+checkoutID, nil, &tcResp); err != nil {
|
|
return nil, err
|
|
}
|
|
tc := tcResp.Checkout
|
|
if tc.Status != "COMPLETED" {
|
|
// PENDING / IN_PROGRESS / CANCEL_REQUESTED all mean the terminal
|
|
// hasn't finished — treat as still-polling. Anything else (e.g.
|
|
// CANCELED) is terminal but not a completed payment.
|
|
switch tc.Status {
|
|
case "PENDING", "IN_PROGRESS", "CANCEL_REQUESTED":
|
|
return nil, ErrCheckoutPending
|
|
}
|
|
return nil, fmt.Errorf("square: checkout %s is %s (not COMPLETED)", checkoutID, tc.Status)
|
|
}
|
|
if len(tc.PaymentIDs) == 0 {
|
|
return nil, fmt.Errorf("square: checkout %s has no payment IDs", checkoutID)
|
|
}
|
|
var payResp sqGetPaymentResponse
|
|
if err := hc.doJSON(ctx, http.MethodGet, "/v2/payments/"+tc.PaymentIDs[0], nil, &payResp); err != nil {
|
|
return nil, err
|
|
}
|
|
return paymentFromSquare(&payResp.Payment), nil
|
|
}
|
|
|
|
func getPaymentHTTP(ctx context.Context, paymentID string) (*PaymentResult, error) {
|
|
return getPaymentHTTPWithClient(ctx, paymentID, newHTTPClient())
|
|
}
|
|
|
|
func getPaymentHTTPWithClient(ctx context.Context, paymentID string, hc *httpClient) (*PaymentResult, error) {
|
|
if !validSquareID(paymentID) {
|
|
return nil, fmt.Errorf("square: invalid payment id %q", paymentID)
|
|
}
|
|
var resp sqGetPaymentResponse
|
|
if err := hc.doJSON(ctx, http.MethodGet, "/v2/payments/"+paymentID, nil, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
return paymentFromSquare(&resp.Payment), nil
|
|
}
|
|
|
|
// squareAPIError wraps a formatted Square API error while exposing the
|
|
// structured Square error code and the HTTP status code so callers can
|
|
// classify definitive business rejections (e.g. ErrRefundDeclined) vs
|
|
// ambiguous transport/server errors, and distinguish 400/401/429/500
|
|
// structurally without parsing the message. Category/Field are captured from
|
|
// Square's error payload (the wire error carries them; they were previously
|
|
// dropped).
|
|
type squareAPIError struct {
|
|
Code string
|
|
Detail string
|
|
Category string
|
|
Field string
|
|
StatusCode int
|
|
err error
|
|
}
|
|
|
|
func (e *squareAPIError) Error() string { return e.err.Error() }
|
|
func (e *squareAPIError) Unwrap() error { return e.err }
|
|
|
|
// ErrorCode returns the Square error Code carried by err when err (or any
|
|
// error it wraps) is a *squareAPIError — i.e. a structured error parsed from
|
|
// Square's error response body. It returns "" for non-Square errors so callers
|
|
// can classify charge failures structurally instead of substring-matching the
|
|
// message.
|
|
func ErrorCode(err error) string {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.Code
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// ErrorDetail returns the Square error Detail carried by err when err (or any
|
|
// error it wraps) is a *squareAPIError, and "" otherwise.
|
|
func ErrorDetail(err error) string {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.Detail
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// ErrorStatusCode returns the HTTP status code of the Square response carried
|
|
// by err when err (or any error it wraps) is a *squareAPIError, and 0
|
|
// otherwise. Callers can distinguish 400/401/429/500 structurally instead of
|
|
// substring-matching "HTTP 400" etc.
|
|
func ErrorStatusCode(err error) int {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.StatusCode
|
|
}
|
|
return 0
|
|
}
|
|
|
|
// ErrorCategory returns the Square error Category carried by err when err (or
|
|
// any error it wraps) is a *squareAPIError, and "" otherwise.
|
|
func ErrorCategory(err error) string {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.Category
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// ErrorField returns the Square error Field carried by err when err (or any
|
|
// error it wraps) is a *squareAPIError, and "" otherwise.
|
|
func ErrorField(err error) string {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.Field
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// IsNotFound reports whether err is a Square "not found" condition: the
|
|
// structured NOT_FOUND error code, an HTTP 404 response status, or a plain
|
|
// non-JSON 404 body (doJSON's fallback error message embeds "HTTP 404").
|
|
// Callers use this to treat already-completed/unknown Square resources as
|
|
// idempotent no-ops instead of substring-matching the error message.
|
|
func IsNotFound(err error) bool {
|
|
if err == nil {
|
|
return false
|
|
}
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) {
|
|
return sqErr.Code == "NOT_FOUND" || sqErr.StatusCode == http.StatusNotFound
|
|
}
|
|
return strings.Contains(err.Error(), "HTTP 404")
|
|
}
|
|
|
|
// Definitive Square refund rejection codes — the refund was declined and can
|
|
// never succeed, so retrying is pointless and the refund record should be
|
|
// marked 'failed'. Anything else (transport errors, 5xx) is left ambiguous so
|
|
// callers leave the refund 'pending' for a scheduler retry. Codes match
|
|
// Square's documented Refunds error list (REFUND_DECLINED, REFUND_AMOUNT_INVALID,
|
|
// PAYMENT_NOT_REFUNDABLE); note PAYMENT_ALREADY_REFUNDED and
|
|
// REFUND_ALREADY_PENDING are intentionally absent — money is in flight or has
|
|
// moved, so they map to ErrRefundAlreadyProcessed instead of ErrRefundDeclined.
|
|
var definitiveRefundCodes = map[string]bool{
|
|
"REFUND_DECLINED": true,
|
|
"REFUND_AMOUNT_INVALID": true,
|
|
"PAYMENT_NOT_REFUNDABLE": true,
|
|
}
|
|
|
|
func refundPaymentHTTP(ctx context.Context, req RefundPaymentReq) (*RefundResult, error) {
|
|
return refundPaymentHTTPWithClient(ctx, req, newHTTPClient())
|
|
}
|
|
|
|
func refundPaymentHTTPWithClient(ctx context.Context, req RefundPaymentReq, hc *httpClient) (*RefundResult, error) {
|
|
body := sqRefundPaymentRequest{
|
|
PaymentID: req.PaymentID,
|
|
IdempotencyKey: req.IdempotencyKey,
|
|
AmountMoney: sqMoney{Amount: req.Amount, Currency: "GBP"},
|
|
Reason: req.Reason,
|
|
}
|
|
var resp sqRefundPaymentResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/refunds", body, &resp); err != nil {
|
|
var sqErr *squareAPIError
|
|
if errors.As(err, &sqErr) && definitiveRefundCodes[sqErr.Code] {
|
|
return nil, fmt.Errorf("%w: %v", ErrRefundDeclined, err)
|
|
}
|
|
if errors.As(err, &sqErr) && (sqErr.Code == "PAYMENT_ALREADY_REFUNDED" || sqErr.Code == "REFUND_ALREADY_PENDING") {
|
|
return nil, fmt.Errorf("%w: %v", ErrRefundAlreadyProcessed, err)
|
|
}
|
|
return nil, err
|
|
}
|
|
return refundFromSquare(&resp.Refund), nil
|
|
}
|
|
|
|
func listRefundsHTTP(ctx context.Context, paymentID string, beginTime time.Time) ([]RefundResult, error) {
|
|
return listRefundsHTTPWithClient(ctx, paymentID, beginTime, newHTTPClient())
|
|
}
|
|
|
|
func listRefundsHTTPWithClient(ctx context.Context, paymentID string, beginTime time.Time, hc *httpClient) ([]RefundResult, error) {
|
|
base := "/v2/refunds?begin_time=" + url.QueryEscape(beginTime.UTC().Format(time.RFC3339)) + "&limit=100"
|
|
path := base
|
|
results := []RefundResult{}
|
|
for page := 0; page < 20; page++ {
|
|
var resp sqListRefundsResponse
|
|
if err := hc.doJSON(ctx, http.MethodGet, path, nil, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
for i := range resp.Refunds {
|
|
r := &resp.Refunds[i]
|
|
if r.PaymentID == paymentID {
|
|
results = append(results, *refundFromSquare(r))
|
|
}
|
|
}
|
|
if resp.Cursor == "" {
|
|
return results, nil
|
|
}
|
|
path = base + "&cursor=" + url.QueryEscape(resp.Cursor)
|
|
}
|
|
// 20 pages fetched and a cursor is still present — return what we
|
|
// collected rather than discarding partial results (the previous
|
|
// infinite-loop guard dropped everything and returned an error).
|
|
log.Printf("[SQUARE] list refunds exceeded 20 pages (infinite-loop guard) — returning partial results: %d refunds for %s", len(results), paymentID)
|
|
return results, nil
|
|
}
|
|
|
|
func createCardOnFileHTTP(ctx context.Context, userID, cardToken, customerID string) (*CardOnFile, error) {
|
|
return createCardOnFileHTTPWithClient(ctx, userID, cardToken, customerID, newHTTPClient())
|
|
}
|
|
|
|
func createCardOnFileHTTPWithClient(ctx context.Context, userID, cardToken, customerID string, hc *httpClient) (*CardOnFile, error) {
|
|
// PCI-DSS parity with the dev mock: source_id must be a cnon: nonce or
|
|
// ccof: card ID. A raw PAN is refused client-side before it reaches Square.
|
|
if !isTokenLike(cardToken) {
|
|
return nil, fmt.Errorf("square: invalid card token %s — use a card nonce (cnon:xxx) or card ID (ccof:xxx)", tokenPrefix(cardToken))
|
|
}
|
|
|
|
// Deterministic idempotency key derived from user + card (not time-based)
|
|
// so that retries with the same details don't create duplicate cards.
|
|
// SHA-256 hash prevents recovering the card token from the key itself.
|
|
// Truncated to ≤45 chars — Square's documented idempotency-key limit for
|
|
// /v2/cards (a full 64-hex hash would be rejected with a 400).
|
|
ikHash := sha256.Sum256([]byte(userID + "|" + cardToken))
|
|
body := sqCreateCardRequest{
|
|
IdempotencyKey: "card-" + fmt.Sprintf("%x", ikHash)[:38],
|
|
SourceID: cardToken,
|
|
Card: sqCardPayload{
|
|
// reference_id is Square's free-form client reference, used to link
|
|
// the card to the local user for client-side filtering. customer_id
|
|
// is sent when the app has provisioned a Square customer for the
|
|
// user (Square marks customer_id Required on the Card object for
|
|
// saved-card flows) and omitted otherwise.
|
|
ReferenceID: userID,
|
|
CustomerID: customerID,
|
|
},
|
|
}
|
|
var resp sqCreateCardResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/cards", body, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
return cardFromSquare(&resp.Card, userID), nil
|
|
}
|
|
|
|
func getCardsOnFileHTTP(ctx context.Context, userID string) ([]CardOnFile, error) {
|
|
return getCardsOnFileHTTPWithClient(ctx, userID, newHTTPClient())
|
|
}
|
|
|
|
func getCardsOnFileHTTPWithClient(ctx context.Context, userID string, hc *httpClient) ([]CardOnFile, error) {
|
|
// Filter by reference_id natively: Square's List Cards API supports the
|
|
// reference_id query param, and cards are created with reference_id = the
|
|
// local user ID. customer_id is not used for the filter because a user may
|
|
// have no provisioned Square customer. List Cards has NO limit param and
|
|
// pages at 25 cards per page, so loop on the cursor to avoid silently
|
|
// truncating a large saved-card list (N-10). The 20-page guard therefore
|
|
// caps out at 500 cards before warning.
|
|
var cards []CardOnFile
|
|
path := "/v2/cards?reference_id=" + url.QueryEscape(userID)
|
|
truncated := false
|
|
for page := 0; page < 20; page++ {
|
|
var resp sqListCardsResponse
|
|
if err := hc.doJSON(ctx, http.MethodGet, path, nil, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
for i := range resp.Cards {
|
|
cards = append(cards, *cardFromSquare(&resp.Cards[i], userID))
|
|
}
|
|
if resp.Cursor == "" {
|
|
break
|
|
}
|
|
if page == 19 {
|
|
truncated = true
|
|
}
|
|
path = "/v2/cards?reference_id=" + url.QueryEscape(userID) + "&cursor=" + url.QueryEscape(resp.Cursor)
|
|
}
|
|
if truncated {
|
|
// 20 pages fetched and a cursor is still present — return what we
|
|
// collected rather than discarding partial results (mirrors the
|
|
// listRefunds 20-page guard's behavior).
|
|
log.Printf("[SQUARE] list cards for %s exceeded 20 pages (infinite-loop guard) — returning partial results: %d cards", userID, len(cards))
|
|
}
|
|
if cards == nil {
|
|
cards = []CardOnFile{}
|
|
}
|
|
return cards, nil
|
|
}
|
|
|
|
func deleteCardOnFileHTTP(ctx context.Context, cardID string) error {
|
|
hc := newHTTPClient()
|
|
var resp sqDisableCardResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/cards/"+cardID+"/disable", nil, &resp); err != nil {
|
|
return err
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func createCustomerHTTP(ctx context.Context, name, email string) (*CustomerResult, error) {
|
|
return createCustomerHTTPWithClient(ctx, name, email, newHTTPClient())
|
|
}
|
|
|
|
func createCustomerHTTPWithClient(ctx context.Context, name, email string, hc *httpClient) (*CustomerResult, error) {
|
|
// Deterministic idempotency key derived from the email (not time-based)
|
|
// so retries with the same email don't create duplicate customers. SHA-256
|
|
// prevents recovering the email from the key. Truncated to ≤45 chars —
|
|
// Square's documented idempotency-key limit.
|
|
ikHash := sha256.Sum256([]byte(email))
|
|
body := sqCreateCustomerRequest{
|
|
IdempotencyKey: "customer-" + fmt.Sprintf("%x", ikHash)[:35],
|
|
EmailAddress: email,
|
|
GivenName: name,
|
|
}
|
|
var resp sqCreateCustomerResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/customers", body, &resp); err != nil {
|
|
return nil, err
|
|
}
|
|
return &CustomerResult{
|
|
ID: resp.Customer.ID,
|
|
Email: resp.Customer.EmailAddress,
|
|
CreatedAt: resp.Customer.CreatedAt,
|
|
}, nil
|
|
}
|
|
|
|
func cancelCheckoutHTTP(ctx context.Context, checkoutID string) error {
|
|
return cancelCheckoutHTTPWithClient(ctx, checkoutID, newHTTPClient())
|
|
}
|
|
|
|
func cancelCheckoutHTTPWithClient(ctx context.Context, checkoutID string, hc *httpClient) error {
|
|
if !validSquareID(checkoutID) {
|
|
return fmt.Errorf("square: invalid checkout id %q", checkoutID)
|
|
}
|
|
var resp sqTerminalCheckoutResponse
|
|
if err := hc.doJSON(ctx, http.MethodPost, "/v2/terminals/checkouts/"+checkoutID+"/cancel", nil, &resp); err != nil {
|
|
// Square returns 404 / NOT_FOUND when the checkout is already
|
|
// completed or canceled — that is a no-op, not a failure.
|
|
if IsNotFound(err) {
|
|
return nil
|
|
}
|
|
return err
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Conversion helpers — Square JSON → domain types.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
func paymentFromSquare(sq *sqPayment) *PaymentResult {
|
|
r := &PaymentResult{
|
|
ID: sq.ID,
|
|
Status: sq.Status,
|
|
Amount: sq.TotalMoney.Amount,
|
|
ReceiptURL: sq.ReceiptURL,
|
|
ReceiptNumber: sq.ReceiptNumber,
|
|
SquarePayID: sq.ID,
|
|
BuyerEmail: sq.BuyerEmail,
|
|
CustomerID: sq.CustomerID,
|
|
LocationID: sq.LocationID,
|
|
CreatedAt: sq.CreatedAt,
|
|
UpdatedAt: sq.UpdatedAt,
|
|
OrderID: sq.OrderID,
|
|
ReferenceID: sq.ReferenceID,
|
|
}
|
|
if sq.TipMoney != nil {
|
|
r.TipAmount = sq.TipMoney.Amount
|
|
}
|
|
for _, f := range sq.ProcessingFee {
|
|
r.Fees += f.AmountMoney.Amount
|
|
}
|
|
if sq.CardDetails != nil {
|
|
cd := sq.CardDetails
|
|
r.EntryMethod = cd.EntryMethod
|
|
r.CVVStatus = cd.CVVStatus
|
|
r.AVSStatus = cd.AVSStatus
|
|
r.CardBrand = cd.Card.CardBrand
|
|
r.CardLast4 = cd.Card.Last4
|
|
// exp_month/exp_year ride on the card object — pointer set when present.
|
|
expMonth := cd.Card.ExpMonth
|
|
expYear := cd.Card.ExpYear
|
|
r.ExpMonth = &expMonth
|
|
r.ExpYear = &expYear
|
|
if cd.Card.ID != "" {
|
|
r.CardFingerprint = cd.Card.Fingerprint
|
|
}
|
|
}
|
|
return r
|
|
}
|
|
|
|
func checkoutFromSquare(sq *sqTerminalCheckout) *CheckoutResult {
|
|
return &CheckoutResult{
|
|
ID: sq.ID,
|
|
Status: sq.Status,
|
|
AmountMoney: sq.AmountMoney.Amount,
|
|
Currency: sq.AmountMoney.Currency,
|
|
ReferenceID: sq.ReferenceID,
|
|
Note: sq.Note,
|
|
PaymentIDs: sq.PaymentIDs,
|
|
Deadline: sq.Deadline,
|
|
CreatedAt: sq.CreatedAt,
|
|
UpdatedAt: sq.UpdatedAt,
|
|
}
|
|
}
|
|
|
|
func refundFromSquare(sq *sqRefund) *RefundResult {
|
|
return &RefundResult{
|
|
ID: sq.ID,
|
|
Status: sq.Status,
|
|
Amount: sq.AmountMoney.Amount,
|
|
PaymentID: sq.PaymentID,
|
|
LocationID: sq.LocationID,
|
|
Reason: sq.Reason,
|
|
CreatedAt: sq.CreatedAt,
|
|
}
|
|
}
|
|
|
|
func cardFromSquare(sq *sqCard, userID string) *CardOnFile {
|
|
return &CardOnFile{
|
|
ID: sq.ID,
|
|
CardID: sq.ID,
|
|
Brand: sq.CardBrand,
|
|
Last4: sq.Last4,
|
|
ExpMonth: sq.ExpMonth,
|
|
ExpYear: sq.ExpYear,
|
|
Fingerprint: sq.Fingerprint,
|
|
CardholderName: sq.CardholderName,
|
|
CustomerID: sq.CustomerID,
|
|
ReferenceID: sq.ReferenceID,
|
|
Enabled: sq.Enabled,
|
|
Version: sq.Version,
|
|
CreatedAt: sq.CreatedAt,
|
|
}
|
|
}
|
|
|
|
func firstNonEmpty(vals ...string) string {
|
|
for _, v := range vals {
|
|
if v != "" {
|
|
return v
|
|
}
|
|
}
|
|
return ""
|
|
}
|