# Endpoint (API v2): Платёж Stripe по payment_intent_id

## Зачем это нужно

Когда по конкретному платежу нужно не строчка в списке, а всё целиком — этот метод возвращает **полный снэпшот одного платежа** по его идентификатору `payment_intent_id` (`pi_…`): тот же набор объектов Stripe, который приходит вам в вебхуке, плюс все связанные с платежом движения — возвраты и споры.

Типичные случаи: вебхук по платежу не дошёл и надо восстановить состояние; клиент утверждает, что оплатил; нужно проверить, не было ли по платежу возврата или спора.

Метод доступен и через **прямой HTTP API** (с вашим API-ключом), и через **MCP-агента** (тул `get_partner_stripe_payment`) — это одна и та же ручка.

Идентификатор платежа берётся из поля `payment_intent_id` в [списке платежей за период](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-api-v2-spisok-platezhej-stripe-za-period-HLmrFXTXwS) или из вебхука.

## Как подключиться


1. Возьмите API-ключ в мини-апп EasyPay («Show key» на первом шаге онбординга) — или запросите у вашего менеджера. Подробнее: [«Где взять API-ключ»](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/gde-vzyat-api-klyuch-dlya-integracii-s-claude-code-cursor-N8e3jiAxdz).
2. Нужно разрешение `balance_view` — то же, по которому вы смотрите баланс и список платежей.
3. API-ключ — строка в формате UUID, например: `18fcf8a0-cde3-4a27-ab7c-2f3bca09b9a2`.

## Endpoint

```
POST https://api.appsign.me/get-partner-stripe-payment
Content-Type: application/json
```

Ключ передаётся заголовком `X-Partner-Api-Key` **или** полем `api_key` в теле — на выбор.

## Формат запроса

```json
{
  "api_key": "ваш-api-ключ",
  "payment_intent_id": "pi_3TcXXXXXXXXXXXXX"
}
```

**Параметры:**

| Параметр | Обязательный | Описание |
|----------|--------------|----------|
| `api_key` | Да, если нет заголовка | API-ключ партнёра (UUID). Либо заголовок `X-Partner-Api-Key`. |
| `payment_intent_id` | Да           | Идентификатор платежа Stripe, строка вида `pi_…`. **Ровно один за вызов** — списки идентификаторов метод не принимает. |

Параметра `environment` здесь нет: `pi_…` уникален сам по себе, а окружение платежа возвращается полем в ответе.

## Формат ответа

### Успешный ответ

```json
{
  "success": true,
  "payment": {
    "id": "stripe:txn_3TcXXXXXXXXXXXXX",
    "amount": 99.00,
    "net_amount": 95.13,
    "fee": 3.87,
    "currency": "USD",
    "status": "completed",
    "transaction_date": "2026-08-18T14:22:05.000Z",
    "description": "Premium Plan",
    "environment": "live",
    "type": "stripe_payment_in",
    "is_subscription": false,
    "client_reference_id": "order-10482",
    "payment_intent_id": "pi_3TcXXXXXXXXXXXXX",
    "snapshot": {
      "payment_intent": { "…": "…" },
      "charge": { "…": "…" },
      "checkout_session": { "…": "…" },
      "invoice": { "…": "…" },
      "balance_transaction": { "…": "…" }
    }
  },
  "related_movements": [
    {
      "id": "stripe:txn_3TdYYYYYYYYYYYYY",
      "type": "stripe_refund",
      "amount": -99.00,
      "currency": "USD",
      "status": "refunded",
      "transaction_date": "2026-08-19T09:03:41.000Z"
    }
  ],
  "count": 2
}
```

**Поля верхнего уровня:**

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успехе. |
| `payment` | object | Основное движение по платежу — сама оплата. Если оплаты в наших данных нет (например, вы запросили `pi_…`, по которому есть только возврат), сюда попадает самое раннее движение. |
| `related_movements` | array | Остальные движения этого же платежа: возвраты, споры, разморозки. Без снэпшота. |
| `count` | number | Сколько всего движений найдено (основное + связанные). |

**Поля объекта** `**payment**` — те же, что в [списке платежей за период](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-api-v2-spisok-platezhej-stripe-za-period-HLmrFXTXwS) (`id`, `amount`, `net_amount`, `fee`, `currency`, `status`, `transaction_date`, `description`, `environment`, `type`, `is_subscription`, `client_reference_id`, `payment_intent_id`), плюс одно дополнительное:

