### Payments

Your bot can accept payments from Telegram users. Please see the introduction to payments for more details on the process and how to set up payments for your bot.

#### sendInvoice

Use this method to send invoices. On success, the sent Message is returned.

Parameter | Type | Required | Description
--- | --- | --- | ---
chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
message_thread_id | Integer | 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
direct_messages_topic_id | Integer | 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
title | String | Yes | Product name, 1-32 characters
description | String | Yes | Product description, 1-255 characters
payload | String | Yes | Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use it for your internal processes.
provider_token | String | Optional | Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars.
currency | String | Yes | Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for payments in Telegram Stars.
prices | Array of LabeledPrice | Yes | 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.
max_tip_amount | Integer | 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.
suggested_tip_amounts | Array of Integer | 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.
start_parameter | String | 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
provider_data | String | 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.
photo_url | String | 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.
photo_size | Integer | Optional | Photo size in bytes
photo_width | Integer | Optional | Photo width
photo_height | Integer | Optional | Photo height
need_name | Boolean | Optional | Pass True if you require the user's full name to complete the order. Ignored for payments in Telegram Stars.
need_phone_number | Boolean | Optional | Pass True if you require the user's phone number to complete the order. Ignored for payments in Telegram Stars.
need_email | Boolean | Optional | Pass True if you require the user's email address to complete the order. Ignored for payments in Telegram Stars.
need_shipping_address | Boolean | Optional | Pass True if you require the user's shipping address to complete the order. Ignored for payments in Telegram Stars.
send_phone_number_to_provider | Boolean | Optional | Pass True if the user's phone number should be sent to the provider. Ignored for payments in Telegram Stars.
send_email_to_provider | Boolean | Optional | Pass True if the user's email address should be sent to the provider. Ignored for payments in Telegram Stars.
is_flexible | Boolean | Optional | Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars.
disable_notification | Boolean | Optional | Sends the message silently. Users will receive a notification with no sound.
protect_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving
allow_paid_broadcast | Boolean | 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
message_effect_id | String | Optional | Unique identifier of the message effect to be added to the message; for private chats only
suggested_post_parameters | 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.
reply_parameters | ReplyParameters | Optional | Description of the message to reply to
reply_markup | InlineKeyboardMarkup | 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.

#### createInvoiceLink

Use this method to create a link for an invoice. Returns the created invoice link as String on success.

Parameter | Type | Required | Description
--- | --- | --- | ---
business_connection_id | String | Optional | Unique identifier of the business connection on behalf of which the link will be created. For payments in Telegram Stars only.
title | String | Yes | Product name, 1-32 characters
description | String | Yes | Product description, 1-255 characters
payload | String | Yes | Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use it for your internal processes.
provider_token | String | Optional | Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars.
currency | String | Yes | Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for payments in Telegram Stars.
prices | Array of LabeledPrice | Yes | 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.
subscription_period | Integer | 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.
max_tip_amount | Integer | 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.
suggested_tip_amounts | Array of Integer | 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.
provider_data | String | 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.
photo_url | String | Optional | URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service.
photo_size | Integer | Optional | Photo size in bytes
photo_width | Integer | Optional | Photo width
photo_height | Integer | Optional | Photo height
need_name | Boolean | Optional | Pass True if you require the user's full name to complete the order. Ignored for payments in Telegram Stars.
need_phone_number | Boolean | Optional | Pass True if you require the user's phone number to complete the order. Ignored for payments in Telegram Stars.
need_email | Boolean | Optional | Pass True if you require the user's email address to complete the order. Ignored for payments in Telegram Stars.
need_shipping_address | Boolean | Optional | Pass True if you require the user's shipping address to complete the order. Ignored for payments in Telegram Stars.
send_phone_number_to_provider | Boolean | Optional | Pass True if the user's phone number should be sent to the provider. Ignored for payments in Telegram Stars.
send_email_to_provider | Boolean | Optional | Pass True if the user's email address should be sent to the provider. Ignored for payments in Telegram Stars.
is_flexible | Boolean | Optional | Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars.

