# Gift Marketplaces

This document describes a set of custom Bot API methods that allow gift marketplaces to report completed gift purchase transactions.

## How to send requests

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 |

## Method: `reportGiftPurchase`

Reports 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](#amount-format) |
| 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.

---

#### Amount format

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`

#### Example: Single Gift Purchase

```json
{
  "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
  }
}
```

#### Example: Multiple Gifts Purchase

```json
{
  "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
  }
}
```

## Notes

- `transaction_id` must be unique per marketplace.
- The method must be called only after successful payment confirmation.
- `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.
- If a gift is sold in a currency other than `USD` or `TON`, the transaction amount must be converted to USD or TON using the current exchange rate at the time of the transaction.