Generated from package comments and exported declarations. Edit the Go source, not this file.
payments
import "codeberg.org/hemanta212/playgo/api/payments"
Package payments defines deposit, withdrawal, proof, webhook, and provider-gateway contracts.
This is the largest admin surface, covering off-app deposit state transitions, the withdrawal inbox, review acknowledgement, approval, settlement, proof assets, reconciliation, and provider callbacks.
Three things are worth knowing before working here.
States and events are append-only audit vocabulary. Records gain history; they do not have it overwritten.
The withdrawal inbox grouping (open, paid, closed) is not the same thing as the financial state machine, and the two should not be derived from each other. The mapping is deliberately not one-to-one, so clients consume the backend-derived operator status rather than recomputing it.
An unknown outcome stays unknown. When a provider or webhook disagrees with our state, the record moves to reconciliation rather than being forced to look successful. Guessing at an unresolved payout is how a player gets paid twice.
Handlers translate HTTP requests into commands; services own idempotency, lifecycle facts, wallet effects, and provider evidence.
Constants
const (
HousePayoutPolicyChangedMessage = "Payout settings changed. Reload them and review the payout account before continuing."
CashoutScreenshotRequiredMessage = "Add a screenshot of your payment app that shows your tag and name."
PaymentReceiptInvalidMessage = "Your screenshot could not be verified. Retry its upload before submitting."
)
Plain operator refusals for staff cash records. A recorded cash in needs only amount and method, with a name for Other (#853); a player's payment claim is approved only with the player's receipt screenshot (#842).
const (
StaffCashInTagNameMessage = "Choose the method (Chime, PayPal, Cash App) or type its name under Other."
StaffClaimNoScreenshotMessage = "This payment claim has no receipt screenshot, so it cannot be approved. Ask the player to send one."
)
const DepositBonusRecoveryMessage = "A reversed deposit bonus needs support review before you can cash out."
ManualClaimPayerTagMessage asks the player for the tag they paid from (#853).
const ManualClaimPayerTagMessage = "Enter the tag you sent the money from. Example: $George-Ramsey-27."
MaxManualPayoutReferenceLength bounds the payment confirmation reference.
const MaxManualPayoutReferenceLength = 200
const MaxPlayerDepositMethods = 30
const (
MaxWebhookIdentityBodyBytes = 1 << 20
)
MinimumManualClaimPaidCents is the positive-cent receipt boundary, not a suggested amount to send. Preserve the player's chosen PaidCents separately from SuggestedCreditCents and RoundUpCents.
const MinimumManualClaimPaidCents int64 = 1
OffAppDepositAmountMessage explains the ADR 0015 deposit amount rule when a staff-recorded deposit has other cents (#859).
const OffAppDepositAmountMessage = "Enter a whole-dollar amount like 5.00, or one ending in .99 like 4.99. Deposits with other cents cannot be credited."
QualifyingDepositMinimumCents is the product-wide minimum for a deposit to unlock deposit-qualified rewards and referral policy.
const QualifyingDepositMinimumCents = ledger.Cents(499)
const ResourceEffectPaymentDepositsOptions = "payment-deposits.options"
const WithdrawalBeingPaidMessage = "Staff are paying this cash-out now. It can't be canceled."
WithdrawalFulfillmentAdminManual marks provider evidence for a payout that an admin sends by hand and then marks paid.
const WithdrawalFulfillmentAdminManual = "admin_manual"
Variables
var (
ErrHousePayoutPolicyChanged = fmt.Errorf("%w: house payout policy changed", apiidem.ErrConflict)
ErrPaymentReceiptInvalid = fmt.Errorf("%w: payment receipt not ready", ErrInvalidRequest)
)
var (
ErrWithdrawalNotManualPayout = fmt.Errorf("%w: withdrawal is not a manual payout", ErrInvalidRequest)
ErrWithdrawalProofRequired = fmt.Errorf("%w: payout settings require a settlement proof", ErrInvalidRequest)
ErrWithdrawalFeeInvalid = fmt.Errorf("%w: fee must leave a positive net payout", ErrInvalidRequest)
// ErrWithdrawalNeedsReview refuses the one-step approve-and-mark-paid of a
// payout that is not a manual payout or whose player has open risk
// signals; it must be approved from its detail first.
ErrWithdrawalNeedsReview = errors.New("this player has open risk signals: choose why you approve this cash-out, then approve it again")
// ErrWithdrawalPaymentNotConfirmed refuses approving a hand-paid cash-out
// unless the admin answered Yes to "Did you pay the player already?".
ErrWithdrawalPaymentNotConfirmed = fmt.Errorf("%w: confirm you already paid the player", ErrInvalidRequest)
// ErrWithdrawalPaidByHand refuses the plain approve of a cash-out an admin
// pays by hand: approving it records it paid, with the payment details (ADR 0019).
ErrWithdrawalPaidByHand = fmt.Errorf("%w: pay this cash-out first, then approve it with the receipt: approving a hand-paid cash-out records it paid", apiidem.ErrConflict)
)
var (
ErrDepositMethodHidden = errors.New("payments: deposit method hidden")
ErrDepositMethodListChanged = errors.New("payments: player deposit method list changed")
)
var (
ErrDepositBonusRecoveryRequired = errors.New("payments: deposit bonus recovery required")
ErrInvalidRequest = errors.New("payments: invalid request")
ErrDepositBelowMinimum = fmt.Errorf("%w: below current provider minimum", ErrInvalidRequest)
ErrInvalidDestination = fmt.Errorf("%w: invalid withdrawal destination", ErrInvalidRequest)
ErrWithdrawalSettlementDetailsInvalid = fmt.Errorf("%w: incomplete withdrawal settlement details", ErrInvalidRequest)
ErrWithdrawalSettlementAmountsMismatch = fmt.Errorf("%w: withdrawal settlement fee and net do not equal gross", ErrInvalidRequest)
ErrWithdrawalProofNotFinalized = fmt.Errorf("%w: withdrawal proof is not finalized", ErrInvalidRequest)
ErrNotFound = errors.New("payments: not found")
ErrDisabled = errors.New("payments: provider disabled")
ErrProviderUnavailable = errors.New("payments: provider unavailable")
ErrSignatureInvalid = errors.New("payments: signature invalid")
// ErrSignedWebhookRejected wraps a refusal of a callback whose signature
// passed (bad field, identity or status). It is not a possible forgery.
ErrSignedWebhookRejected = errors.New("payments: signed webhook rejected")
ErrEvidenceMismatch = errors.New("payments: provider evidence mismatch")
ErrUnknownProviderEvent = errors.New("payments: unknown provider event")
)
var (
ErrWithdrawalBeingPaid = errors.New("withdrawal is being paid")
ErrWithdrawalClaimRequired = errors.New("withdrawal paying claim required")
ErrWithdrawalClaimReview = errors.New("withdrawal paying claim needs review")
ErrWithdrawalCanceledBeforePay = errors.New("withdrawal canceled before payment")
ErrWithdrawalExpiredBeforePay = errors.New("withdrawal expired before payment")
)
CloseoutReasons is why stale, never-paid deposits are closed as abandoned: each code and the phrase its audit text starts with.
var CloseoutReasons = reasoncode.Vocabulary{
"never_paid": "Never paid",
"player_abandoned": "Player abandoned the checkout",
"test_cleanup": "Test cleanup",
"other": "Other",
}
ErrDuplicateWithdrawalTransaction means another withdrawal already uses the receipt reference.
var ErrDuplicateWithdrawalTransaction = errors.New("this provider transaction reference is already used by another cash-out; verify the receipt and use its unique transaction reference; no funds were moved")
var ErrPolicyChanged = errors.New("deposit options changed; refresh payment options and try again")
OffAppConvertReasons is why a stuck provider deposit is converted to an off-app deposit: each code and the phrase its audit text starts with.
var OffAppConvertReasons = reasoncode.Vocabulary{
"paid_off_app": "Player paid another way",
"provider_checkout_failed": "Provider checkout failed",
"test_cleanup": "Test cleanup",
"other": "Other",
}
OffAppReversalReasons is why a settled off-app deposit is reversed: each code and the phrase its audit text starts with.
var OffAppReversalReasons = reasoncode.Vocabulary{
"payment_reversed": "Payment reversed by the sender",
"payment_not_received": "Payment never arrived",
"duplicate_payment": "Duplicate payment",
"credited_by_mistake": "Credited by mistake",
"test_cleanup": "Test cleanup",
"other": "Other",
}
OffAppSettleNowReasons is why an admin records and credits an off-app deposit in one step: each code and the phrase its audit text starts with.
var OffAppSettleNowReasons = reasoncode.Vocabulary{
"payment_received": "Payment received",
"receipt_verified": "Receipt verified",
"test_credit": "Test credit",
"other": "Other",
}
OffAppVoidReasons is why an unsettled off-app deposit draft is voided: each code and the phrase its audit text starts with.
var OffAppVoidReasons = reasoncode.Vocabulary{
"entered_in_error": "Entered in error",
"duplicate_entry": "Duplicate entry",
"payment_not_received": "Payment not received",
"player_cancelled": "Player cancelled",
"test_cleanup": "Test cleanup",
"other": "Other",
}
ProviderPolicyReasons is why an operator changed a payment provider policy (deposit routing or automatic payouts): each code and the phrase its audit text starts with.
var ProviderPolicyReasons = reasoncode.Vocabulary{
"provider_outage": "Provider outage",
"provider_restored": "Provider restored",
"operating_policy": "Operating policy change",
"correction": "Correcting a previous change",
"other": "Other",
}
WithdrawalApprovalReasons is why an admin approved a withdrawal: each code and the phrase its audit text starts with.
var WithdrawalApprovalReasons = reasoncode.Vocabulary{
"checks_passed": "Checks passed",
"known_player": "Known player",
"verified_identity": "Identity verified",
"other": "Other",
}
WithdrawalConfirmFailedReasons is why an admin confirmed that a reconciling payout failed and released its reservation: each code and the phrase its audit text starts with.
var WithdrawalConfirmFailedReasons = reasoncode.Vocabulary{
"provider_confirmed_failed": "Provider confirmed the payout failed",
"player_cancelled_at_provider": "Player cancelled at the provider",
"destination_rejected": "Payout destination rejected",
"other": "Other",
}
WithdrawalRejectionReasons is the private reason an admin rejected a withdrawal; the player sees only the rejection category: each code and the phrase its audit text starts with.
var WithdrawalRejectionReasons = reasoncode.Vocabulary{
"cheating": "Cheating",
"cleared_wallet": "Cleared wallet",
"suspected_fraud": "Suspected fraud",
"promotion_abuse": "Promotion abuse",
"unverified_identity": "Identity not verified",
"destination_problem": "Payout destination problem",
"duplicate_request": "Duplicate request",
"player_request": "Player asked to cancel",
"provider_unavailable": "Payout provider unavailable",
"test_cleanup": "Test cleanup",
"other": "Other",
}
func CashoutScreenshotRequired
func CashoutScreenshotRequired(code ProviderCode) bool
CashoutScreenshotRequired reports whether a cash-out paid by this provider needs the player's screenshot of their payment app (#853): staff pay a hand-paid (manual) cash-out by hand, to the tag the player shows.
func ManualPayoutPaidErrorMessage
func ManualPayoutPaidErrorMessage(err error) string
ManualPayoutPaidErrorMessage is the operator guidance for a refused manual mark-paid.
func OffAppDepositAmountError
func OffAppDepositAmountError() error
OffAppDepositAmountError refuses a recorded deposit amount the deposit credit rule does not allow, on the amount field.
func ParseConnectTestOrder
func ParseConnectTestOrder(ref MerchantOrderRef) (string, bool)
ParseConnectTestOrder recognizes only the run/step namespace used by probes. A real UUID payment-intent reference cannot match it.
func RefuseWithdrawalQuote
func RefuseWithdrawalQuote(reason WithdrawalQuoteReason, method WithdrawalDestinationKind, cause error) error
func WithdrawalEvidenceAdminFulfilled
func WithdrawalEvidenceAdminFulfilled(evidence map[string]any) bool
WithdrawalEvidenceAdminFulfilled reports whether stored provider evidence says an admin sends this payout by hand.
type AccountSetupState
type AccountSetupState string
const (
AccountSetupStateNotCreated AccountSetupState = "not_created"
AccountSetupStateActive AccountSetupState = "active"
AccountSetupStatePending AccountSetupState = "pending"
AccountSetupStateKYCRequired AccountSetupState = "kyc_required"
AccountSetupStateBlocked AccountSetupState = "blocked"
AccountSetupStateRejected AccountSetupState = "rejected"
AccountSetupStateInactive AccountSetupState = "inactive"
AccountSetupStateReviewRequired AccountSetupState = "review_required"
)
type AdminFulfilledWithdrawalGateway
AdminFulfilledWithdrawalGateway is implemented by payout providers that never send money themselves: an admin sends every payout by hand and marks it paid.
type AdminFulfilledWithdrawalGateway interface {
AdminFulfillsWithdrawals() bool
}
type AmountAwareWithdrawalOptionsGateway
AmountAwareWithdrawalOptionsGateway narrows advertised payout methods to methods the provider can currently fund for the supplied player amount.
type AmountAwareWithdrawalOptionsGateway interface {
ListWithdrawalOptionsForAmount(context.Context, ledger.Cents) (WithdrawalOptions, error)
}
type AmountOption
type AmountOption struct {
Ref AmountOptionRef
Amount ledger.Cents
Label string
Currency ledger.CurrencyCode
}
type AmountOptionRef
type AmountOptionRef string
type ApproveWithdrawalCommand
ApproveWithdrawalCommand approves a withdrawal. ReasonCode comes from WithdrawalApprovalReasons; Note is optional except for other.
type ApproveWithdrawalCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
ReasonCode string
Note string
IdempotencyKey string
}
type BalanceAmountKind
BalanceAmountKind identifies the vendor observation, independently of its currency.
type BalanceAmountKind string
const (
BalanceAmountAvailable BalanceAmountKind = "available"
BalanceAmountPending BalanceAmountKind = "pending"
BalanceAmountTotal BalanceAmountKind = "total"
BalanceAmountDelayed BalanceAmountKind = "delayed"
BalanceAmountOnHold BalanceAmountKind = "on_hold"
)
func (BalanceAmountKind) Valid
func (kind BalanceAmountKind) Valid() bool
type BalanceFailureReason
BalanceFailureReason is a safe PlayGo category; it never contains vendor messages.
type BalanceFailureReason string
const (
BalanceFailureNone BalanceFailureReason = ""
BalanceFailureTimeout BalanceFailureReason = "timeout"
BalanceFailureAuthentication BalanceFailureReason = "authentication"
BalanceFailureInvalidResponse BalanceFailureReason = "invalid_response"
BalanceFailureProviderUnavailable BalanceFailureReason = "provider_unavailable"
)
func (BalanceFailureReason) Valid
func (reason BalanceFailureReason) Valid() bool
type BalanceObservationState
BalanceObservationState distinguishes a verified observation from an unavailable read.
type BalanceObservationState string
const (
BalanceObservationReady BalanceObservationState = "ready"
BalanceObservationUnavailable BalanceObservationState = "unavailable"
)
func (BalanceObservationState) Valid
func (state BalanceObservationState) Valid() bool
type CancelWithdrawalCommand
type CancelWithdrawalCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
WithdrawalID uuid.UUID
IdempotencyKey string
}
type ChargePaymentMethodRequest
type ChargePaymentMethodRequest struct {
ProviderPaymentMethodRef ProviderPaymentMethodRef
ProviderPlayerRef ProviderPlayerRef
MerchantOrderRef MerchantOrderRef
Amount ledger.Cents
}
type CheckoutOutcome
type CheckoutOutcome string
const (
CheckoutOutcomeCreated CheckoutOutcome = "created"
CheckoutOutcomePlayerPending CheckoutOutcome = "player_pending"
CheckoutOutcomeKYCRequired CheckoutOutcome = "kyc_required"
CheckoutOutcomeRejected CheckoutOutcome = "rejected"
CheckoutOutcomeInvalidRequest CheckoutOutcome = "invalid_request"
CheckoutOutcomeUnknown CheckoutOutcome = "unknown"
CheckoutOutcomeProviderError CheckoutOutcome = "provider_error"
)
func (CheckoutOutcome) String
func (outcome CheckoutOutcome) String() string
type CheckoutTransactionIdentityGateway
CheckoutTransactionIdentityGateway permits an adapter to supply a transaction identity later, while returning a successful checkout link now.
type CheckoutTransactionIdentityGateway interface {
AllowsMissingCheckoutTransactionID() bool
}
type CloseoutCommand
type CloseoutCommand struct {
ActorID uuid.UUID
Token string
ReasonCode string
Note string
}
type CloseoutConflict
CloseoutConflict is the error for a refused close-out confirm. ClosedIDs is set only for token_used: the items the original confirm closed.
type CloseoutConflict struct {
Reason CloseoutConflictReason
ClosedIDs []uuid.UUID
}
func (*CloseoutConflict) Error
func (c *CloseoutConflict) Error() string
type CloseoutConflictReason
CloseoutConflictReason says why a close-out confirm was refused. Nothing was closed by the refused call.
type CloseoutConflictReason string
const (
// CloseoutConflictTokenUsed: the token was already confirmed, by this
// admin; the conflict carries what that confirm closed.
CloseoutConflictTokenUsed CloseoutConflictReason = "token_used"
// CloseoutConflictTokenExpired: the preview is older than its validity.
CloseoutConflictTokenExpired CloseoutConflictReason = "token_expired"
// CloseoutConflictTokenForeign: the token was issued to another admin, or
// never issued.
CloseoutConflictTokenForeign CloseoutConflictReason = "token_foreign"
// CloseoutConflictItemsChanged: an item stopped being eligible or was
// touched after the preview.
CloseoutConflictItemsChanged CloseoutConflictReason = "items_changed"
)
type CloseoutExclusion
type CloseoutExclusion struct {
Kind CloseoutItemKind
ID uuid.UUID
Reason CloseoutExclusionReason
State State
}
type CloseoutExclusionReason
CloseoutExclusionReason is why an otherwise eligible item was left out.
type CloseoutExclusionReason string
const (
// CloseoutExcludedProviderResolved: the provider check resolved the
// deposit (paid and credited, or failed); state is its new state.
CloseoutExcludedProviderResolved CloseoutExclusionReason = "provider_resolved"
// CloseoutExcludedCheckFailed: the status lookup errored, timed out or
// did not run within the preview's budget. The outcome is unknown, so the
// deposit is resolved one by one, never bulk-closed.
CloseoutExcludedCheckFailed CloseoutExclusionReason = "check_failed"
// CloseoutExcludedProviderInconclusive: the provider reports a status
// that is not an affirmative non-payment (still processing, refunded).
CloseoutExcludedProviderInconclusive CloseoutExclusionReason = "provider_inconclusive"
)
type CloseoutItem
type CloseoutItem struct {
Kind CloseoutItemKind
ID uuid.UUID
UserID uuid.UUID
UserEmail string
ProviderCode ProviderCode
State State
Amount ledger.Cents
CreatedAt time.Time
WaitingSince time.Time
ProviderCheck CloseoutProviderCheck
}
type CloseoutItemKind
CloseoutItemKind says what a close-out item is.
type CloseoutItemKind string
const (
CloseoutItemDeposit CloseoutItemKind = "deposit"
CloseoutItemOffAppDraft CloseoutItemKind = "off_app_draft"
)
type CloseoutPreview
CloseoutPreview lists what a confirm with Token would close. Token is empty when Items is.
type CloseoutPreview struct {
Token string
ExpiresAt time.Time
Items []CloseoutItem
Excluded []CloseoutExclusion
TotalAmount ledger.Cents
HasMore bool
}
type CloseoutProviderCheck
CloseoutProviderCheck is what the provider said about a closeable item at preview.
type CloseoutProviderCheck string
const (
// CloseoutCheckUnpaid: the provider's status lookup has no payment for
// the checkout (not found).
CloseoutCheckUnpaid CloseoutProviderCheck = "provider_unpaid"
// CloseoutCheckNotCheckable: the provider has no status lookup, or the
// item is an off-app draft. Closeable on age; a late success opens a case.
CloseoutCheckNotCheckable CloseoutProviderCheck = "not_checkable"
)
type CloseoutResult
type CloseoutResult struct {
IDs []uuid.UUID
}
type ConfirmWithdrawalFailedCommand
ConfirmWithdrawalFailedCommand confirms that a reconciling payout failed. ReasonCode comes from WithdrawalConfirmFailedReasons; Note is optional except for other.
type ConfirmWithdrawalFailedCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
ExpectedState State
ReasonCode string
Note string
Evidence map[string]any
IdempotencyKey string
}
type ControlWithdrawalRequest
type ControlWithdrawalRequest struct {
MerchantOrderRef MerchantOrderRef
ProviderTransactionID ProviderTransactionID
}
type ControlWithdrawalResult
type ControlWithdrawalResult struct {
Accepted bool
Evidence Evidence
}
type ConvertDepositToOffAppCommand
ConvertDepositToOffAppCommand records and settles an off-app deposit for a stuck provider deposit paid another way, and supersedes that deposit. Draft.PlayerID is ignored: the deposit's own player is credited. ReasonCode comes from OffAppConvertReasons; Note is optional except for other.
type ConvertDepositToOffAppCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
Draft OffAppDepositDraftInput
ReasonCode string
Note string
IdempotencyKey string
}
type CreateAndSettleOffAppDepositCommand
CreateAndSettleOffAppDepositCommand is an admin's one-step record-and-credit. ReasonCode comes from OffAppSettleNowReasons; Note is optional except for other.
type CreateAndSettleOffAppDepositCommand struct {
ActorID uuid.UUID
Draft OffAppDepositDraftInput
ReasonCode string
Note string
IdempotencyKey string
}
type CreateCheckoutRequest
type CreateCheckoutRequest struct {
ProviderPlayerRef ProviderPlayerRef
MerchantOrderRef MerchantOrderRef
AmountOptionRef AmountOptionRef
Amount ledger.Cents
PaymentMethodRef PaymentMethodRef
ClientIP string
Fingerprint string
}
type CreateCheckoutResult
type CreateCheckoutResult struct {
Outcome CheckoutOutcome
ProviderTransactionID *ProviderTransactionID
PaymentLink *string
KYCLink *string
Evidence Evidence
}
type CreateDepositCommand
type CreateDepositCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
ProviderCode ProviderCode
AmountOptionRef AmountOptionRef
PaymentMethodRef PaymentMethodRef
PaymentSource *PaymentSource
IdempotencyKey string
ClientIP string
UserAgent string
SessionID string
DeviceID string
}
type CreateDepositResult
type CreateDepositResult struct {
Intent Intent
PaymentLink *string
Replayed bool
}
type CreateManualClaimCommand
type CreateManualClaimCommand struct {
ReceiptAttachmentID *uuid.UUID
ActorID uuid.UUID
Method string
// PayerTag is the player's own tag the money came from (#853). Required.
PayerTag string
PaidCents int64
Note string
IdempotencyKey string
}
type CreateOffAppDepositCommand
type CreateOffAppDepositCommand struct {
ActorID uuid.UUID
Draft OffAppDepositDraftInput
IdempotencyKey string
}
type CreatePaymentMethodRequest
type CreatePaymentMethodRequest struct {
ProviderCustomerRef ProviderCustomerRef
ProviderToken ProviderToken
MethodCommandRef string
}
type CreatePaymentMethodResult
type CreatePaymentMethodResult struct {
ProviderPaymentMethodRef ProviderPaymentMethodRef
Fingerprint PaymentMethodFingerprint
Kind PaymentMethodKind
Brand string
LastFour string
ExpirationMonth int16
ExpirationYear int32
CardholderName string
Evidence Evidence
}
type CreateWithdrawalCommand
type CreateWithdrawalCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
ProviderCode ProviderCode
Amount ledger.Cents
AmountOptionRef AmountOptionRef
PaymentMethodRef PaymentMethodRef
Destination *WithdrawalDestination
IdempotencyKey string
ClientIP string
UserAgent string
SessionID string
}
type CreateWithdrawalRequest
type CreateWithdrawalRequest struct {
ProviderPlayerRef ProviderPlayerRef
MerchantOrderRef MerchantOrderRef
Amount ledger.Cents
NetAmount ledger.Cents
PaymentMethodRef PaymentMethodRef
Destination *WithdrawalDestination
ClientIP string
Fingerprint string
QuoteVersion string
QuoteSnapshot json.RawMessage
ManualOnly bool
}
type CreateWithdrawalResult
type CreateWithdrawalResult struct {
Intent WithdrawalIntent
Replayed bool
}
type DecideManualClaimCommand
type DecideManualClaimCommand struct {
ActorID uuid.UUID
ClaimID uuid.UUID
Decision string
CreditCents *int64
Reason string
}
type DepositAmountOption
type DepositAmountOption struct {
Ref AmountOptionRef
Amount ledger.Cents
CreditedAmount ledger.Cents
Label string
Currency ledger.CurrencyCode
}
type DepositFailure
type DepositFailure struct {
Reason DepositFailureReason `json:"reason"`
ProviderStatus string `json:"provider_status"`
ProviderMessage string `json:"provider_message"`
Message string `json:"message"`
}
type DepositFailureEvidenceGateway
DepositFailureEvidenceGateway decodes stored diagnostics without network IO. Vendor fields and status formats stay inside the implementing adapter.
type DepositFailureEvidenceGateway interface {
DepositFailureFromEvidence([]byte) *DepositFailure
}
type DepositFailureReason
type DepositFailureReason string
const (
DepositFailureCardDeclined DepositFailureReason = "card_declined"
DepositFailureInsufficientFunds DepositFailureReason = "insufficient_funds"
DepositFailureAuthenticationFailed DepositFailureReason = "authentication_failed"
DepositFailureProviderRejected DepositFailureReason = "provider_rejected"
)
type DepositLatePaidEvent
type DepositLatePaidEvent struct {
Kind DepositLatePaidEventKind `json:"kind"`
At *time.Time `json:"at,omitempty"`
AmountCents *int64 `json:"amount_cents,omitempty"`
WalletCreditCents *int64 `json:"wallet_credit_cents,omitempty"`
StaffName *string `json:"staff_name,omitempty"`
RelatedPaymentID *uuid.UUID `json:"related_payment_id,omitempty"`
ProviderStatus *string `json:"provider_status,omitempty"`
ProviderReference *string `json:"provider_reference,omitempty"`
}
type DepositLatePaidEventKind
type DepositLatePaidEventKind string
const (
LatePaidDepositCreated DepositLatePaidEventKind = "deposit_created"
LatePaidProviderFailed DepositLatePaidEventKind = "provider_failed"
LatePaidStaffCredited DepositLatePaidEventKind = "staff_credited"
LatePaidPossibleCredit DepositLatePaidEventKind = "possible_staff_credit"
LatePaidNoLinkedCredit DepositLatePaidEventKind = "no_linked_staff_credit"
LatePaidProviderCallback DepositLatePaidEventKind = "provider_paid_callback"
LatePaidProviderLookup DepositLatePaidEventKind = "provider_paid_lookup"
LatePaidCreditRefused DepositLatePaidEventKind = "second_credit_refused"
)
type DepositLatePaidReview
type DepositLatePaidReview struct {
Events []DepositLatePaidEvent `json:"events"`
}
type DepositMethodKind
type DepositMethodKind string
const (
DepositMethodKindCashApp DepositMethodKind = "cash_app"
DepositMethodKindChime DepositMethodKind = "chime"
DepositMethodKindCard DepositMethodKind = "card"
DepositMethodKindApplePay DepositMethodKind = "apple_pay"
DepositMethodKindGooglePay DepositMethodKind = "google_pay"
DepositMethodKindCrypto DepositMethodKind = "crypto"
DepositMethodKindWallet DepositMethodKind = "wallet"
)
type DepositMethodKindsGateway
DepositMethodKindsGateway declares static adapter support without network calls, credentials, release gates or live payment options.
type DepositMethodKindsGateway interface {
DepositMethodKinds() []DepositMethodKind
}
type DepositMethodOption
type DepositMethodOption struct {
ID string
AutomaticRouting bool
DisplayName string
MethodKinds []DepositMethodKind
Recommended bool
Featured bool
MinimumAmount ledger.Cents
Amounts []DepositAmountOption
AmountRangeStep ledger.Cents
Routing DepositRouting
Flow PaymentFlow
Tokenization *TokenizationConfig
AccountSetupState AccountSetupState
}
type DepositMethodProviders
type DepositMethodProviders struct {
MethodKind DepositMethodKind
Providers []DepositProviderAvailability
}
type DepositMinimumGateway
type DepositMinimumGateway interface {
DepositMinimum(context.Context, PaymentMethodRef) (DepositMinimumResult, error)
}
type DepositMinimumResult
type DepositMinimumResult struct {
MinimumAmount ledger.Cents
CachedUntil time.Time
}
type DepositPolicy
type DepositPolicy struct {
ProviderOutcomes []DepositProviderOutcomes `json:"provider_outcomes"`
ManualPolicy *ManualClaimPolicy
History []PaymentSettingsChange
Rules []DepositRoutingRule
MethodProviders []DepositMethodProviders
Version int64
}
type DepositProofAsset
type DepositProofAsset struct {
ID uuid.UUID
PaymentID uuid.UUID
UploaderID uuid.UUID
State WithdrawalProofAssetState
OriginalFilename string
DeclaredMIME string
DetectedMIME *string
DeclaredSize int64
ActualSize *int64
ChecksumSHA256 string
ETag *string
VersionID *string
UploadExpiresAt time.Time
FinalizedAt *time.Time
CreatedAt time.Time
}
type DepositProviderAvailability
type DepositProviderAvailability struct {
ProviderCode ProviderCode
Configured bool
}
type DepositProviderOutcomes
type DepositProviderOutcomes struct {
ProviderCode ProviderCode `json:"provider_code"`
WindowMinutes int64 `json:"window_minutes"`
Succeeded int64 `json:"succeeded"`
Failed int64 `json:"failed"`
Pending int64 `json:"pending"`
Unresolved int64 `json:"unresolved"`
SuccessRateBps *int64 `json:"success_rate_bps"`
}
type DepositRouting
type DepositRouting struct {
ProviderCode ProviderCode
PaymentMethodRef PaymentMethodRef
}
type DepositRoutingRule
type DepositRoutingRule struct {
MethodKind DepositMethodKind `json:"method_kind"`
ProviderCode ProviderCode `json:"provider_code"`
Enabled bool `json:"enabled"`
Configured bool `json:"-"`
MinAmount ledger.Cents `json:"min_amount_cents"`
MaxAmount *ledger.Cents `json:"max_amount_cents"`
}
type DepositRoutingRuleError
DepositRoutingRuleError identifies a rejected replacement-list field. It contains validation text only, never credentials or vendor responses.
type DepositRoutingRuleError struct {
Index int
Field string
Reason string
}
func (*DepositRoutingRuleError) Error
func (e *DepositRoutingRuleError) Error() string
func (*DepositRoutingRuleError) Unwrap
func (*DepositRoutingRuleError) Unwrap() error
type DirectChargeOutcome
type DirectChargeOutcome string
const (
DirectChargeOutcomeSucceeded DirectChargeOutcome = "succeeded"
DirectChargeOutcomePending DirectChargeOutcome = "pending"
DirectChargeOutcomeDeclined DirectChargeOutcome = "declined"
DirectChargeOutcomeUnknown DirectChargeOutcome = "unknown"
)
type DirectChargeResult
type DirectChargeResult struct {
Outcome DirectChargeOutcome
ProviderTransactionID ProviderTransactionID
Evidence Evidence
}
type DirectPaymentGateway
DirectPaymentGateway is the narrow provider boundary required by the first saved-card implementation. Provider tokens and provider resource shapes stay behind this interface; the payment service persists only normalized method metadata and provider references.
type DirectPaymentGateway interface {
EnsurePaymentCustomer(context.Context, EnsurePaymentCustomerRequest) (EnsurePaymentCustomerResult, error)
CreatePaymentMethod(context.Context, CreatePaymentMethodRequest) (CreatePaymentMethodResult, error)
ChargePaymentMethod(context.Context, ChargePaymentMethodRequest) (DirectChargeResult, error)
DisablePaymentMethod(context.Context, DisablePaymentMethodRequest) (DisablePaymentMethodResult, error)
}
type DisablePaymentMethodRequest
type DisablePaymentMethodRequest struct {
ProviderPaymentMethodRef ProviderPaymentMethodRef
}
type DisablePaymentMethodResult
type DisablePaymentMethodResult struct {
Disabled bool
Evidence Evidence
}
type EnsurePaymentCustomerRequest
type EnsurePaymentCustomerRequest struct {
UserID string
Email string
FullName string
ExistingRef *ProviderCustomerRef
}
type EnsurePaymentCustomerResult
type EnsurePaymentCustomerResult struct {
ProviderCustomerRef ProviderCustomerRef
Evidence Evidence
}
type EnsurePlayerRequest
type EnsurePlayerRequest struct {
UserID string
Username string
Email string
FullName string
ExistingRef *ProviderPlayerRef
}
type EnsurePlayerResult
type EnsurePlayerResult struct {
ProviderPlayerRef ProviderPlayerRef
Status ProviderPlayerStatus
Evidence Evidence
}
type ErrorCode
type ErrorCode string
const (
ErrorCodeBonusRecoveryRequired ErrorCode = "bonus_recovery_required"
ErrorCodeInvalidRequest ErrorCode = "invalid_request"
ErrorCodeDisabled ErrorCode = "disabled"
ErrorCodeDepositMethodHidden ErrorCode = "deposit_method_hidden"
ErrorCodeHousePayoutPolicyChanged ErrorCode = "house_payout_policy_changed"
ErrorCodePaymentReceiptInvalid ErrorCode = "payment_receipt_invalid"
ErrorCodeIdempotencyConflict ErrorCode = "idempotency_conflict"
ErrorCodeInsufficientFunds ErrorCode = "insufficient_funds"
ErrorCodeProviderUnavailable ErrorCode = "provider_unavailable"
)
const ErrorCodePolicyChanged ErrorCode = "policy_changed"
type EventType
type EventType string
const (
EventDepositStatusLookupSucceeded EventType = "deposit_status_lookup_succeeded"
EventDepositDirectSucceeded EventType = "deposit_direct_succeeded"
EventDepositStaffConfirmed EventType = "deposit_staff_confirmed"
)
const (
EventIntentCreated EventType = "intent_created"
EventPlayerSignupSucceeded EventType = "player_signup_succeeded"
EventPlayerSignupRejected EventType = "player_signup_rejected"
EventCheckoutCreated EventType = "checkout_created"
EventProviderCreated EventType = "provider_created"
EventProviderRejected EventType = "provider_rejected"
EventProviderTimeout EventType = "provider_timeout"
EventWebhookReceived EventType = "webhook_received"
EventWebhookPaidAccepted EventType = "webhook_paid_accepted"
EventWebhookDuplicate EventType = "webhook_duplicate"
EventWebhookInvalidSignature EventType = "webhook_invalid_signature"
EventWebhookUnmatched EventType = "webhook_unmatched"
EventWebhookMismatch EventType = "webhook_mismatch"
EventWebhookNonPaid EventType = "webhook_non_paid"
EventWalletCreditSucceeded EventType = "wallet_credit_succeeded"
EventStateChanged EventType = "state_changed"
EventWithdrawalIntentCreated EventType = "withdrawal_intent_created"
EventWithdrawalReserved EventType = "withdrawal_reserved"
EventWithdrawalApproved EventType = "withdrawal_approved"
EventWithdrawalRejected EventType = "withdrawal_rejected"
EventWithdrawalCanceled EventType = "withdrawal_canceled"
EventWithdrawalExpired EventType = "withdrawal_expired"
EventWithdrawalDispatchQueued EventType = "withdrawal_dispatch_queued"
EventWithdrawalActionRequired EventType = "withdrawal_action_required"
EventWithdrawalQuoteReview EventType = "withdrawal_quote_review_required"
EventWithdrawalConfirmedFailed EventType = "withdrawal_admin_confirmed_failed"
EventWithdrawalAdminMarkedPaid EventType = "withdrawal_admin_marked_paid"
EventWithdrawalProviderCreated EventType = "withdrawal_provider_created"
EventWithdrawalWalletDebited EventType = "withdrawal_wallet_debited"
EventWithdrawalWebhookSucceeded EventType = "withdrawal_webhook_succeeded"
EventWithdrawalWebhookDuplicate EventType = "withdrawal_webhook_duplicate"
EventWithdrawalWebhookInvalid EventType = "withdrawal_webhook_invalid_signature"
EventWithdrawalWebhookUnmatched EventType = "withdrawal_webhook_unmatched"
EventWithdrawalWebhookMismatch EventType = "withdrawal_webhook_mismatch"
EventWithdrawalWebhookNonSuccess EventType = "withdrawal_webhook_non_success"
EventOffAppDraftCreated EventType = "off_app_draft_created"
EventOffAppDraftUpdated EventType = "off_app_draft_updated"
EventOffAppSettled EventType = "off_app_settled"
EventOffAppVoided EventType = "off_app_voided"
EventOffAppReversalBlocked EventType = "off_app_reversal_blocked"
EventOffAppReversed EventType = "off_app_reversed"
EventSupersededByOffApp EventType = "superseded_by_off_app"
)
func (EventType) String
func (event EventType) String() string
type Evidence
type Evidence struct {
LatePaidReview *DepositLatePaidReview `json:"late_paid_review,omitempty"`
DepositFailure *DepositFailure `json:"deposit_failure,omitempty"`
DepositAmountPaidCents *ledger.Cents `json:"deposit_amount_paid_cents,omitempty"`
DepositPrincipalCents *ledger.Cents `json:"deposit_principal_cents,omitempty"`
ProviderCode ProviderCode `json:"provider_code"`
Operation string `json:"operation"`
HTTPStatus *int `json:"http_status,omitempty"`
ProviderStatus string `json:"provider_status,omitempty"`
ProviderMessage string `json:"provider_message,omitempty"`
RequestID string `json:"request_id,omitempty"`
RawRequest *RedactedPayload `json:"raw_request,omitempty"`
RawResponse *RedactedPayload `json:"raw_response,omitempty"`
SignatureValid *bool `json:"signature_valid,omitempty"`
SignatureVersion string `json:"signature_version,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
ObservedAt time.Time `json:"observed_at"`
RedactionVersion string `json:"redaction_version"`
}
type ExpireWithdrawalCommand
type ExpireWithdrawalCommand struct {
WithdrawalID uuid.UUID
IdempotencyKey string
}
type FinalizeDepositProofUploadCommand
type FinalizeDepositProofUploadCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
ProofAssetID uuid.UUID
IdempotencyKey string
}
type FinalizeDepositProofUploadResult
type FinalizeDepositProofUploadResult struct {
Asset DepositProofAsset
Replayed bool
}
type FinalizeWithdrawalProofUploadCommand
type FinalizeWithdrawalProofUploadCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
ProofAssetID uuid.UUID
}
type Gateway
type Gateway interface {
ListOptions(context.Context) (Options, error)
EnsurePlayer(context.Context, EnsurePlayerRequest) (EnsurePlayerResult, error)
CreateCheckout(context.Context, CreateCheckoutRequest) (CreateCheckoutResult, error)
VerifyWebhook(context.Context, VerifyWebhookRequest) (VerifiedWebhook, WebhookAck, error)
}
type HostedPaymentMethodIdentityGateway
HostedPaymentMethodIdentityGateway pins the provider's hosted payment method to the immutable method selected for the intent.
type HostedPaymentMethodIdentityGateway interface {
PinHostedPaymentMethod() bool
}
type HouseDepositMethod
type HouseDepositMethod struct {
HousePaymentMethod
Rounding HouseMethodRounding `json:"rounding"`
}
type HouseMethodIcon
type HouseMethodIcon string
const (
HouseMethodIconWallet HouseMethodIcon = "wallet"
HouseMethodIconBank HouseMethodIcon = "bank"
HouseMethodIconPhone HouseMethodIcon = "phone"
)
type HouseMethodRounding
type HouseMethodRounding string
const (
HouseMethodRoundingNone HouseMethodRounding = "none"
HouseMethodRoundingCeilDollar HouseMethodRounding = "ceil_dollar"
)
type HousePaymentMethod
HousePaymentMethod is a public house account configuration, never a player destination. Input is normalized by the one shared smart-input parser before policy storage.
type HousePaymentMethod struct {
ID string `json:"id"`
Name string `json:"name"`
Icon HouseMethodIcon `json:"icon"`
LogoDataURL string `json:"logo_data_url"`
Enabled bool `json:"enabled"`
Input string `json:"input"`
QRPayload string `json:"qr_payload"`
Tag string `json:"tag"`
PaymentLink string `json:"payment_link"`
}
type HousePayoutMethod
type HousePayoutMethod struct {
HousePaymentMethod
AllowPlayerModeChoice bool `json:"allow_player_mode_choice"`
DefaultMode HousePayoutMode `json:"default_mode"`
}
type HousePayoutMode
type HousePayoutMode string
const (
HousePayoutPayPlayer HousePayoutMode = "pay_player"
HousePayoutRequestOnHouseTag HousePayoutMode = "request_on_house_tag"
)
type InitiateDepositProofUploadCommand
type InitiateDepositProofUploadCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
OriginalFilename string
ContentType string
SizeBytes int64
ChecksumSHA256 string
IdempotencyKey string
}
type InitiateDepositProofUploadResult
type InitiateDepositProofUploadResult struct {
Asset DepositProofAsset
UploadURL string
Headers map[string]string
Replayed bool
}
type InitiateWithdrawalProofUploadCommand
type InitiateWithdrawalProofUploadCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
OriginalFilename string
ContentType string
SizeBytes int64
ChecksumSHA256 string
}
type InitiateWithdrawalProofUploadResult
type InitiateWithdrawalProofUploadResult struct {
Asset WithdrawalProofAsset
UploadURL string
Headers map[string]string
}
type Intent
type Intent struct {
Failure *DepositFailure
ID uuid.UUID
UserID uuid.UUID
ProviderCode ProviderCode
State State
Amount ledger.Cents
CreditedAmount *ledger.Cents
Currency ledger.CurrencyCode
AmountOptionRef AmountOptionRef
PaymentMethodRef PaymentMethodRef
ProviderPlayerRef *ProviderPlayerRef
ProviderTransactionID *ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
CheckoutURL *string
KYCLink *string
WalletCreditTxnID *uuid.UUID
StaleAfter *time.Time
CreatedAt time.Time
UpdatedAt time.Time
}
type ListCommand
type ListCommand struct {
UserID uuid.UUID
State *State
Page int
PerPage int
}
type ListResult
type ListResult struct {
Payments []Intent
Page int
PerPage int
HasNext bool
}
type ListWithdrawalsCommand
type ListWithdrawalsCommand struct {
UserID uuid.UUID
State *State
Page int
PerPage int
}
type ListWithdrawalsResult
type ListWithdrawalsResult struct {
Withdrawals []WithdrawalIntent
Page int
PerPage int
HasNext bool
}
type LiveWithdrawalQuoteGateway
type LiveWithdrawalQuoteGateway interface {
QuoteWithdrawal(context.Context, QuoteWithdrawalRequest) (QuoteWithdrawalResult, error)
}
type LookupPaymentStatusRequest
type LookupPaymentStatusRequest struct {
ProviderTransactionID *ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
ProviderPlayerRef *ProviderPlayerRef
ProviderPaymentMethodRef *ProviderPaymentMethodRef
ExpectedAmount *ledger.Cents
}
type LookupPaymentStatusResult
type LookupPaymentStatusResult struct {
Found bool
Status ProviderPaymentStatus
ProviderTransactionID ProviderTransactionID
Evidence Evidence
}
type LookupWithdrawalStatusRequest
type LookupWithdrawalStatusRequest struct {
ProviderTransactionID *ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
ProviderPlayerRef *ProviderPlayerRef
}
type LookupWithdrawalStatusResult
type LookupWithdrawalStatusResult struct {
Found bool
Status ProviderPaymentStatus
ProviderTransactionID ProviderTransactionID
// RequestedAmount is optional because some providers report only the net fiat payout.
RequestedAmount *ledger.Cents
// SettledAmount is the provider-reported net fiat payout.
SettledAmount ledger.Cents
Evidence Evidence
}
type ManualClaim
ManualClaim preserves the player's receipt separately from the approved credit.
type ManualClaim struct {
MethodName string `json:"method_name"`
PayerTag *string `json:"payer_tag,omitempty"`
ReceiptAttachmentID *uuid.UUID `json:"receipt_attachment_id,omitempty"`
RoundUpCents int64 `json:"round_up_cents"`
ID uuid.UUID `json:"id"`
ConversationID uuid.UUID `json:"conversation_id"`
UserID uuid.UUID `json:"user_id"`
Method string `json:"method"`
PaidCents int64 `json:"paid_cents"`
SuggestedCreditCents int64 `json:"suggested_credit_cents"`
CreditCents *int64 `json:"credit_cents"`
Note string `json:"note"`
Status ManualClaimStatus `json:"status"`
Reason string `json:"reason"`
PaymentID *uuid.UUID `json:"payment_id"`
CreatedAt time.Time `json:"created_at"`
DecidedByLabel *string `json:"decided_by_label,omitempty"`
DecidedBy *uuid.UUID `json:"decided_by,omitempty"`
DecidedAt *time.Time `json:"decided_at,omitempty"`
}
type ManualClaimPolicy
type ManualClaimPolicy struct {
MethodDisplayOrder PaymentMethodDisplayOrder `json:"method_display_order"`
PayoutMethods []HousePayoutMethod `json:"payout_methods"`
AdditionalDepositMethods []HouseDepositMethod `json:"additional_deposit_methods"`
AllowTips bool `json:"allow_tips"`
WithdrawalMinimumCents int64 `json:"withdrawal_minimum_cents"`
CashAppTag string `json:"cash_app_tag"`
ChimeTag string `json:"chime_tag"`
PayPalEmail string `json:"paypal_email"`
CashAppPaymentLink string `json:"cash_app_payment_link"`
CashAppInput string `json:"cash_app_input,omitempty"`
ChimeInput string `json:"chime_input,omitempty"`
PayPalInput string `json:"paypal_input,omitempty"`
ChimePaymentLink string `json:"chime_payment_link"`
PayPalPaymentLink string `json:"paypal_payment_link"`
CashAppRounding string `json:"cash_app_rounding"`
ChimeRounding string `json:"chime_rounding"`
PayPalRounding string `json:"paypal_rounding"`
CashAppQRPayload string `json:"cash_app_qr_payload"`
ChimeQRPayload string `json:"chime_qr_payload"`
PayPalQRPayload string `json:"paypal_qr_payload"`
EnabledMethods []string `json:"enabled_methods"`
Version int64 `json:"version"`
}
type ManualClaimStatus
type ManualClaimStatus string
const (
ManualClaimPending ManualClaimStatus = "pending"
ManualClaimApproved ManualClaimStatus = "approved"
ManualClaimRejected ManualClaimStatus = "rejected"
)
type ManualPaymentInput
ManualPaymentInput is the parsed receiving identity; opening it never pays or credits.
type ManualPaymentInput struct {
Method ManualPaymentInputMethod `json:"method"`
Tag string `json:"tag"`
PaymentLink string `json:"payment_link"`
Label string `json:"label"`
}
type ManualPaymentInputMethod
ManualPaymentInputMethod describes parsing, not deposit/payout eligibility.
type ManualPaymentInputMethod string
const (
ManualPaymentInputCashApp ManualPaymentInputMethod = "cash_app"
ManualPaymentInputChime ManualPaymentInputMethod = "chime"
ManualPaymentInputPayPal ManualPaymentInputMethod = "paypal"
ManualPaymentInputVenmo ManualPaymentInputMethod = "venmo"
ManualPaymentInputCustom ManualPaymentInputMethod = "custom"
)
type ManualPaymentLinkError
ManualPaymentLinkError never includes the submitted URL or its query fields.
type ManualPaymentLinkError struct{}
func (*ManualPaymentLinkError) Error
func (e *ManualPaymentLinkError) Error() string
func (*ManualPaymentLinkError) SafeMessage
func (e *ManualPaymentLinkError) SafeMessage() string
func (*ManualPaymentLinkError) Unwrap
func (e *ManualPaymentLinkError) Unwrap() error
type ManualPayoutConflictReason
ManualPayoutConflictReason says why a manual mark-paid conflicted.
type ManualPayoutConflictReason string
const (
ManualPayoutConflictReviewRequired ManualPayoutConflictReason = "review_required"
ManualPayoutConflictDuplicateReference ManualPayoutConflictReason = "duplicate_reference"
ManualPayoutConflictStateChanged ManualPayoutConflictReason = "state_changed"
)
func ManualPayoutConflict
func ManualPayoutConflict(err error) (ManualPayoutConflictReason, string)
ManualPayoutConflict classifies a conflicting manual mark-paid and gives the operator guidance for it.
func ManualPayoutConflictReasons
func ManualPayoutConflictReasons() []ManualPayoutConflictReason
ManualPayoutConflictReasons lists every conflict reason; OpenAPI's ManualPayoutConflictReason mirrors it.
type ManualPayoutFeeDetails
type ManualPayoutFeeDetails struct {
FeeCents ledger.Cents
AmountCents ledger.Cents
FeeLimitCents ledger.Cents
}
type ManualPayoutPaidReason
ManualPayoutPaidReason is the structured reason an admin records when a manual payout is marked paid.
type ManualPayoutPaidReason string
const (
ManualPayoutPaidAsRequested ManualPayoutPaidReason = "paid_as_requested"
ManualPayoutPaidOther ManualPayoutPaidReason = "other"
)
func (ManualPayoutPaidReason) Valid
func (r ManualPayoutPaidReason) Valid() bool
type ManualPayoutPaidVia
ManualPayoutPaidVia records how the operator actually sent the payment.
type ManualPayoutPaidVia string
const (
ManualPayoutPaidViaCashApp ManualPayoutPaidVia = "cash_app"
ManualPayoutPaidViaChime ManualPayoutPaidVia = "chime"
ManualPayoutPaidViaPayPal ManualPayoutPaidVia = "paypal"
ManualPayoutPaidViaOther ManualPayoutPaidVia = "other"
)
func (ManualPayoutPaidVia) Valid
func (v ManualPayoutPaidVia) Valid() bool
type ManualPayoutPreview
type ManualPayoutPreview struct {
FeeLimitCents ledger.Cents
AmountCents ledger.Cents
FeeCents ledger.Cents
TipCents ledger.Cents
NetCents ledger.Cents
Valid bool
}
type ManualPayoutReferenceConflict
ManualPayoutReferenceConflict is private operator evidence, exposed only by the authenticated admin mark-paid adapter.
type ManualPayoutReferenceConflict struct {
CashoutID uuid.UUID
PlayerLabel string
AmountCents ledger.Cents
CashoutCreatedAt time.Time
}
type ManualQRPayloadError
ManualQRPayloadError deliberately contains no uploaded or decoded content.
type ManualQRPayloadError struct {
Reason ManualQRPayloadReason
Field string
}
func (*ManualQRPayloadError) Error
func (e *ManualQRPayloadError) Error() string
func (*ManualQRPayloadError) SafeMessage
func (e *ManualQRPayloadError) SafeMessage() string
func (*ManualQRPayloadError) Unwrap
func (e *ManualQRPayloadError) Unwrap() error
type ManualQRPayloadReason
type ManualQRPayloadReason string
const (
ManualQRTooLong ManualQRPayloadReason = "qr_payload_too_long"
ManualQRInvalid ManualQRPayloadReason = "qr_payload_invalid"
ManualQRUnsupportedScheme ManualQRPayloadReason = "qr_payload_unsupported_scheme"
)
type ManualReceiptClaimMatch
type ManualReceiptClaimMatch struct {
ClaimID uuid.UUID
PaidCents int64
Status ManualClaimStatus
CreatedAt time.Time
}
type ManualWithdrawalOptionsGateway
type ManualWithdrawalOptionsGateway interface {
ListManualWithdrawalOptions(context.Context) (WithdrawalOptions, error)
}
type MarkManualPayoutPaidCommand
MarkManualPayoutPaidCommand is the admin's Approve of a cash-out sent by hand (ADR 0019, 2026-11-16 amendment): it is refused unless PlayerPaidConfirmed is true, and it records the payout paid. ExpectedState awaiting_approval approves and records it paid in one step; provider_created finishes a payout approved before the amendment. A nil fee means zero; the net is always computed by the database. ReasonCode defaults to paid_as_requested; other needs a note. ApprovalReasonCode (from WithdrawalApprovalReasons) and ApprovalNote record why the admin approved; they are required while the player has open risk signals.
type MarkManualPayoutPaidCommand struct {
PayingClaimID uuid.UUID
ClaimReviewEvidence string
ActorID uuid.UUID
WithdrawalID uuid.UUID
ExpectedState State
PlayerPaidConfirmed bool
Reference string
PaidVia *ManualPayoutPaidVia
Tag string
ProofAssetID *uuid.UUID
FeeCents *ledger.Cents
ReasonCode *ManualPayoutPaidReason
Note *string
ApprovalReasonCode string
ApprovalNote string
IdempotencyKey string
}
type MarkWithdrawalPaidCommand
type MarkWithdrawalPaidCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
ExpectedState State
ProviderTransactionID ProviderTransactionID
ProviderReference string
ProofAssetID uuid.UUID
ActualFee ledger.Cents
ActualNet ledger.Cents
OperatorReason string
Evidence map[string]any
IdempotencyKey string
}
type MaskedWithdrawalDestination
MaskedWithdrawalDestination is a withdrawal destination that is safe to display. It is a distinct type so a masked value can never be passed where a raw WithdrawalDestination is expected (dispatch, quotes). The only producer is internal/payments/redact.WithdrawalDestination.
type MaskedWithdrawalDestination struct {
ReceiptAttachmentID *uuid.UUID `json:"receipt_attachment_id,omitempty"`
ManualKind ManualPaymentInputMethod `json:"manual_kind,omitempty"`
ManualTag string `json:"manual_tag,omitempty"`
MethodName string `json:"method_name,omitempty"`
HousePaymentLink string `json:"house_payment_link,omitempty"`
HouseQRPayload string `json:"house_qr_payload,omitempty"`
HousePolicyVersion int64 `json:"house_policy_version,omitempty"`
TipCents ledger.Cents `json:"tip_cents,omitempty"`
TipNote string `json:"tip_note,omitempty"`
Mode HousePayoutMode `json:"mode,omitempty"`
HouseTag string `json:"house_tag,omitempty"`
Kind WithdrawalDestinationKind `json:"kind"`
CashAppTag string `json:"cash_app_tag,omitempty"`
ChimeTag string `json:"chime_tag,omitempty"`
PayPalEmail string `json:"paypal_email,omitempty"`
ChimeAccount string `json:"chime_account,omitempty"`
Network string `json:"network,omitempty"`
Address string `json:"address,omitempty"`
Memo string `json:"memo,omitempty"`
}
type MerchantOrderRef
type MerchantOrderRef string
type OffAppDepositCommandResult
type OffAppDepositCommandResult struct {
PaymentID uuid.UUID
Replayed bool
}
type OffAppDepositDraftInput
type OffAppDepositDraftInput struct {
PlayerID uuid.UUID
Amount ledger.Cents
PaymentMethod OffAppDepositMethod
OtherLabel *string
PayerReference *string
ExternalReference *string
ReceivedAt time.Time
InternalNote string
}
type OffAppDepositMethod
type OffAppDepositMethod string
const (
OffAppDepositMethodCashApp OffAppDepositMethod = "cash_app"
OffAppDepositMethodChime OffAppDepositMethod = "chime"
OffAppDepositMethodPayPal OffAppDepositMethod = "paypal"
OffAppDepositMethodCard OffAppDepositMethod = "card"
OffAppDepositMethodBank OffAppDepositMethod = "bank"
OffAppDepositMethodCrypto OffAppDepositMethod = "crypto"
OffAppDepositMethodOther OffAppDepositMethod = "other"
)
type OffAppDepositReversalPreview
type OffAppDepositReversalPreview struct {
PaymentID uuid.UUID
ExpectedState State
Principal ledger.Cents
WalletCredit ledger.Cents
HouseSubsidy ledger.Cents
Reversible bool
Blockers []ReversalBlocker
}
type Options
type Options struct {
ProviderCode ProviderCode
Flow PaymentFlow
Tokenization *TokenizationConfig
AccountSetupState AccountSetupState
Amounts []AmountOption
PaymentMethods []PaymentMethodOption
CachedUntil time.Time
}
type OptionsCatalog
type OptionsCatalog struct {
Methods []DepositMethodOption
AutomaticRouting bool
}
type PaymentFlow
type PaymentFlow string
const (
PaymentFlowHostedCheckout PaymentFlow = "hosted_checkout"
PaymentFlowDirectSavedMethod PaymentFlow = "direct_saved_method"
)
type PaymentInputError
type PaymentInputError struct {
Field string
Reason string
Message string
}
func (*PaymentInputError) Error
func (e *PaymentInputError) Error() string
func (*PaymentInputError) SafeMessage
func (e *PaymentInputError) SafeMessage() string
func (*PaymentInputError) Unwrap
func (e *PaymentInputError) Unwrap() error
type PaymentMethodDisplayOrder
PaymentMethodDisplayOrder uses stable card keys; online/house variants share a key. Unlisted methods retain their existing relative order after explicit entries.
type PaymentMethodDisplayOrder struct {
Deposit []string `json:"deposit"`
Payout []string `json:"payout"`
}
type PaymentMethodFingerprint
type PaymentMethodFingerprint string
type PaymentMethodKind
type PaymentMethodKind string
const (
PaymentMethodKindCard PaymentMethodKind = "card"
)
type PaymentMethodOption
type PaymentMethodOption struct {
WithdrawalAllowTips bool
WithdrawalHouseTag string
WithdrawalHousePaymentLink string
WithdrawalHouseQRPayload string
WithdrawalDefaultMode HousePayoutMode
WithdrawalPayoutModes []HousePayoutMode
WithdrawalInputKind ManualPaymentInputMethod
WithdrawalMethodIcon HouseMethodIcon
WithdrawalMethodLogo string
WithdrawalPolicyVersion int64
Ref PaymentMethodRef
// Amounts overrides provider-wide amounts when non-nil; an empty list offers none.
Amounts []AmountOption
// AmountRangeStep declares range presentation; zero keeps every preset visible.
AmountRangeStep ledger.Cents
DisplayName string
MethodKinds []DepositMethodKind
Recommended bool
Featured bool
MinimumAmount ledger.Cents
ProviderCode ProviderCode
WithdrawalDestination WithdrawalDestinationKind
WithdrawalDestinationLabel string
WithdrawalNetwork string
WithdrawalMemoRequired bool
}
type PaymentMethodRef
type PaymentMethodRef string
type PaymentMethodState
type PaymentMethodState string
const (
PaymentMethodStateActive PaymentMethodState = "active"
PaymentMethodStateRemovalPending PaymentMethodState = "removal_pending"
PaymentMethodStateRemoved PaymentMethodState = "removed"
)
type PaymentProviderBalance
type PaymentProviderBalance struct {
ProviderCode ProviderCode
State BalanceObservationState
CheckedAt time.Time
AsOf *time.Time
CachedUntil time.Time
Reason BalanceFailureReason
Amounts []ProviderBalanceAmount
}
type PaymentSettingsChange
type PaymentSettingsChange struct {
ID uuid.UUID
CreatedAt time.Time
ActorLabel string
Kind PaymentSettingsChangeKind
Reason string
}
type PaymentSettingsChangeKind
type PaymentSettingsChangeKind string
const (
SettingsChangeCombined PaymentSettingsChangeKind = "payment_settings"
SettingsChangeRouting PaymentSettingsChangeKind = "provider_routing"
SettingsChangeManual PaymentSettingsChangeKind = "manual_settings"
)
type PaymentSource
type PaymentSource struct {
Kind PaymentSourceKind
PaymentMethodID *uuid.UUID
ProviderToken ProviderToken
}
type PaymentSourceKind
type PaymentSourceKind string
const (
PaymentSourceKindSavedPaymentMethod PaymentSourceKind = "saved_payment_method"
PaymentSourceKindNewPaymentMethod PaymentSourceKind = "new_payment_method"
)
type PaymentVendor
PaymentVendor is a configured payment processor, separate from game stores.
type PaymentVendor struct {
Code ProviderCode
DisplayName string
PanelURL *string
BalanceSupported bool
}
type PayoutConfigurationFault
PayoutConfigurationFault is observed runtime configuration health, never a player or transfer failure. It is re-established by startup/provider probes.
type PayoutConfigurationFault struct {
ProviderCode ProviderCode `json:"provider_code"`
Since time.Time `json:"since"`
Endpoint string `json:"endpoint"`
}
type PayoutConfigurationFaultGateway
type PayoutConfigurationFaultGateway interface {
PayoutConfigurationFault() *PayoutConfigurationFault
}
type PlayerDepositMethod
type PlayerDepositMethod struct {
ID string
CustomName string
Configured bool
Hidden bool
}
type PlayerDepositMethodChange
type PlayerDepositMethodChange struct {
ActorID uuid.UUID
ActorLabel string
ChangedAt time.Time
}
type PlayerDepositVisibility
type PlayerDepositVisibility struct {
Revision int64
Methods []PlayerDepositMethod
LastChange *PlayerDepositMethodChange
}
type PreviewDepositProofCommand
type PreviewDepositProofCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
ProofAssetID uuid.UUID
}
type PreviewWithdrawalMinimumCommand
type PreviewWithdrawalMinimumCommand struct {
UserID uuid.UUID
ProviderCode ProviderCode
PaymentMethodRef PaymentMethodRef
}
type PreviewWithdrawalMinimumResult
type PreviewWithdrawalMinimumResult struct {
MinimumAmount ledger.Cents
Currency ledger.CurrencyCode
CachedUntil time.Time
}
type PreviewWithdrawalProofCommand
type PreviewWithdrawalProofCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
ProofAssetID uuid.UUID
}
type PreviewWithdrawalQuoteCommand
type PreviewWithdrawalQuoteCommand struct {
UserID uuid.UUID
ProviderCode ProviderCode
Amount ledger.Cents
PaymentMethodRef PaymentMethodRef
Destination *WithdrawalDestination
}
type PreviewWithdrawalQuoteResult
type PreviewWithdrawalQuoteResult struct {
TipCents ledger.Cents
Amount ledger.Cents
EstimatedFee ledger.Cents
EstimatedNet ledger.Cents
Currency ledger.CurrencyCode
QuoteVersion string
}
type ProviderBalanceAmount
ProviderBalanceAmount is an exact external asset observation, not wallet money. USD Units are integer cents (DecimalPlaces=2); other assets retain their exact scale.
type ProviderBalanceAmount struct {
Currency string
Kind BalanceAmountKind
Units int64
DecimalPlaces int32
}
type ProviderBalanceGateway
type ProviderBalanceGateway interface {
LookupProviderBalance(context.Context) (ProviderBalanceResult, error)
}
type ProviderBalanceResult
type ProviderBalanceResult struct {
Available map[string]string
Pending map[string]string
Evidence Evidence
}
type ProviderCode
type ProviderCode string
const (
ProviderCodeTheSolar ProviderCode = "thesolar"
ProviderCodeMockPay ProviderCode = "mockpay"
ProviderCodeDollarPay ProviderCode = "dollarpay"
ProviderCodeXXPay ProviderCode = "xxpay"
ProviderCodeFinix ProviderCode = "finix"
ProviderCodeNowPayments ProviderCode = "nowpayments"
ProviderCodeRocketRamp ProviderCode = "rocketramp"
ProviderCodeManual ProviderCode = "manual"
)
func (ProviderCode) String
func (code ProviderCode) String() string
func (ProviderCode) Valid
func (code ProviderCode) Valid() bool
Valid reports whether code is a member of the provider-code enum.
type ProviderCreateWithdrawalResult
type ProviderCreateWithdrawalResult struct {
// NotSent is a definite pre-dispatch refusal, only with Rejected and no retry.
// It must never be returned after a payout create request has been sent.
NotSent *WithdrawalNotSentRefusal
Outcome WithdrawalOutcome
// RetryAllowed, only with WithdrawalOutcomeRejected, says the provider
// confirmed it did not create or send the payout, so sending the same
// merchant order again cannot pay twice. Payouts are then retried once.
RetryAllowed bool
ProviderTransactionID *ProviderTransactionID
KYCLink *string
ActionURL *string
ActionKind *WithdrawalActionKind
Evidence Evidence
}
type ProviderCustomerRef
type ProviderCustomerRef string
type ProviderPanel
ProviderPanel is a configured payment provider and its operator back-office URL, where an admin verifies a payment by hand. PanelURL is nil when none is configured.
type ProviderPanel struct {
Code ProviderCode
// DisplayName is the vendor's name for admins; empty falls back to Code.
DisplayName string
PanelURL *panelurl.URL
}
type ProviderPaymentMethodRef
type ProviderPaymentMethodRef string
type ProviderPaymentStatus
type ProviderPaymentStatus string
const (
// ProviderPaymentStatusUnknown is an authenticated but unrecognized order
// status. It is neither non-payment nor settlement evidence.
ProviderPaymentStatusExpired ProviderPaymentStatus = "expired"
ProviderPaymentStatusUnknown ProviderPaymentStatus = "unknown"
ProviderPaymentStatusProcessing ProviderPaymentStatus = "processing"
ProviderPaymentStatusSucceeded ProviderPaymentStatus = "succeeded"
ProviderPaymentStatusFailed ProviderPaymentStatus = "failed"
ProviderPaymentStatusRefundIssued ProviderPaymentStatus = "refund_issued"
)
type ProviderPlayerRef
type ProviderPlayerRef string
type ProviderPlayerStatus
type ProviderPlayerStatus string
const (
ProviderPlayerStatusActive ProviderPlayerStatus = "active"
ProviderPlayerStatusPending ProviderPlayerStatus = "pending"
ProviderPlayerStatusKYCRequired ProviderPlayerStatus = "kyc_required"
ProviderPlayerStatusBlocked ProviderPlayerStatus = "blocked"
ProviderPlayerStatusRejected ProviderPlayerStatus = "rejected"
ProviderPlayerStatusInactive ProviderPlayerStatus = "inactive"
ProviderPlayerStatusReviewRequired ProviderPlayerStatus = "review_required"
)
func (ProviderPlayerStatus) String
func (status ProviderPlayerStatus) String() string
type ProviderStatusClassification
ProviderStatusClassification names a canonical interpretation of provider evidence.
type ProviderStatusClassification string
ProviderStatusUnrecognized is the stable classification of an authenticated order status whose meaning has not been established.
const ProviderStatusUnrecognized ProviderStatusClassification = "provider_status_unrecognized"
func (ProviderStatusClassification) String
func (c ProviderStatusClassification) String() string
type ProviderToken
type ProviderToken string
type ProviderTransactionID
type ProviderTransactionID string
func (ProviderTransactionID) String
func (id ProviderTransactionID) String() string
type ProviderWebhookStatus
type ProviderWebhookStatus string
const (
ProviderWebhookStatusPaid ProviderWebhookStatus = "paid"
ProviderWebhookStatusProcessing ProviderWebhookStatus = "processing"
ProviderWebhookStatusSucceeded ProviderWebhookStatus = "succeeded"
ProviderWebhookStatusFailed ProviderWebhookStatus = "failed"
ProviderWebhookStatusRefundIssued ProviderWebhookStatus = "refund_issued"
// ProviderWebhookStatusExpired is an unpaid checkout the provider closed.
// It records the expiry on its order and never moves money.
ProviderWebhookStatusExpired ProviderWebhookStatus = "expired"
)
func (ProviderWebhookStatus) String
func (status ProviderWebhookStatus) String() string
type QuoteWithdrawalRequest
type QuoteWithdrawalRequest struct {
GrossAmount ledger.Cents
PaymentMethodRef PaymentMethodRef
Destination *WithdrawalDestination
}
type QuoteWithdrawalResult
type QuoteWithdrawalResult struct {
EstimatedFee ledger.Cents
EstimatedNet ledger.Cents
Version string
ExchangeRate string
Snapshot json.RawMessage
Evidence Evidence
}
type RedactedPayload
type RedactedPayload string
type RejectWithdrawalCommand
RejectWithdrawalCommand rejects a withdrawal. Category is what the player sees; ReasonCode (from WithdrawalRejectionReasons) and Note stay private.
type RejectWithdrawalCommand struct {
ActorID uuid.UUID
WithdrawalID uuid.UUID
Category WithdrawalRejectionCategory
ReasonCode string
Note string
IdempotencyKey string
}
type RemovePaymentMethodCommand
type RemovePaymentMethodCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
PaymentMethodID uuid.UUID
IdempotencyKey string
}
type RemovePaymentMethodResult
type RemovePaymentMethodResult struct {
PaymentMethod SavedPaymentMethod
Replayed bool
}
type ReversalBlocker
type ReversalBlocker struct {
Code ReversalBlockerCode `json:"code"`
Message string `json:"message"`
RelatedID *uuid.UUID `json:"related_id,omitempty"`
}
type ReversalBlockerCode
type ReversalBlockerCode string
const (
ReversalBlockerNotOffApp ReversalBlockerCode = "not_off_app_deposit"
ReversalBlockerInvalidState ReversalBlockerCode = "invalid_state"
ReversalBlockerPrincipalSpent ReversalBlockerCode = "principal_already_spent"
ReversalBlockerDepositReward ReversalBlockerCode = "deposit_reward_effect"
ReversalBlockerDailyBonus ReversalBlockerCode = "daily_bonus_effect"
ReversalBlockerReferral ReversalBlockerCode = "referral_effect"
ReversalBlockerMission ReversalBlockerCode = "mission_effect"
)
type ReverseOffAppDepositCommand
ReverseOffAppDepositCommand reverses a settled off-app deposit. ReasonCode comes from OffAppReversalReasons; Note is optional except for other.
type ReverseOffAppDepositCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
ExpectedState State
ReasonCode string
Note string
IdempotencyKey string
}
type RevisionPin
RevisionPin identifies the immutable credentials issued to payment work.
type RevisionPin struct {
IntegrationID uuid.UUID
Revision int64
}
type SavedPaymentMethod
type SavedPaymentMethod struct {
ID uuid.UUID
ProviderCode ProviderCode
Kind PaymentMethodKind
Brand string
LastFour string
ExpirationMonth int16
ExpirationYear int32
CardholderName string
State PaymentMethodState
LastUsedAt *time.Time
CreatedAt time.Time
UpdatedAt time.Time
}
type SettleOffAppDepositCommand
type SettleOffAppDepositCommand struct {
ReasonCode string
Note string
ActorID uuid.UUID
PaymentID uuid.UUID
ExpectedState State
ProofAssetID *uuid.UUID
IdempotencyKey string
}
type StaffCashProofError
StaffCashProofError carries one of the plain messages above to the admin.
type StaffCashProofError struct{ Message string }
func (*StaffCashProofError) Error
func (e *StaffCashProofError) Error() string
func (*StaffCashProofError) Unwrap
func (e *StaffCashProofError) Unwrap() error
type State
type State string
const (
StateRequested State = "requested"
StateAwaitingApproval State = "awaiting_approval"
StateDispatchQueued State = "dispatch_queued"
StateActionRequired State = "action_required"
StatePlayerPending State = "player_pending"
StateKYCRequired State = "kyc_required"
StateCheckoutCreated State = "checkout_created"
StateProviderCreated State = "provider_created"
StateSucceeded State = "succeeded"
StateFailed State = "failed"
StateRejected State = "rejected"
StateCanceled State = "canceled"
StateExpired State = "expired"
StateStalePending State = "stale_pending"
StateUnknownRequiresReconcile State = "unknown_requires_reconcile"
StateFailedInternal State = "failed_internal"
StateVoided State = "voided"
StateReversed State = "reversed"
// StateSuperseded closes a provider deposit, never credited, that an
// off-app deposit replaced.
StateSuperseded State = "superseded"
// StateAbandoned closes a stale, never-paid deposit by admin close-out.
StateAbandoned State = "abandoned"
)
func (State) DepositCaseRecordOnly
func (state State) DepositCaseRecordOnly() bool
DepositCaseRecordOnly reports whether a staff decision on a deposit case in this state is record-only (ADR 0055): it closes the case and credits or moves nothing. Only unknown_requires_reconcile and failed_internal settle through the owner's credit and not-received flows.
func (State) String
func (state State) String() string
type StatusLookupGateway
type StatusLookupGateway interface {
LookupPaymentStatus(context.Context, LookupPaymentStatusRequest) (LookupPaymentStatusResult, error)
}
type TokenizationConfig
type TokenizationConfig struct {
Environment TokenizationEnvironment
ApplicationID string
SDKURL string
SDKVersion string
}
type TokenizationEnvironment
type TokenizationEnvironment string
const (
TokenizationEnvironmentSandbox TokenizationEnvironment = "sandbox"
TokenizationEnvironmentProd TokenizationEnvironment = "prod"
)
type UntrustedTestOrderSignal
UntrustedTestOrderSignal is alert evidence only, never settlement evidence.
type UntrustedTestOrderSignal struct {
RunID, ReportedStatus, ReportedAmount string
ReportsMoney bool
}
func TestOrderSignal
func TestOrderSignal(ref MerchantOrderRef, status, amount string, paidStatus bool) *UntrustedTestOrderSignal
type UntrustedWebhookIdentity
UntrustedWebhookIdentity selects a candidate only. It proves no signature, amount, status or ownership; normal verification and settlement still follow.
type UntrustedWebhookIdentity struct {
TestOrder *UntrustedTestOrderSignal
MerchantOrderRef MerchantOrderRef
ProviderTransactionID ProviderTransactionID
}
func (UntrustedWebhookIdentity) Valid
func (i UntrustedWebhookIdentity) Valid() bool
type UpdateDepositPolicyCommand
type UpdateDepositPolicyCommand struct {
// Optional house settings share the routing transaction and one audit.
ManualPolicy *ManualClaimPolicy
Rules []DepositRoutingRule
ExpectedVersion int64
// ReasonCode comes from ProviderPolicyReasons; Note is optional except
// for other.
ReasonCode string
Note string
}
type UpdateOffAppDepositCommand
type UpdateOffAppDepositCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
ExpectedState State
Draft OffAppDepositDraftInput
IdempotencyKey string
}
type UpdatePlayerDepositVisibility
type UpdatePlayerDepositVisibility struct {
ActorID uuid.UUID
UserID uuid.UUID
ExpectedRevision int64
HiddenMethods []string
}
type UserEmail
type UserEmail struct {
// contains filtered or unexported fields
}
func NewUserEmail
func NewUserEmail(email string) (UserEmail, error)
func (UserEmail) String
func (email UserEmail) String() string
type VerifiedWebhook
type VerifiedWebhook struct {
ProviderCode ProviderCode
ProviderTransactionID ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
Status ProviderWebhookStatus
Paid bool
LoadAmount ledger.Cents
AmountPaid ledger.Cents
Username string
Email *string
PaidAt string
Evidence Evidence
}
type VerifiedWithdrawalWebhook
type VerifiedWithdrawalWebhook struct {
ProviderCode ProviderCode
ProviderTransactionID ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
Status ProviderWebhookStatus
Succeeded bool
// RequestedAmount is optional because some providers report only the net fiat payout.
RequestedAmount *ledger.Cents
// SettledAmount is the provider-reported net fiat payout.
SettledAmount ledger.Cents
Username string
Email *string
PaidAt string
Evidence Evidence
}
type VerifyWebhookRequest
type VerifyWebhookRequest struct {
ProviderCode ProviderCode
ContentType string
Headers map[string][]string
RawBody []byte
}
type VoidOffAppDepositCommand
VoidOffAppDepositCommand voids an unsettled draft. ReasonCode comes from OffAppVoidReasons; Note is optional except for other.
type VoidOffAppDepositCommand struct {
ActorID uuid.UUID
PaymentID uuid.UUID
ExpectedState State
ReasonCode string
Note string
IdempotencyKey string
}
type WebhookAck
type WebhookAck struct {
StatusCode int
ContentType string
Body []byte
}
type WebhookMismatchReason
WebhookMismatchReason names why a provider callback contradicted its payment; it is the reason in a webhook_mismatch event's evidence metadata.
type WebhookMismatchReason string
const (
WebhookMismatchLoadAmount WebhookMismatchReason = "load_amount_mismatch"
WebhookMismatchDepositAmount WebhookMismatchReason = "settled_deposit_amount_must_be_whole_dollars_or_end_in_99_cents"
WebhookMismatchAmountPaid WebhookMismatchReason = "amount_paid_mismatch"
WebhookMismatchAmount WebhookMismatchReason = "amount_mismatch"
WebhookMismatchTransactionID WebhookMismatchReason = "transaction_id_mismatch"
WebhookMismatchPaymentMethod WebhookMismatchReason = "payment_method_mismatch"
WebhookMismatchUsername WebhookMismatchReason = "username_mismatch"
WebhookMismatchEmail WebhookMismatchReason = "email_mismatch"
WebhookMismatchInvalidState WebhookMismatchReason = "invalid_state_for_paid_webhook"
// WebhookMismatchClosedWithoutCredit is provider evidence of payment for
// an intent already closed without a credit.
WebhookMismatchClosedWithoutCredit WebhookMismatchReason = "closed_without_credit"
// WebhookMismatchUnpinnedIntent is an unverifiable callback for a payment
// created before its site served the vendor from saved revisions (ADR 0055).
WebhookMismatchUnpinnedIntent WebhookMismatchReason = "unpinned_intent"
)
const WebhookMismatchDollarPayLatePaid WebhookMismatchReason = "dollarpay_late_paid_after_failure"
func (WebhookMismatchReason) String
func (reason WebhookMismatchReason) String() string
type WebhookOutcome
type WebhookOutcome string
const (
WebhookOutcomeRefusedBeforeVerification WebhookOutcome = "refused_before_verification"
WebhookOutcomeInvalidSignature WebhookOutcome = "invalid_signature"
WebhookOutcomeSignedRejected WebhookOutcome = "signed_rejected"
WebhookOutcomeUnmatched WebhookOutcome = "unmatched"
WebhookOutcomeNonPaid WebhookOutcome = "non_paid"
WebhookOutcomeWalletCreditRecovered WebhookOutcome = "wallet_credit_recovered"
WebhookOutcomeMismatch WebhookOutcome = "mismatch"
WebhookOutcomeDuplicate WebhookOutcome = "duplicate"
WebhookOutcomeInvalidState WebhookOutcome = "invalid_state"
WebhookOutcomePaidAccepted WebhookOutcome = "paid_accepted"
WebhookOutcomeCommitFailed WebhookOutcome = "commit_failed"
)
func (WebhookOutcome) String
func (outcome WebhookOutcome) String() string
type WebhookResult
type WebhookResult struct {
Accepted bool
Replay bool
IntentID *uuid.UUID
}
type WithdrawalActionKind
type WithdrawalActionKind string
const (
WithdrawalActionKYC WithdrawalActionKind = "kyc"
WithdrawalActionPayoutSetup WithdrawalActionKind = "payout_setup"
)
func (WithdrawalActionKind) String
func (kind WithdrawalActionKind) String() string
type WithdrawalCatalogOptionsGateway
WithdrawalCatalogOptionsGateway supplies display metadata without live custody/fee lookups. Funding remains a live check against the issued quote. The amount is the player's available cash-out balance, never deposit cash.
type WithdrawalCatalogOptionsGateway interface {
ListWithdrawalCatalogOptions(context.Context, ledger.Cents) (WithdrawalOptions, error)
}
type WithdrawalCatalogRefreshGateway
WithdrawalCatalogRefreshGateway owns startup warming and periodic refresh of display metadata. Start is bounded by the provider timeout and failures are logged without stopping the payment service; ctx owns the refresh lifetime.
type WithdrawalCatalogRefreshGateway interface {
StartWithdrawalCatalogRefresh(context.Context)
}
type WithdrawalCommandResult
type WithdrawalCommandResult struct {
Intent WithdrawalIntent
Replayed bool
}
type WithdrawalControlGateway
type WithdrawalControlGateway interface {
CancelWithdrawal(context.Context, ControlWithdrawalRequest) (ControlWithdrawalResult, error)
ReissueWithdrawalNotification(context.Context, ControlWithdrawalRequest) (ControlWithdrawalResult, error)
}
type WithdrawalDecision
WithdrawalDecision is an admin's approve or reject decision on a withdrawal awaiting approval; each one records its reason code.
type WithdrawalDecision string
const (
WithdrawalDecisionApprove WithdrawalDecision = "approve"
WithdrawalDecisionReject WithdrawalDecision = "reject"
// WithdrawalDecisionConfirmFailed records why a reconciling payout was
// confirmed failed.
WithdrawalDecisionConfirmFailed WithdrawalDecision = "confirm_failed"
)
type WithdrawalDestination
type WithdrawalDestination struct {
ExpectedHousePolicyVersion *int64 `json:"expected_house_policy_version,omitempty"`
ReceiptAttachmentID *uuid.UUID `json:"receipt_attachment_id,omitempty"`
Input string `json:"input,omitempty"`
ManualMethodRef string `json:"manual_method_ref,omitempty"`
ManualKind ManualPaymentInputMethod `json:"manual_kind,omitempty"`
ManualTag string `json:"manual_tag,omitempty"`
PaymentLink string `json:"payment_link,omitempty"`
MethodName string `json:"method_name,omitempty"`
HousePaymentLink string `json:"house_payment_link,omitempty"`
HouseQRPayload string `json:"house_qr_payload,omitempty"`
HousePolicyVersion int64 `json:"house_policy_version,omitempty"`
TipCents ledger.Cents `json:"tip_cents,omitempty"`
TipNote string `json:"tip_note,omitempty"`
Mode HousePayoutMode `json:"mode,omitempty"`
HouseTag string `json:"house_tag,omitempty"`
Kind WithdrawalDestinationKind `json:"kind"`
CashAppTag string `json:"cash_app_tag,omitempty"`
ChimeTag string `json:"chime_tag,omitempty"`
PayPalEmail string `json:"paypal_email,omitempty"`
// ChimeAccount is retained only to decode and dispatch legacy DollarPay intents.
ChimeAccount string `json:"chime_account,omitempty"`
Network string `json:"network,omitempty"`
Address string `json:"address,omitempty"`
Memo string `json:"memo,omitempty"`
}
type WithdrawalDestinationKind
type WithdrawalDestinationKind string
const (
WithdrawalDestinationManual WithdrawalDestinationKind = "manual"
WithdrawalDestinationCashApp WithdrawalDestinationKind = "cash_app"
WithdrawalDestinationChime WithdrawalDestinationKind = "chime"
WithdrawalDestinationPayPal WithdrawalDestinationKind = "paypal"
WithdrawalDestinationCrypto WithdrawalDestinationKind = "crypto"
WithdrawalDestinationProviderManaged WithdrawalDestinationKind = "provider_managed"
)
type WithdrawalEventSource
type WithdrawalEventSource string
const (
WithdrawalEventSourcePlayer WithdrawalEventSource = "player"
WithdrawalEventSourceAdmin WithdrawalEventSource = "admin"
WithdrawalEventSourceProvider WithdrawalEventSource = "provider"
WithdrawalEventSourceSystem WithdrawalEventSource = "system"
WithdrawalEventSourceReconciler WithdrawalEventSource = "reconciler"
)
func (WithdrawalEventSource) String
func (source WithdrawalEventSource) String() string
type WithdrawalFundingGateway
WithdrawalFundingGateway checks custody against an already validated quote. The snapshot remains opaque to the payment service.
type WithdrawalFundingGateway interface {
CanFundWithdrawal(context.Context, PaymentMethodRef, json.RawMessage) (bool, error)
}
type WithdrawalGateway
type WithdrawalGateway interface {
CreateWithdrawal(context.Context, CreateWithdrawalRequest) (ProviderCreateWithdrawalResult, error)
VerifyWithdrawalWebhook(context.Context, VerifyWebhookRequest) (VerifiedWithdrawalWebhook, WebhookAck, error)
}
type WithdrawalIntent
type WithdrawalIntent struct {
PaymentInProgress bool
ID uuid.UUID
UserID uuid.UUID
ProviderCode ProviderCode
State State
Amount ledger.Cents
Currency ledger.CurrencyCode
AmountOptionRef AmountOptionRef
PaymentMethodRef PaymentMethodRef
Destination *WithdrawalDestination
ProviderPlayerRef *ProviderPlayerRef
ProviderTransactionID *ProviderTransactionID
MerchantOrderRef *MerchantOrderRef
KYCLink *string
ActionURL *string
ActionKind *WithdrawalActionKind
WalletDebitTxnID *uuid.UUID
ReleaseTxnID *uuid.UUID
SettlementTxnID *uuid.UUID
EstimatedFee ledger.Cents
EstimatedNet ledger.Cents
ActualFee *ledger.Cents
ActualNet *ledger.Cents
ApprovalExpiresAt *time.Time
ActionRequiredExpires *time.Time
RejectionCategory *string
CreatedAt time.Time
UpdatedAt time.Time
}
type WithdrawalMinimumGateway
type WithdrawalMinimumGateway interface {
WithdrawalMinimum(context.Context, PaymentMethodRef) (WithdrawalMinimumResult, error)
}
type WithdrawalMinimumResult
type WithdrawalMinimumResult struct {
MinimumAmount ledger.Cents
CachedUntil time.Time
}
type WithdrawalNotSentReason
WithdrawalNotSentReason describes validation before any payout create call. It says nothing about an earlier dispatch; the dispatcher must guard those.
type WithdrawalNotSentReason string
const (
WithdrawalMinimumUnavailable WithdrawalNotSentReason = "minimum_unavailable"
WithdrawalMinimumIncreased WithdrawalNotSentReason = "minimum_increased"
)
type WithdrawalNotSentRefusal
WithdrawalNotSentRefusal is a definite not-sent outcome, not transport uncertainty. Its fields are validated domain data, never raw provider copy. Quote refusals also use it as an error while retaining the existing error classifications for HTTP callers through Unwrap.
type WithdrawalNotSentRefusal struct {
Reason WithdrawalNotSentReason
Coin string
MinimumAmount ledger.Cents
}
func (*WithdrawalNotSentRefusal) Error
func (r *WithdrawalNotSentRefusal) Error() string
func (*WithdrawalNotSentRefusal) PlayerMessage
func (r *WithdrawalNotSentRefusal) PlayerMessage() string
func (*WithdrawalNotSentRefusal) Unwrap
func (r *WithdrawalNotSentRefusal) Unwrap() error
func (*WithdrawalNotSentRefusal) Valid
func (r *WithdrawalNotSentRefusal) Valid() bool
type WithdrawalOperatorStatus
WithdrawalOperatorStatus is the operator workflow status of a withdrawal. It is derived from the stored lifecycle facts in Postgres; clients never infer it themselves.
type WithdrawalOperatorStatus string
const (
WithdrawalOperatorStatusNew WithdrawalOperatorStatus = "new"
WithdrawalOperatorStatusWaitingForApproval WithdrawalOperatorStatus = "waiting_for_approval"
WithdrawalOperatorStatusApprovedSendPayment WithdrawalOperatorStatus = "approved_send_payment"
WithdrawalOperatorStatusProcessingAutomatically WithdrawalOperatorStatus = "processing_automatically"
WithdrawalOperatorStatusNeedsAttention WithdrawalOperatorStatus = "needs_attention"
WithdrawalOperatorStatusPaid WithdrawalOperatorStatus = "paid"
WithdrawalOperatorStatusClosed WithdrawalOperatorStatus = "closed"
)
func ParseWithdrawalOperatorStatus
func ParseWithdrawalOperatorStatus(value string) (WithdrawalOperatorStatus, bool)
ParseWithdrawalOperatorStatus accepts only a known status.
func WithdrawalOperatorStatuses
func WithdrawalOperatorStatuses() []WithdrawalOperatorStatus
WithdrawalOperatorStatuses lists every operator status. The rule that derives a status is the Postgres function playgo_withdrawal_operator_status (migration 000123), which the payout board, the admin withdrawal views and the Inbox situation feed all read; Go only parses its result.
func (WithdrawalOperatorStatus) Label
func (s WithdrawalOperatorStatus) Label() string
Label is the operator-facing wording of the status.
type WithdrawalOptions
type WithdrawalOptions struct {
ProviderCode ProviderCode
AccountSetupState AccountSetupState
Amounts []AmountOption
PaymentMethods []PaymentMethodOption
MinimumAmount ledger.Cents
MaximumAmount *ledger.Cents
DestinationRequired bool
DestinationLabel string
CachedUntil time.Time
}
type WithdrawalOptionsCatalog
type WithdrawalOptionsCatalog struct {
MethodDisplayOrder []string
Providers []WithdrawalOptions
}
type WithdrawalOptionsGateway
type WithdrawalOptionsGateway interface {
ListWithdrawalOptions(context.Context) (WithdrawalOptions, error)
}
type WithdrawalOutcome
type WithdrawalOutcome string
const (
WithdrawalOutcomeCreated WithdrawalOutcome = "created"
WithdrawalOutcomePlayerPending WithdrawalOutcome = "player_pending"
WithdrawalOutcomeKYCRequired WithdrawalOutcome = "kyc_required"
WithdrawalOutcomeRejected WithdrawalOutcome = "rejected"
WithdrawalOutcomeUnknown WithdrawalOutcome = "unknown"
WithdrawalOutcomeProviderError WithdrawalOutcome = "provider_error"
)
type WithdrawalPayingClaimCommand
type WithdrawalPayingClaimCommand struct {
WithdrawalID uuid.UUID
ActorID uuid.UUID
ClaimID uuid.UUID
ReviewEvidence string
}
type WithdrawalPayingStatus
type WithdrawalPayingStatus struct {
State State
ClaimID *uuid.UUID
Held bool
Owned bool
NeedsReview bool
SendValidForMs *int64
PayingBy *uuid.UUID
PayingAt *time.Time
}
type WithdrawalProofAsset
type WithdrawalProofAsset struct {
ID uuid.UUID
WithdrawalID uuid.UUID
UploaderID uuid.UUID
State WithdrawalProofAssetState
OriginalFilename string
DeclaredMIME string
DetectedMIME *string
DeclaredSize int64
ActualSize *int64
ChecksumSHA256 string
ETag *string
VersionID *string
UploadExpiresAt time.Time
FinalizedAt *time.Time
CreatedAt time.Time
}
type WithdrawalProofAssetState
type WithdrawalProofAssetState string
const (
WithdrawalProofAssetPending WithdrawalProofAssetState = "pending"
WithdrawalProofAssetFinalized WithdrawalProofAssetState = "finalized"
)
type WithdrawalProofPreview
type WithdrawalProofPreview struct {
URL string
ExpiresAt time.Time
}
type WithdrawalProviderGateway
WithdrawalProviderGateway is the complete payout boundary used by the withdrawal service. It allows payout-only implementations without exposing deposit checkout methods.
type WithdrawalProviderGateway interface {
WithdrawalOptionsGateway
WithdrawalGateway
EnsurePlayer(context.Context, EnsurePlayerRequest) (EnsurePlayerResult, error)
}
type WithdrawalQuoteReason
WithdrawalQuoteReason is a safe classification, never provider error text.
type WithdrawalQuoteReason string
const (
QuoteUnauthorized WithdrawalQuoteReason = "unauthorized"
QuoteInvalidRequest WithdrawalQuoteReason = "invalid_request"
QuoteAmountBelowMinimum WithdrawalQuoteReason = "amount_below_minimum"
QuoteAmountAboveMaximum WithdrawalQuoteReason = "amount_above_maximum"
QuoteAmountDoesNotCoverFee WithdrawalQuoteReason = "amount_does_not_cover_fee"
QuoteInvalidDestination WithdrawalQuoteReason = "invalid_destination"
QuoteNetworkMismatch WithdrawalQuoteReason = "network_mismatch"
QuoteMethodUnavailable WithdrawalQuoteReason = "method_unavailable"
QuoteProviderUnavailable WithdrawalQuoteReason = "provider_unavailable"
)
func (WithdrawalQuoteReason) Valid
func (r WithdrawalQuoteReason) Valid() bool
type WithdrawalQuoteRefusal
WithdrawalQuoteRefusal retains errors.Is behavior without exposing its cause through Error, logs or span exception messages. Method is a destination family, not an unvalidated client reference that could contain an address or email.
type WithdrawalQuoteRefusal struct {
Reason WithdrawalQuoteReason
Method WithdrawalDestinationKind
// contains filtered or unexported fields
}
func (*WithdrawalQuoteRefusal) Error
func (r *WithdrawalQuoteRefusal) Error() string
func (*WithdrawalQuoteRefusal) Unwrap
func (r *WithdrawalQuoteRefusal) Unwrap() error
type WithdrawalRejectionCategory
type WithdrawalRejectionCategory string
const (
WithdrawalRejectionVerificationFailed WithdrawalRejectionCategory = "verification_failed"
WithdrawalRejectionDestinationIssue WithdrawalRejectionCategory = "destination_issue"
WithdrawalRejectionPolicyRestriction WithdrawalRejectionCategory = "policy_restriction"
WithdrawalRejectionProviderUnavailable WithdrawalRejectionCategory = "provider_unavailable"
WithdrawalRejectionOther WithdrawalRejectionCategory = "other"
)
func (WithdrawalRejectionCategory) String
func (category WithdrawalRejectionCategory) String() string
type WithdrawalStatusLookupGateway
type WithdrawalStatusLookupGateway interface {
LookupWithdrawalStatus(context.Context, LookupWithdrawalStatusRequest) (LookupWithdrawalStatusResult, error)
}
type WithdrawalWebhookResult
type WithdrawalWebhookResult struct {
Accepted bool
Replay bool
IntentID *uuid.UUID
}
Generated by gomarkdoc