Как это устроено

Цепочка идентификаторов

Ваш пользователь, карта в Assalam и карта в банке — три разные сущности. Связывает их одна ссылка на каждом уровне.

Кто что хранит

Платформа не знает ваших пользователей. customerRef — произвольная строка, которую передаёте вы: ваш внутренний id, номер договора, что угодно. Для нас это метка без смысла, по ней удобно фильтровать список карт.

Что вы обязаны сохранить

После успешной привязки сохраните paymentMethodId рядом со своим пользователем. Это единственное, что нужно для будущих списаний.

Полезно сохранить и маску карты (maskedPan) — чтобы показывать клиенту, какой картой он платит, не обращаясь к нам лишний раз.

// таблица пользователей вашего продукта
{
  "userId": "user_1024",
  "phone": "998901234567",
  "assalamPaymentMethodId": "cmsr7d1e",
  "cardMask": "8600 31** **** 3131"
}

# берёте id карты из своей БД по своему пользователю
curl -X POST https://api.assalam.uz/subscribe/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1024" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 180000,
    "card": "cmsr…"
  }'

Если не сохранили — не страшно: карты клиента находятся по вашей же метке через GET /subscribe/v1/cards?customerRef=…. Но хранить у себя надёжнее и быстрее.

# найти карты по своей же метке клиента
curl "https://api.assalam.uz/subscribe/v1/cards?customerRef=user_1024" \
  -H "Authorization: Bearer sk_test_..."

{
  "object": "list",
  "data": [
    {
      "id": "cmsr7d1e",
      "object": "payment_method",
      "maskedPan": "860031******3131",
      "status": "ACTIVE",
      "processingSystem": "UZCARD",
      "customerRef": "user_1024"
    }
  ],
  "has_more": false
}

Объекты платформы

• Продукт — ваш сервис в платформе. У него свои ключи, свой баланс и свои карты. Объекты одного продукта не видны другому.
• Сессия привязки (checkout_session) — одноразовый процесс добавления карты. Живёт 15 минут, заканчивается получением карты.
• Карта (payment_method) — привязанная карта клиента. Хранится, пока её не отключат.
• Платёж (payment_intent) — одно списание. Создаётся, затем подтверждается.

Почему нельзя списать с чужой карты

Продукт определяется ключом API, а не телом запроса. Карта другого продукта или другого режима вернёт 404 — как несуществующая. Подставить чужой paymentMethodId не получится.

Внутри одного продукта разделения по клиентам нет: если у вас есть paymentMethodId, вы можете им списать. Следите за тем, чтобы ваш код брал идентификатор карты того пользователя, который сейчас платит.

Дальше по теме