Получить карту — API Плати в Пути

GET/api/partner/v1/cards/{id}

Scope: cards:read

Возвращает вашу карту с текущим балансом, прочитанным у эмитента в момент запроса.

balance отсутствует, если эмитент не ответил: считайте отсутствующий баланс неизвестным, а не нулевым. Если balance_stale: true, это последнее записанное нами значение, а не живое чтение — число настоящее, но необратимую операцию на нём не стройте.

provider_missing: true значит, что эмитент перестал отдавать эту карту — скорее всего, её закрыли или удалили на его стороне. Мы не знаем, что она закрыта, поэтому не сообщаем «закрыта»: карта, которая была бы active или frozen, показывается как frozen, balance не отдаётся, пополнения отклоняются (card_not_active), пока наш оператор не проверит карту. Считайте карту непригодной и не показывайте её баланс. Закрыть её можно — так случай и разрешается, — а /secret продолжает отдавать реквизиты: они могут понадобиться держателю для спора. Если эмитент снова начнёт отвечать, флаг снимется сам и карта вернётся в своё реальное состояние.

Реквизитов карты здесь НЕТ. Их отдаёт только GET /cards/{id}/secret, и только если вашему аккаунту открыт доступ.

Параметры пути

Параметр	Тип	Обяз.	Описание
`id`	string (uuid)	да	Идентификатор карты

Пример запроса

TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" "GET" "/api/partner/v1/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" "" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS -X GET "https://api.plativputi.com/api/partner/v1/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
  -H "X-Key-Id: $PP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

const res = await pp("GET", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d");

res = pp("GET", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d")

$res = pp('GET', '/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d');

pp() — функция-обёртка с подписью из раздела Аутентификация и подпись.

Ответ

200 OK — CardDTO

Поле	Тип	Обяз.	Описание
`balance`	string (decimal)	нет	Текущий баланс карты. Нет поля — баланс неизвестен (не ноль)
`balance_stale`	boolean	нет	`true`, если `balance` — последнее известное значение, а не живое чтение
`created_at`	string	да	Когда карта создана, UTC
`currency`	string	нет	Валюта карты
`expires_at`	string	нет	Месяц/год окончания срока действия
`holder_external_id`	string	да	`external_id` держателя
`id`	string	да	Идентификатор карты
`masked_number`	string	нет	Маскированный номер — можно хранить и показывать
`payment_system`	string	нет	Платёжная система, например `VISA` или `MASTERCARD`
`provider_missing`	boolean	нет	`true`, если эмитент перестал отдавать карту; живая карта тогда показывается как `frozen`, пополнения отклоняются до проверки оператором
`state`	string	да	`creating` \| `active` \| `frozen` \| `wait_for_close` \| `closed` \| `expired` \| `failed`. Пока `provider_missing: true`, карта, которая была бы `active` или `frozen`, показывается как `frozen`; остальные состояния — как есть.

Примеры ответа

{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "state": "active",
  "holder_external_id": "cust-42",
  "masked_number": "**** **** **** 4821",
  "payment_system": "VISA",
  "currency": "USD",
  "balance": "50",
  "expires_at": "10/29",
  "created_at": "2026-10-07T09:13:02Z"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "not_found",
  "errors": [
    {
      "message": "not_found",
      "location": "error.code",
      "value": "not_found"
    }
  ]
}

Ошибки

HTTP	Код	Когда
404	`not_found`	Карты нет или она выпущена не вашим аккаунтом.

Плюс общие ошибки подписи и лимитов — см. Ошибки.