Laniakea/tgapi/payments_methods.go

package tgapi

import "context"

// SendInvoice holds parameters for the sendInvoice method.
// Since: Bot API 3.0
// See https://core.telegram.org/bots/api#sendinvoice
type SendInvoice struct {
	// ChatID Required. Unique identifier for the target chat or username of the target bot, supergroup or
	// channel in the format @username
	ChatID int64 `json:"chat_id"`
	// MessageThreadID Optional. Unique identifier for the target message thread (topic) of a forum; for forum
	// supergroups and private chats of bots with forum topic mode enabled only
	MessageThreadID int `json:"message_thread_id,omitempty"`
	// DirectMessagesTopicID Optional. Identifier of the direct messages topic to which the message will be
	// sent; required if the message is sent to a direct messages chat
	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`

	// Title Required. Product name, 1-32 characters
	Title string `json:"title"`
	// Description Required. Product description, 1-255 characters
	Description string `json:"description"`
	// Payload Required. Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use
	// it for your internal processes.
	Payload string `json:"payload"`
	// ProviderToken Optional. Payment provider token, obtained via @BotFather. Pass an empty string for
	// payments in Telegram Stars.
	ProviderToken string `json:"provider_token,omitempty"`
	// Currency Required. Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for
	// payments in Telegram Stars.
	Currency string `json:"currency"`
	// Prices Required. Price breakdown, a JSON-serialized list of components (e.g. product price, tax,
	// discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in
	// Telegram Stars.
	Prices []LabeledPrice `json:"prices"`

	// MaxTipAmount Optional. The maximum accepted amount for tips in the smallest units of the currency
	// (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See
	// the exp parameter in currencies.json, it shows the number of digits past the decimal point for each
	// currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars.
	MaxTipAmount int `json:"max_tip_amount,omitempty"`
	// SuggestedTipAmounts Optional. A JSON-serialized Array of suggested amounts of tips in the smallest units
	// of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The
	// suggested tip amounts must be positive, passed in a strictly increased order and must not exceed
	// max_tip_amount.
	SuggestedTipAmounts []int `json:"suggested_tip_amounts,omitempty"`
	// StartParameter Optional. Unique deep-linking parameter. If left empty, forwarded copies of the sent
	// message will have a Pay button, allowing multiple users to pay directly from the forwarded message, using
	// the same invoice. If non-empty, forwarded copies of the sent message will have a URL button with a deep
	// link to the bot (instead of a Pay button), with the value used as the start parameter.
	StartParameter string `json:"start_parameter,omitempty"`
	// ProviderData Optional. JSON-serialized data about the invoice, which will be shared with the payment
	// provider. A detailed description of required fields should be provided by the payment provider.
	ProviderData string `json:"provider_data,omitempty"`
	// PhotoURL Optional. URL of the product photo for the invoice. Can be a photo of the goods or a marketing
	// image for a service. People like it better when they see what they are paying for.
	PhotoURL string `json:"photo_url,omitempty"`
	// PhotoSize Optional. Photo size in bytes
	PhotoSize int `json:"photo_size,omitempty"`
	// PhotoWidth Optional. Photo width
	PhotoWidth int `json:"photo_width,omitempty"`
	// PhotoHeight Optional. Photo height
	PhotoHeight int `json:"photo_height,omitempty"`
	// NeedName Optional. Pass True if you require the user's full name to complete the order. Ignored for
	// payments in Telegram Stars.
	NeedName bool `json:"need_name,omitempty"`
	// NeedPhoneNumber Optional. Pass True if you require the user's phone number to complete the order. Ignored
	// for payments in Telegram Stars.
	NeedPhoneNumber bool `json:"need_phone_number,omitempty"`
	// NeedEmail Optional. Pass True if you require the user's email address to complete the order. Ignored for
	// payments in Telegram Stars.
	NeedEmail bool `json:"need_email,omitempty"`
	// NeedShippingAddress Optional. Pass True if you require the user's shipping address to complete the order.
	// Ignored for payments in Telegram Stars.
	NeedShippingAddress bool `json:"need_shipping_address,omitempty"`
	// SendPhoneToProvider Optional. Pass True if the user's phone number should be sent to the provider.
	// Ignored for payments in Telegram Stars.
	SendPhoneToProvider bool `json:"send_phone_number_to_provider,omitempty"`
	// SendEmailToProvider Optional. Pass True if the user's email address should be sent to the provider.
	// Ignored for payments in Telegram Stars.
	SendEmailToProvider bool `json:"send_email_to_provider,omitempty"`
	// IsFlexible Optional. Pass True if the final price depends on the shipping method. Ignored for payments in
	// Telegram Stars.
	IsFlexible bool `json:"is_flexible,omitempty"`
	// DisableNotification Optional. Sends the message silently. Users will receive a notification with no
	// sound.
	DisableNotification bool `json:"disable_notification,omitempty"`
	// ProtectContent Optional. Protects the contents of the sent message from forwarding and saving
	ProtectContent bool `json:"protect_content,omitempty"`
	// AllowPaidBroadcast Optional. Pass True to allow up to 1000 messages per second, ignoring broadcasting
	// limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's
	// balance.
	AllowPaidBroadcast bool `json:"allow_paid_broadcast,omitempty"`
	// MessageEffectID Optional. Unique identifier of the message effect to be added to the message; for private
	// chats only
	MessageEffectID string `json:"message_effect_id,omitempty"`

	// SuggestedPostParameters Optional. A JSON-serialized object containing the parameters of the suggested
	// post to send; for direct messages chats only. If the message is sent as a reply to another suggested
	// post, then that suggested post is automatically declined.
	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
	// ReplyParameters Optional. Description of the message to reply to
	ReplyParameters *ReplyParameters `json:"reply_parameters,omitempty"`
	// ReplyMarkup Optional. A JSON-serialized object for an inline keyboard. If empty, one 'Pay total price'
	// button will be shown. If not empty, the first button must be a Pay button.
	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
}

// SendInvoice sends an invoice.
// Since: Bot API 3.0
// See https://core.telegram.org/bots/api#sendinvoice
func (api *API) SendInvoice(params SendInvoice) (Message, error) {
	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
	return req.Do(api)
}

// SendInvoiceWithContext is the context-aware variant of SendInvoice.
// Since: Bot API 3.0
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#sendinvoice
func (api *API) SendInvoiceWithContext(ctx context.Context, params SendInvoice) (Message, error) {
	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
	return req.DoWithContext(ctx, api)
}

// CreateInvoiceLink holds parameters for the createInvoiceLink method.
// Since: Bot API 6.1
// See https://core.telegram.org/bots/api#createinvoicelink
type CreateInvoiceLink struct {
	// BusinessConnectionID Optional. Unique identifier of the business connection on behalf of which the link
	// will be created. For payments in Telegram Stars only.
	BusinessConnectionID string `json:"business_connection_id,omitempty"`

	// Title Required. Product name, 1-32 characters
	Title string `json:"title"`
	// Description Required. Product description, 1-255 characters
	Description string `json:"description"`
	// Payload Required. Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use
	// it for your internal processes.
	Payload string `json:"payload"`
	// ProviderToken Optional. Payment provider token, obtained via @BotFather. Pass an empty string for
	// payments in Telegram Stars.
	ProviderToken string `json:"provider_token,omitempty"`
	// Currency Required. Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for
	// payments in Telegram Stars.
	Currency string `json:"currency"`
	// Prices Required. Price breakdown, a JSON-serialized list of components (e.g. product price, tax,
	// discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in
	// Telegram Stars.
	Prices []LabeledPrice `json:"prices"`

	// SubscriptionPeriod Optional. The number of seconds the subscription will be active for before the next
	// payment. The currency must be set to “XTR” (Telegram Stars) if the parameter is used. Currently, it
	// must always be 2592000 (30 days) if specified. Any number of subscriptions can be active for a given bot
	// at the same time, including multiple concurrent subscriptions from the same user. Subscription price must
	// no exceed 10000 Telegram Stars.
	SubscriptionPeriod int `json:"subscription_period,omitempty"`
	// MaxTipAmount Optional. The maximum accepted amount for tips in the smallest units of the currency
	// (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See
	// the exp parameter in currencies.json, it shows the number of digits past the decimal point for each
	// currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars.
	MaxTipAmount int `json:"max_tip_amount,omitempty"`
	// SuggestedTipAmounts Optional. A JSON-serialized Array of suggested amounts of tips in the smallest units
	// of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The
	// suggested tip amounts must be positive, passed in a strictly increased order and must not exceed
	// max_tip_amount.
	SuggestedTipAmounts []int `json:"suggested_tip_amounts,omitempty"`
	// ProviderData Optional. JSON-serialized data about the invoice, which will be shared with the payment
	// provider. A detailed description of required fields should be provided by the payment provider.
	ProviderData string `json:"provider_data,omitempty"`
	// PhotoURL Optional. URL of the product photo for the invoice. Can be a photo of the goods or a marketing
	// image for a service.
	PhotoURL string `json:"photo_url,omitempty"`
	// PhotoSize Optional. Photo size in bytes
	PhotoSize int `json:"photo_size,omitempty"`
	// PhotoWidth Optional. Photo width
	PhotoWidth int `json:"photo_width,omitempty"`
	// PhotoHeight Optional. Photo height
	PhotoHeight int `json:"photo_height,omitempty"`
	// NeedName Optional. Pass True if you require the user's full name to complete the order. Ignored for
	// payments in Telegram Stars.
	NeedName bool `json:"need_name,omitempty"`
	// NeedPhoneNumber Optional. Pass True if you require the user's phone number to complete the order. Ignored
	// for payments in Telegram Stars.
	NeedPhoneNumber bool `json:"need_phone_number,omitempty"`
	// NeedEmail Optional. Pass True if you require the user's email address to complete the order. Ignored for
	// payments in Telegram Stars.
	NeedEmail bool `json:"need_email,omitempty"`
	// NeedShippingAddress Optional. Pass True if you require the user's shipping address to complete the order.
	// Ignored for payments in Telegram Stars.
	NeedShippingAddress bool `json:"need_shipping_address,omitempty"`
	// SendPhoneToProvider Optional. Pass True if the user's phone number should be sent to the provider.
	// Ignored for payments in Telegram Stars.
	SendPhoneToProvider bool `json:"send_phone_number_to_provider,omitempty"`
	// SendEmailToProvider Optional. Pass True if the user's email address should be sent to the provider.
	// Ignored for payments in Telegram Stars.
	SendEmailToProvider bool `json:"send_email_to_provider,omitempty"`
	// IsFlexible Optional. Pass True if the final price depends on the shipping method. Ignored for payments in
	// Telegram Stars.
	IsFlexible bool `json:"is_flexible,omitempty"`
}

// CreateInvoiceLink creates an invoice link.
// Since: Bot API 6.1
// See https://core.telegram.org/bots/api#createinvoicelink
func (api *API) CreateInvoiceLink(params CreateInvoiceLink) (string, error) {
	req := NewRequest[string]("createInvoiceLink", params)
	return req.Do(api)
}

// CreateInvoiceLinkWithContext is the context-aware variant of CreateInvoiceLink.
// Since: Bot API 6.1
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#createinvoicelink
func (api *API) CreateInvoiceLinkWithContext(ctx context.Context, params CreateInvoiceLink) (string, error) {
	req := NewRequest[string]("createInvoiceLink", params)
	return req.DoWithContext(ctx, api)
}

// AnswerShippingQuery holds parameters for the answerShippingQuery method.
// Since: Bot API 3.0
// See https://core.telegram.org/bots/api#answershippingquery
type AnswerShippingQuery struct {
	// ShippingQueryID Required. Unique identifier for the query to be answered
	ShippingQueryID string `json:"shipping_query_id"`
	// OK Required. Pass True if delivery to the specified address is possible and False if there are any
	// problems (for example, if delivery to the specified address is not possible)
	OK bool `json:"ok"`
	// ShippingOptions Optional. Required if ok is True. A JSON-serialized Array of available shipping options.
	ShippingOptions []ShippingOption `json:"shipping_options,omitempty"`
	// ErrorMessage Optional. Required if ok is False. Error message in human readable form that explains why it
	// is impossible to complete the order (e.g. “Sorry, delivery to your desired address is unavailable”).
	// Telegram will display this message to the user.
	ErrorMessage string `json:"error_message,omitempty"`
}

// AnswerShippingQuery answers a shipping query.
// Since: Bot API 3.0
// Returns true on success.
// See https://core.telegram.org/bots/api#answershippingquery
func (api *API) AnswerShippingQuery(params AnswerShippingQuery) (bool, error) {
	req := NewRequest[bool]("answerShippingQuery", params)
	return req.Do(api)
}

// AnswerShippingQueryWithContext is the context-aware variant of AnswerShippingQuery.
// Since: Bot API 3.0
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#answershippingquery
func (api *API) AnswerShippingQueryWithContext(ctx context.Context, params AnswerShippingQuery) (bool, error) {
	req := NewRequest[bool]("answerShippingQuery", params)
	return req.DoWithContext(ctx, api)
}

// AnswerPreCheckoutQuery holds parameters for the answerPreCheckoutQuery method.
// Since: Bot API 3.0
// See https://core.telegram.org/bots/api#answerprecheckoutquery
type AnswerPreCheckoutQuery struct {
	// PreCheckoutQueryID Required. Unique identifier for the query to be answered
	PreCheckoutQueryID string `json:"pre_checkout_query_id"`
	// OK Required. Specify True if everything is alright (goods are available, etc.) and the bot is ready to
	// proceed with the order. Use False if there are any problems.
	OK bool `json:"ok"`
	// ErrorMessage Optional. Required if ok is False. Error message in human readable form that explains the
	// reason for failure to proceed with the checkout (e.g. "Sorry, somebody just bought the last of our
	// amazing black T-shirts while you were busy filling out your payment details. Please choose a different
	// color or garment!"). Telegram will display this message to the user.
	ErrorMessage string `json:"error_message,omitempty"`
}

// AnswerPreCheckoutQuery answers a pre-checkout query.
// Since: Bot API 3.0
// Returns true on success.
// See https://core.telegram.org/bots/api#answerprecheckoutquery
func (api *API) AnswerPreCheckoutQuery(params AnswerPreCheckoutQuery) (bool, error) {
	req := NewRequest[bool]("answerPreCheckoutQuery", params)
	return req.Do(api)
}

// AnswerPreCheckoutQueryWithContext is the context-aware variant of AnswerPreCheckoutQuery.
// Since: Bot API 3.0
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#answerprecheckoutquery
func (api *API) AnswerPreCheckoutQueryWithContext(ctx context.Context, params AnswerPreCheckoutQuery) (bool, error) {
	req := NewRequest[bool]("answerPreCheckoutQuery", params)
	return req.DoWithContext(ctx, api)
}