#### answerShippingQuery

If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot API will send an Update with a shipping_query field to the bot. Use this method to reply to shipping queries. On success, True is returned.

Parameter | Type | Required | Description
--- | --- | --- | ---
shipping_query_id | String | Yes | Unique identifier for the query to be answered
ok | Boolean | Yes | 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)
shipping_options | Array of ShippingOption | Optional | Required if ok is True. A JSON-serialized array of available shipping options.
error_message | String | 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.

#### answerPreCheckoutQuery

Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout queries. On success, True is returned. Note: The Bot API must receive an answer within 10 seconds after the pre-checkout query was sent.

Parameter | Type | Required | Description
--- | --- | --- | ---
pre_checkout_query_id | String | Yes | Unique identifier for the query to be answered
ok | Boolean | Yes | 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.
error_message | String | 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.

#### getMyStarBalance

A method to get the current Telegram Stars balance of the bot. Requires no parameters. On success, returns a StarAmount object.

#### getStarTransactions

Returns the bot's Telegram Star transactions in chronological order. On success, returns a StarTransactions object.

Parameter | Type | Required | Description
--- | --- | --- | ---
offset | Integer | Optional | Number of transactions to skip in the response
limit | Integer | Optional | The maximum number of transactions to be retrieved. Values between 1-100 are accepted. Defaults to 100.

#### refundStarPayment

Refunds a successful payment in Telegram Stars. Returns True on success.

Parameter | Type | Required | Description
--- | --- | --- | ---
user_id | Integer | Yes | Identifier of the user whose payment will be refunded
telegram_payment_charge_id | String | Yes | Telegram payment identifier

#### editUserStarSubscription

Allows the bot to cancel or re-enable extension of a subscription paid in Telegram Stars. Returns True on success.

Parameter | Type | Required | Description
--- | --- | --- | ---
user_id | Integer | Yes | Identifier of the user whose subscription will be edited
telegram_payment_charge_id | String | Yes | Telegram payment identifier for the subscription
is_canceled | Boolean | Yes | Pass True to cancel extension of the user subscription; the subscription must be active up to the end of the current subscription period. Pass False to allow the user to re-enable a subscription that was previously canceled by the bot.

#### LabeledPrice

This object represents a portion of the price for goods or services.

Field | Type | Description
--- | --- | ---
label | String | Portion label
amount | Integer | Price of the product in the smallest units of the currency (integer, not float/double). For example, for a price of `US$ 1.45` pass `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).

#### Invoice

This object contains basic information about an invoice.

Field | Type | Description
--- | --- | ---
title | String | Product name
description | String | Product description
start_parameter | String | Unique bot deep-linking parameter that can be used to generate this invoice
currency | String | Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars
total_amount | Integer | Total price in the smallest units of the currency (integer, not float/double). For example, for a price of `US$ 1.45` pass `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).

#### ShippingAddress

This object represents a shipping address.

Field | Type | Description
--- | --- | ---
country_code | String | Two-letter ISO 3166-1 alpha-2 country code
state | String | State, if applicable
city | String | City
street_line1 | String | First line for the address
street_line2 | String | Second line for the address
post_code | String | Address post code

#### OrderInfo

This object represents information about an order.

Field | Type | Description
--- | --- | ---
name | String | Optional. User name
phone_number | String | Optional. User's phone number
email | String | Optional. User email
shipping_address | ShippingAddress | Optional. User shipping address

#### ShippingOption

This object represents one shipping option.

Field | Type | Description
--- | --- | ---
id | String | Shipping option identifier
title | String | Option title
prices | Array of LabeledPrice | List of price portions

#### SuccessfulPayment

This object contains basic information about a successful payment. Note that if the buyer initiates a chargeback with the relevant payment provider following this transaction, the funds may be debited from your balance. This is outside of Telegram's control.