| Поле | Тип | Описание |
|------|-----|----------|
| `snapshot` | object | Полный набор объектов Stripe по платежу: `payment_intent`, `charge`, `checkout_session`, `invoice`, `balance_transaction`, а также `subscription`, `refund`, `dispute` — когда они есть. Тот же состав, что приходит в ваш вебхук. Набор полей зависит от типа платежа: у разового платежа не будет данных подписки, у платежа без чекаут-сессии — её объекта. |

**Структура каждого элемента в** `**related_movements**`**:**

| Поле | Тип | Описание |
|------|-----|----------|
| `id` | string | Идентификатор движения (`stripe:txn_…`). |
| `type` | string \| null | Тип движения: `stripe_refund`, `stripe_dispute_freeze` и т. п. |
| `amount` | number | Сумма в основных единицах, со знаком: возврат — отрицательный. |
| `currency` | string | Валюта по ISO 4217. |
| `status` | string | `completed`, `pending`, `failed`, `refunded`, `disputed` или `dispute_won`. |
| `transaction_date` | string | Дата и время движения, ISO 8601 (UTC). |

### Ошибки

Все ошибки возвращаются с **HTTP 200** и полем `success: false`.

```json
{
  "success": false,
  "error_code": "PAYMENT_NOT_FOUND",
  "error_message": "No payment with payment_intent_id pi_… found for your account."
}
```

| `error_code` | Когда срабатывает |
|------------|-------------------|
| `INVALID_API_KEY` | API-ключ невалиден, не в формате UUID, либо партнёр/сотрудник отключён |
| `PERMISSION_DENIED` | У партнёра нет разрешения `balance_view` |
| `INVALID_INPUT` | `payment_intent_id` не передан, пустой, не является строкой или имеет неверный формат. Принимается только идентификатор вида `pi_…` — id charge (`ch_…`) или движения (`txn_…`) отклоняются |
| `PAYMENT_NOT_FOUND` | Платёж с таким `pi_…` не найден среди ваших платежей |
| `INTERNAL_ERROR` | Сбой на нашей стороне — повторите запрос позже |

> `PAYMENT_NOT_FOUND` приходит и когда платежа не существует вовсе, и когда он существует, но принадлежит другому партнёру — ответ намеренно одинаковый.

## Что важно знать

* Один вызов — один платёж. Если нужно проверить много платежей, сначала возьмите [список за период](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-api-v2-spisok-platezhej-stripe-za-period-HLmrFXTXwS), а точечный запрос делайте только по тем, где расходится с вашей системой.
* Запрос **только читает** и ничего не меняет: его можно безопасно повторять. Поле `idempotency_key` принимается для единообразия, но игнорируется.
* Возврат и спор не меняют исходное движение, а приходят отдельными записями — смотрите их в `related_movements`.
* Расшифровка объектов внутри `snapshot` — в статье [«Webhook EasyPay: структура данных платежей Stripe»](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/webhook-easypay-struktura-dannyh-platezhej-stripe-2aK80hyqzo).

## Пример на Python

```python
import urllib.request
import json

url = "https://api.appsign.me/get-partner-stripe-payment"
payload = {"payment_intent_id": "pi_3TcXXXXXXXXXXXXX"}

req = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "X-Partner-Api-Key": "ваш-api-ключ",
    },
    method="POST",
)

with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read().decode("utf-8"))

if result.get("success"):
    p = result["payment"]
    print(f"{p['amount']} {p['currency']} — {p['status']} ({p['transaction_date']})")
    for m in result["related_movements"]:
        print(f"  движение: {m['type']} {m['amount']} {m['currency']} — {m['status']}")
else:
    print(f"Ошибка: {result.get('error_code')} — {result.get('error_message')}")
```

## Пример на cURL

```bash
curl -X POST https://api.appsign.me/get-partner-stripe-payment \
  -H "Content-Type: application/json" \
  -H "X-Partner-Api-Key: ваш-api-ключ" \
  -d '{"payment_intent_id": "pi_3TcXXXXXXXXXXXXX"}'
```

## Через AI-агента

Если у вас подключён MCP-сервер EasyPay, попросите агента: «покажи всё по платежу pi_… — прошёл ли он, были ли возвраты». Агент вызовет тот же метод. Настройка — [«MCP-сервер EasyPay: настройка платежей в чате с AI»](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/mcp-server-easypay-nastrojka-platezhej-v-chate-s-ai-cqtpnWTk2i).