scrabble-game/backend/internal/yookassa/receipt.go

package yookassa

// Fiscal receipt attributes for «Чеки от ЮKassa» (54-ФЗ). YooKassa registers the receipt itself —
// no cash register to rent, no OFD contract — but only if the payment and refund requests carry a
// receipt object, so unlike the previous rail's cabinet-side receipts these fields are load-bearing
// code. Reference:
// https://yookassa.ru/developers/payment-acceptance/receipts/54fz/yoomoney/parameters-values
const (
	// PaymentSubjectService is the settlement subject (54-ФЗ tag 1212) — what the money is taken
	// for. Chips are sold as a service ("Услуга").
	PaymentSubjectService = "service"
	// PaymentModeFullPayment is the settlement method (54-ФЗ tag 1214) — the payer pays and receives
	// the goods at once ("Полный расчет"). «Чеки от ЮKassa» accept only this and full_prepayment;
	// partial prepayment, advance and credit are not supported.
	PaymentModeFullPayment = "full_payment"

	// VatCodeNone is the VAT rate code (54-ФЗ tag 1199) for «Без НДС» — the rate a sole proprietor on
	// УСН or ПСН charges. It is the default; the deployed value is configurable because the rate is
	// the one receipt attribute that genuinely changes (Russia raised the main rate on 1 Jan 2026,
	// adding codes 11 and 12).
	VatCodeNone = 1
	// VatCodeMax is the highest VAT rate code the API accepts; codes run 1..12.
	VatCodeMax = 12
)

// Customer is the payer's contact data for delivering the receipt. «Чеки от ЮKassa» deliver only by
// email (no SMS), so Email is required — the direct rail's confirmed email anchor supplies it.
type Customer struct {
	Email string `json:"email,omitempty"`
}

// ReceiptItem is one line of a fiscal receipt: what was sold, how much of it, for how much, and the
// three fiscal attributes that classify it.
type ReceiptItem struct {
	Description    string  `json:"description"`
	Quantity       float64 `json:"quantity"`
	Amount         Amount  `json:"amount"`
	VatCode        int     `json:"vat_code"`
	PaymentSubject string  `json:"payment_subject"`
	PaymentMode    string  `json:"payment_mode"`
}

// Receipt is the fiscal receipt data sent alongside a payment or a refund. tax_system_code is
// deliberately absent: YooKassa ignores it for «Чеки от ЮKassa».
type Receipt struct {
	Customer Customer      `json:"customer"`
	Items    []ReceiptItem `json:"items"`
}

// maxDescriptionRunes is the API's limit for both a payment description and a receipt line
// description (54-ФЗ tag 1030). A longer title is truncated rather than rejected, so an over-long
// product name cannot block a purchase.
const maxDescriptionRunes = 128

// SingleItemReceipt builds a one-line receipt for selling title at amount to email. Chip packs are
// always a single line bought once, so quantity is 1 and the line amount is the whole payment.
func SingleItemReceipt(email, title string, amount Amount, vatCode int) *Receipt {
	return &Receipt{
		Customer: Customer{Email: email},
		Items: []ReceiptItem{{
			Description:    TruncateDescription(title),
			Quantity:       1,
			Amount:         amount,
			VatCode:        vatCode,
			PaymentSubject: PaymentSubjectService,
			PaymentMode:    PaymentModeFullPayment,
		}},
	}
}

// TruncateDescription shortens s to the API's description limit, counting runes rather than bytes so
// a Cyrillic title is not cut mid-character.
func TruncateDescription(s string) string {
	r := []rune(s)
	if len(r) <= maxDescriptionRunes {
		return s
	}
	return string(r[:maxDescriptionRunes])
}

// ValidVatCode reports whether code is within the range the API accepts (1..12).
func ValidVatCode(code int) bool { return code >= 1 && code <= VatCodeMax }