Documentation
¶
Overview ¶
Package square is the unified Square payment provider. It mirrors the braintree/ package shape so the BD tenant-scoped payment resolver can call processor.Get(processor.Square) and Configure(...) per-request the same way it already does for Braintree.
This package intentionally wraps the existing SDK-heavy client in thirdparty/square instead of duplicating the Square Go SDK plumbing. The split mirrors the codebase's "transport in thirdparty, lifecycle in payment/providers" convention: this file owns the Configure/IsAvailable contract the processor registry expects; thirdparty/square owns the actual HTTP calls against the Square API.
Credentials are resolved per-request from BD's payment_providers collection (see bd/payment_provider_config.go). At init() time we only register an empty Provider with the global registry — Configure(cfg) is the only path that produces a usable client. This matches how Blue-fix-1 wired Braintree: env vars are a one-way bootstrap, the DB is truth.
Index ¶
- type Config
- type Provider
- func (p *Provider) ApplicationID() string
- func (p *Provider) Authorize(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
- func (p *Provider) CancelAuthorization(ctx context.Context, paymentID string) error
- func (p *Provider) Capture(ctx context.Context, transactionID string, amount currency.Cents) (*processor.PaymentResult, error)
- func (p *Provider) Charge(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
- func (p *Provider) Configure(cfg Config)
- func (p *Provider) Environment() string
- func (p *Provider) GetTransaction(ctx context.Context, txID string) (*processor.Transaction, error)
- func (p *Provider) IsAvailable(ctx context.Context) bool
- func (p *Provider) LocationID() string
- func (p *Provider) Refund(ctx context.Context, req processor.RefundRequest) (*processor.RefundResult, error)
- func (p *Provider) SupportedCurrencies() []currency.Type
- func (p *Provider) Type() processor.ProcessorType
- func (p *Provider) ValidateWebhook(ctx context.Context, payload []byte, signature string) (*processor.WebhookEvent, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// ApplicationID is the Square Developer Dashboard application ID.
// Required for the Web Payments SDK (browser-side tokenization).
ApplicationID string
// AccessToken is the server-side OAuth bearer that authenticates
// Create/Refund payment calls against the Square API.
AccessToken string
// LocationID pins charges to a specific Square merchant location.
LocationID string
// WebhookSignatureKey is the HMAC-SHA256 key that verifies
// payment.* webhook deliveries. Also called "Webhook Signature Key"
// in the Square dashboard.
WebhookSignatureKey string
// Environment must be "sandbox" or "production".
Environment string
}
Config holds Square API credentials and environment settings. Field names match the BD payment_providers JSON schema (camelCase) so callers can unmarshal directly into this struct.
type Provider ¶
type Provider struct {
*processor.BaseProcessor
// contains filtered or unexported fields
}
Provider implements processor.PaymentProcessor for Square. Every method delegates to an underlying *thirdparty.SquareProcessor so there is one and only one HTTP client talking to Square. Configure() rebuilds the inner client whenever creds rotate — the BD runtime-config resolver calls Configure per request, so a key swap via the admin UI is visible within one RTT.
func NewProvider ¶
NewProvider builds and configures a Provider in one shot. Prefer this constructor in unit tests and one-off scripts; BD uses the init() + Configure() pattern at runtime.
func (*Provider) ApplicationID ¶
ApplicationID returns the browser-facing application ID. The Web Payments SDK needs this plus the locationID to initialise.
func (*Provider) Authorize ¶
func (p *Provider) Authorize(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
Authorize performs an auth-only (Autocomplete=false) tokenized payment. Pairs with Capture to release/settle later. Used for deposit flows where we want to confirm the card is good before committing ledger state — today BD goes directly via Charge for simplicity.
func (*Provider) CancelAuthorization ¶
CancelAuthorization voids an uncaptured auth. Used by BD when the downstream routing step fails and we must release the hold rather than let it fall off after Square's 7-day auth window.
func (*Provider) Capture ¶
func (p *Provider) Capture(ctx context.Context, transactionID string, amount currency.Cents) (*processor.PaymentResult, error)
Capture completes a previously authorized payment by its Square payment_id.
func (*Provider) Charge ¶
func (p *Provider) Charge(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
Charge processes a tokenized payment (Autocomplete=true on the Square side, i.e. capture-at-charge). The req.Token field must be a Square Web Payments SDK payment source id — card nonce, Apple Pay token, or Google Pay token. Square treats them identically once tokenized.
BD calls this from /v1/bd/deposits/{id}/confirm with the token the fund SPA produced via the Web Payments SDK. The returned TransactionID is the Square payment_id, which BD pins to the deposit row for idempotent webhook reconciliation.
func (*Provider) Configure ¶
Configure rebuilds the inner SDK client from cfg. Safe to call concurrently with other Configure() calls only up to the guarantee provided by processor.BaseProcessor.SetConfigured; callers that race on Configure must serialise themselves.
func (*Provider) Environment ¶
Environment returns "sandbox" or "production". BD uses this to pick the correct Web Payments SDK URL (sandbox.web.squarecdn.com vs web.squarecdn.com).
func (*Provider) GetTransaction ¶
GetTransaction retrieves a payment by Square payment_id. Used by the reconciler to confirm settled state before crediting DEF ledger when the webhook is delayed.
func (*Provider) IsAvailable ¶
IsAvailable reports whether the processor has been configured. Does not issue a network probe — that is the /test endpoint's job in BD.
func (*Provider) LocationID ¶
LocationID returns the configured merchant location. Exposed so BD can hand it to the fund SPA alongside the application id.
func (*Provider) Refund ¶
func (p *Provider) Refund(ctx context.Context, req processor.RefundRequest) (*processor.RefundResult, error)
Refund processes a refund against a settled Square payment. Partial refunds are supported by setting req.Amount < the original; a zero amount refunds the full charge.
func (*Provider) SupportedCurrencies ¶
SupportedCurrencies returns the currencies Square supports. Delegates to thirdparty to keep the list in one place.
func (*Provider) Type ¶
func (p *Provider) Type() processor.ProcessorType
Type returns the processor type.
func (*Provider) ValidateWebhook ¶
func (p *Provider) ValidateWebhook(ctx context.Context, payload []byte, signature string) (*processor.WebhookEvent, error)
ValidateWebhook verifies the HMAC-SHA256 signature on an incoming Square webhook and returns a normalised event. BD's /v1/bd/webhooks/square handler must:
- Iterate enabled square payment_providers rows (for multi-tenant webhook disambiguation — Square's webhook is headerless on tenant).
- Call ValidateWebhook with the raw request body and the x-square-hmacsha256-signature header.
- Accept the first row whose WebhookSignatureKey validates, reject with 401 if none match.
The normalised event.Type will be one of:
- payment.created
- payment.updated (includes status=COMPLETED for settled funds)
- refund.created / refund.updated
- dispute.created / dispute.updated
See thirdparty/square/processor.go::mapSquareEventType for the full mapping.
Source Files