This document describes a set of custom Bot API methods that allow gift marketplaces to report completed gift purchase transactions.
Custom requests to the Bot API are performed using the special Bot API method sendCustomRequest.
| Parameters | Type | Required | Description |
|---|---|---|---|
| method | String | Yes | Custom method name. Currently supported values: reportGiftPurchase |
| parameters | Object | Yes | JSON-serialized custom method parameters |
reportGiftPurchaseReports a completed gift purchase that occurred on an external gift marketplace. Returns true on success.
This method must be called only after the transaction is fully completed.
| Field | Type | Required | Description |
|---|---|---|---|
| transaction_id | String | Yes | Unique transaction identifier on the marketplace side, 1-64 characters |
| transaction_date | Integer | Yes | Transaction date as a Unix timestamp (seconds) |
| amount | Integer | Yes | Total transaction amount in the smallest units of the currency. See examples below |
| currency | String | Yes | Transaction currency, “USD” or “TON”. If the original transaction was made in another currency, the amount must be converted to USD or TON using the current exchange rate at the time of the transaction |
| sale_type | String | Optional | Sale type, “listing”, “offer” or “auction”, defaults to “listing” |
| gift_name | String | Optional | Identifier of a single purchased gift (e.g. “plushpepe-1”). Used if exactly one gift was purchased |
| gift_names | Array of String | Optional | Identifiers of multiple purchased gifts. Used if a collection of multiple gifts was sold |
| buyer_id | Integer | Yes | Telegram user identifier of the buyer |
| seller_id | Integer | Optional | Telegram user identifier of the seller. Required if applicable |
| recipient_id | Integer | Optional | Telegram user identifier of the gift recipient. Required if applicable |
Exactly one of the fields gift_name or gift_names must be provided.
The amount field represents the total transaction price in the smallest units of the specified currency, as an integer.
For example:
- For USD, the amount must be provided in cents, so a price of US$ 1.45 must be sent as amount = 145
- For TON, the amount must be provided in nanotons, so a price of 1.23 TON must be sent as amount = 1230000000
{
"method": "reportGiftPurchase",
"parameters": {
"transaction_id": "9f3c2d4a-6e5b-4c7a-9f1d-2b8e3a6c4f10",
"transaction_date": 1770373392,
"amount": 5000000000000,
"currency": "TON",
"sale_type": "offer",
"gift_name": "plushpepe-1",
"buyer_id": 123456789,
"recipient_id": 987654321,
"seller_id": 555444333
}
}{
"method": "reportGiftPurchase",
"parameters": {
"transaction_id": "c1a7b9e2-3d44-4f6a-bc21-8d7e5f9a2c33",
"transaction_date": 1770373403,
"amount": 5000000,
"currency": "USD",
"sale_type": "listing",
"gift_names": [
"plushpepe-1",
"plushpepe-27",
"durovscap-1010"
],
"buyer_id": 123456789
}
}transaction_id must be unique per marketplace.sale_type must be set to listing for catalog purchases, to offer for purchases made via an offer and to auction for purchases completed as a result of an auction.USD or TON, the transaction amount must be converted to USD or TON using the current exchange rate at the time of the transaction.