CardV Merchant API

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

#Среды

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

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

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

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

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

4. Создайте API-ключ. В кабинете откройте Integrations → API keys. Создайте ключ. Кабинет один раз покажет ID ключа и секрет подписи. Сохраните секрет в хранилище секретов.

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

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

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

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

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

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

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

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

8. Оформите заказ. Подпишите его, как и любой запрос. Возьмите пример из раздела Аутентификация и отправьте такое тело:

   JSONCopy

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

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

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

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

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

#Кратко об API

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

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

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

Пополнение мобильной связи описано в разделе Пополнение мобильной связи.

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

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

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

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

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

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

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