Зарегистрировать держателя

POST/api/partner/v1/cardholders

Scope: cards:write
Idempotency-Key: необязателен

Регистрирует человека, на которого будет выпущена карта, или возвращает существующего держателя, если такой external_id уже встречался.

Используйте один external_id для одного человека. Первая карта нового держателя ждёт проверки личности у эмитента, следующие карты того же держателя её пропускают. Новый external_id на каждую карту — это каждый раз ожидание и повторная регистрация того же человека.

Имя и email становятся данными держателя. Остальные данные, которые требует эмитент, мы формируем сами.

Повторный вызов с тем же external_id и ДРУГИМ именем возвращает исходного держателя без изменений: к этому моменту имя уже зарегистрировано у эмитента и напечатано на выпущенных картах.

Тело запроса

Поле	Тип	Обяз.	Описание
`email`	string	да	Контактный адрес держателя (до 254 символов)
`external_id`	string	да	Ваш собственный идентификатор человека. Используйте его повторно для следующих карт; новое значение — новый держатель и новая проверка личности. (до 128 символов)
`first_name`	string	да	Имя латиницей, как оно будет на карте (до 64 символов)
`last_name`	string	да	Фамилия латиницей, как она будет на карте (до 64 символов)

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

BODY='{"external_id":"cust-42","first_name":"Ivan","last_name":"Petrov","email":"ivan.petrov@example.com"}'
IDEM=$(uuidgen)
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" "POST" "/api/partner/v1/cardholders" "$BODY" "$IDEM" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS -X POST "https://api.plativputi.com/api/partner/v1/cardholders" \
  -H "X-Key-Id: $PP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d "$BODY"

import { randomUUID } from "node:crypto";

const res = await pp("POST", "/cardholders", {
  "external_id": "cust-42",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "email": "ivan.petrov@example.com"
}, { idempotencyKey: randomUUID() });

import uuid

res = pp("POST", "/cardholders", body={
    "external_id": "cust-42",
    "first_name": "Ivan",
    "last_name": "Petrov",
    "email": "ivan.petrov@example.com",
}, idempotency_key=str(uuid.uuid4()))

$res = pp('POST', '/cardholders', [
    'external_id' => 'cust-42',
    'first_name' => 'Ivan',
    'last_name' => 'Petrov',
    'email' => 'ivan.petrov@example.com',
], uuid4());

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

Ответ

201 Created — CardholderDTO

Поле	Тип	Обяз.	Описание
`created_at`	string	да	Когда держатель зарегистрирован, UTC
`email`	string	да	Контактный адрес
`external_id`	string	да	Ваш идентификатор, возвращается как есть. Его вы передаёте в `holder_external_id` при выпуске карты.
`first_name`	string	да	Имя
`id`	string	да	Наш идентификатор держателя. Справочный: храните свой `external_id` — дедупликация идёт только по нему, и повторная регистрация человека по этому `id` создаст ВТОРОГО держателя.
`last_name`	string	да	Фамилия

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

{
  "id": "b7e1c9d2-4a3f-4c8e-a6b5-1f2e3d4c5b6a",
  "external_id": "cust-42",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "email": "ivan.petrov@example.com",
  "created_at": "2026-10-07T09:12:44Z"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "message": "expected required property email to be present",
      "location": "body",
      "value": {
        "external_id": "cust-42",
        "first_name": "Ivan",
        "last_name": "Petrov"
      }
    }
  ]
}

Ошибки

HTTP	Код	Когда
422	—	Нет обязательного поля или превышена длина.

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