Реквизиты карты — API Плати в Пути

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

Scope: cards:secret

Возвращает полный номер карты (PAN), CVV и срок действия.

Это вводит вас в периметр PCI DSS. Не храните, не логируйте и не кэшируйте ответ: передайте его держателю и забудьте. По той же причине ответ помечен no-store.

Для части карт эмитент показывает реквизиты только на своей странице. Тогда в ответе вместо них приходят view_url и view_expires_at, а pan, cvv и срок пустые: откройте ссылку держателю (во фрейме или новой вкладке) до истечения срока и запросите новую после. view_ttl_sec — сколько секунд ей осталось на момент ответа: считайте дедлайн от него, а не сравнивая свои часы с view_expires_at. Ссылка — тоже секрет: не логируйте и не храните её.

Нужны оба условия: ключ со scope cards:secret и открытый аккаунту доступ к реквизитам. Без любого из них — 403 card_secret_not_allowed.

Обращайтесь с ключом с этим scope как с самым чувствительным доступом: храните его секрет в менеджере секретов, заведите для него отдельный ключ, а не тот, которым выпускаете карты, и перевыпускайте при любом подозрении на утечку.

У эндпоинта свой, гораздо более строгий лимит запросов, и каждый вызов записывается.

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

Параметр	Тип	Обяз.	Описание
`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/secret" "" \
  | 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/secret" \
  -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/secret");

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

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

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

Ответ

200 OK — SecretOutputBody

Поле	Тип	Обяз.	Описание
`cacheable`	boolean	да	`false`: эмитент карты запрещает хранить эти реквизиты — покажите их держателю и удалите; не кэшируйте их ни в каком виде, даже зашифрованными. `true`: можно хранить под вашими собственными мерами PCI. Присутствует всегда.
`cvv`	string	да	Код безопасности карты
`expiry_month`	string	да	Месяц окончания, две цифры
`expiry_year`	string	да	Год окончания, четыре цифры
`masked_number`	string	нет	Маскированный номер, можно хранить
`pan`	string	да	Полный номер карты. Не храните и не логируйте
`view_expires_at`	string (date-time)	нет	Когда `view_url` перестаёт работать (RFC 3339). После этого запросите новую ссылку.
`view_ttl_sec`	integer	нет	Сколько секунд осталось жить `view_url` на момент этого ответа. Считайте дедлайн как момент получения ответа плюс это значение, а не по `view_expires_at`: ваши часы могут расходиться с нашими. (мин. 0)
`view_url`	string	нет	Короткоживущая ссылка на страницу реквизитов эмитента. Если она есть, `pan`, `cvv` и срок пустые. Это секрет: не логируйте и не храните её.

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

{
  "pan": "4000001234564821",
  "cvv": "123",
  "expiry_month": "10",
  "expiry_year": "2029",
  "masked_number": "**** **** **** 4821"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "partner_secret_not_allowed",
  "errors": [
    {
      "message": "card_secret_not_allowed",
      "location": "error.code",
      "value": "card_secret_not_allowed"
    }
  ]
}

Ошибки

HTTP	Код	Когда
403	`card_secret_not_allowed`	У ключа нет scope `cards:secret` или аккаунту не открыт доступ к реквизитам.
404	`not_found`	Карты нет или она выпущена не вашим аккаунтом.
429	`card_secret_rate_limited`	Превышен отдельный лимит запросов реквизитов.
503	`card_secret_reveal_disabled`	Выдача реквизитов временно выключена. Повторите позже.

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