Field | Type | Description
--- | --- | ---
currency | String | Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars
total_amount | Integer | Total price in the smallest units of the currency (integer, not float/double). For example, for a price of `US$ 1.45` pass `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).
invoice_payload | String | Bot-specified invoice payload
subscription_expiration_date | Integer | Optional. Expiration date of the subscription, in Unix time; for recurring payments only
is_recurring | True | Optional. True, if the payment is a recurring payment for a subscription
is_first_recurring | True | Optional. True, if the payment is the first payment for a subscription
shipping_option_id | String | Optional. Identifier of the shipping option chosen by the user
order_info | OrderInfo | Optional. Order information provided by the user
telegram_payment_charge_id | String | Telegram payment identifier
provider_payment_charge_id | String | Provider payment identifier

#### RefundedPayment

This object contains basic information about a refunded payment.

Field | Type | Description
--- | --- | ---
currency | String | Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars. Currently, always “XTR”
total_amount | Integer | Total refunded price in the smallest units of the currency (integer, not float/double). For example, for a price of `US$ 1.45`, `total_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).
invoice_payload | String | Bot-specified invoice payload
telegram_payment_charge_id | String | Telegram payment identifier
provider_payment_charge_id | String | Optional. Provider payment identifier

#### ShippingQuery

This object contains information about an incoming shipping query.

Field | Type | Description
--- | --- | ---
id | String | Unique query identifier
from | User | User who sent the query
invoice_payload | String | Bot-specified invoice payload
shipping_address | ShippingAddress | User specified shipping address

#### PreCheckoutQuery

This object contains information about an incoming pre-checkout query.

