CardV Merchant API

#Документация

#Среды

Sandbox — это отдельная тестовая копия CardV с тестовыми деньгами. Ключи, балансы, заказы и ID товаров в каждой среде свои.

#Быстрый старт

1. Подайте заявку на аккаунт в кабинете и подтвердите email.

2. Дождитесь одобрения. CardV проверяет вашу компанию. После этого вы получаете Merchant ID, например M00000001.

3. Откройте Sandbox. Войдите в кабинет и выберите Sandbox в верхней панели. Вам начислят 1 000 USD тестовых денег.

4. Создайте API-ключ. В кабинете откройте Integrations → API keys. Создайте ключ и откройте его с помощью кода, который CardV пришлёт вам на почту. Сохраните ключ в хранилище секретов.

5. Проверьте баланс:

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. Найдите товар:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

   Выберите товар с "availability": "available" и запишите его sku_id.

7. Узнайте цену:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

   Запомните merchant_price — это ваша цена за единицу.

8. Оформите заказ. Этот запрос нужно подписать. Возьмите пример из раздела Аутентификация и отправьте такое тело:

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
     ]
   }

   В ответ придёт HTTP 201 с номером заказа CardV, например O-00001234.

9. Получите коды. Вызывайте GET/api/v1/orders/O-00001234, пока статус не станет succeeded. Коды лежат в items[].deliveries[].display_fields. Можно также получать вебхук, когда заказ завершится.

10. Переходите в Live, когда пройдёте чек-лист Sandbox.

ID и цены выше — только примеры. Используйте значения из своего каталога.

#Кратко об API

Всего семь методов. Все пути начинаются с /api/v1.

Любой другой метод при вызове с API-ключом вернёт HTTP 403:

{"detail": "This operation is only available in the Merchant Portal."}

Пополнение мобильной связи через API недоступно.

#Идентификаторы

Храните ID как строки и не разбирайте их на части. Подробнее — в разделе Общие правила.

#Что делается в кабинете

• Пополнение кошелька и письмо о низком балансе
• История заказов, поиск и выгрузка в CSV
• Счета по заказам
• Операции по кошельку и сверка
• Настройка вебхуков, история отправок и повторная отправка
• API-ключи
• Список разрешённых IP
• Сотрудники и роли
• Журнал аудита
• Двухэтапная проверка (2FA)
• Переключение между Live и Sandbox

#Совместимость и поддержка

Мы можем без предупреждения добавлять новые поля в ответы и новые статусы. Незнакомые поля просто пропускайте. Если статус заказа вам незнаком, считайте, что заказ ещё не завершён. Не опирайтесь на формулировки сообщений об ошибках.

Пишите на [email protected]. Укажите Merchant ID, среду, номера заказов, время (UTC) и HTTP-статус. Никогда не присылайте API-ключи, подписи, секреты вебхуков и коды карт.