Field | Type | Description
--- | --- | ---
id | String | Unique query identifier
from | User | User who sent the query
currency | String | Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars
total_amount | Integer | Total price in the smallest units of the currency (integer, not float/double). For example, for a price of `US$ 1.45` pass `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).
invoice_payload | String | Bot-specified invoice payload
shipping_option_id | String | Optional. Identifier of the shipping option chosen by the user
order_info | OrderInfo | Optional. Order information provided by the user

#### PaidMediaPurchased

This object contains information about a paid media purchase.

Field | Type | Description
--- | --- | ---
from | User | User who purchased the media
paid_media_payload | String | Bot-specified paid media payload

#### RevenueWithdrawalState

This object describes the state of a revenue withdrawal operation. Currently, it can be one of

- RevenueWithdrawalStatePending
- RevenueWithdrawalStateSucceeded
- RevenueWithdrawalStateFailed

#### RevenueWithdrawalStatePending

The withdrawal is in progress.

Field | Type | Description
--- | --- | ---
type | String | Type of the state, always “pending”

#### RevenueWithdrawalStateSucceeded

The withdrawal succeeded.

Field | Type | Description
--- | --- | ---
type | String | Type of the state, always “succeeded”
date | Integer | Date the withdrawal was completed in Unix time
url | String | An HTTPS URL that can be used to see transaction details

#### RevenueWithdrawalStateFailed

The withdrawal failed and the transaction was refunded.

Field | Type | Description
--- | --- | ---
type | String | Type of the state, always “failed”

#### AffiliateInfo

Contains information about the affiliate that received a commission via this transaction.

Field | Type | Description
--- | --- | ---
affiliate_user | User | Optional. The bot or the user that received an affiliate commission if it was received by a bot or a user
affiliate_chat | Chat | Optional. The chat that received an affiliate commission if it was received by a chat
commission_per_mille | Integer | The number of Telegram Stars received by the affiliate for each 1000 Telegram Stars received by the bot from referred users
amount | Integer | Integer amount of Telegram Stars received by the affiliate from the transaction, rounded to 0; can be negative for refunds
nanostar_amount | Integer | Optional. The number of 1/1000000000 shares of Telegram Stars received by the affiliate; from -999999999 to 999999999; can be negative for refunds

#### TransactionPartner

This object describes the source of a transaction, or its recipient for outgoing transactions. Currently, it can be one of

- TransactionPartnerUser
- TransactionPartnerChat
- TransactionPartnerAffiliateProgram
- TransactionPartnerFragment
- TransactionPartnerTelegramAds
- TransactionPartnerTelegramApi
- TransactionPartnerOther

#### TransactionPartnerUser

Describes a transaction with a user.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “user”
transaction_type | String | Type of the transaction, currently one of “invoice_payment” for payments via invoices, “paid_media_payment” for payments for paid media, “gift_purchase” for gifts sent by the bot, “premium_purchase” for Telegram Premium subscriptions gifted by the bot, “business_account_transfer” for direct transfers from managed business accounts
user | User | Information about the user
affiliate | AffiliateInfo | Optional. Information about the affiliate that received a commission via this transaction. Can be available only for “invoice_payment” and “paid_media_payment” transactions.
invoice_payload | String | Optional. Bot-specified invoice payload. Can be available only for “invoice_payment” transactions.
subscription_period | Integer | Optional. The duration of the paid subscription. Can be available only for “invoice_payment” transactions.
paid_media | Array of PaidMedia | Optional. Information about the paid media bought by the user; for “paid_media_payment” transactions only
paid_media_payload | String | Optional. Bot-specified paid media payload. Can be available only for “paid_media_payment” transactions.
gift | Gift | Optional. The gift sent to the user by the bot; for “gift_purchase” transactions only
premium_subscription_duration | Integer | Optional. Number of months the gifted Telegram Premium subscription will be active for; for “premium_purchase” transactions only

#### TransactionPartnerChat

Describes a transaction with a chat.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “chat”
chat | Chat | Information about the chat
gift | Gift | Optional. The gift sent to the chat by the bot

#### TransactionPartnerAffiliateProgram

Describes the affiliate program that issued the affiliate commission received via this transaction.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “affiliate_program”
sponsor_user | User | Optional. Information about the bot that sponsored the affiliate program
commission_per_mille | Integer | The number of Telegram Stars received by the bot for each 1000 Telegram Stars received by the affiliate program sponsor from referred users

#### TransactionPartnerFragment

Describes a withdrawal transaction with Fragment.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “fragment”
withdrawal_state | RevenueWithdrawalState | Optional. State of the transaction if the transaction is outgoing

#### TransactionPartnerTelegramAds

Describes a withdrawal transaction to the Telegram Ads platform.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “telegram_ads”

#### TransactionPartnerTelegramApi

Describes a transaction with payment for paid broadcasting.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “telegram_api”
request_count | Integer | The number of successful requests that exceeded regular limits and were therefore billed

#### TransactionPartnerOther

Describes a transaction with an unknown source or recipient.

Field | Type | Description
--- | --- | ---
type | String | Type of the transaction partner, always “other”

#### StarTransaction

Describes a Telegram Star transaction. Note that if the buyer initiates a chargeback with the payment provider from whom they acquired Stars (e.g., Apple, Google) following this transaction, the refunded Stars will be deducted from the bot's balance. This is outside of Telegram's control.

Field | Type | Description
--- | --- | ---
id | String | Unique identifier of the transaction. Coincides with the identifier of the original transaction for refund transactions. Coincides with SuccessfulPayment.telegram_payment_charge_id for successful incoming payments from users.
amount | Integer | Integer amount of Telegram Stars transferred by the transaction
nanostar_amount | Integer | Optional. The number of 1/1000000000 shares of Telegram Stars transferred by the transaction; from 0 to 999999999
date | Integer | Date the transaction was created in Unix time
source | TransactionPartner | Optional. Source of an incoming transaction (e.g., a user purchasing goods or services, Fragment refunding a failed withdrawal). Only for incoming transactions
receiver | TransactionPartner | Optional. Receiver of an outgoing transaction (e.g., a user for a purchase refund, Fragment for a withdrawal). Only for outgoing transactions

#### StarTransactions

Contains a list of Telegram Star transactions.

Field | Type | Description
--- | --- | ---
transactions | Array of StarTransaction | The list of transactions