CardV Merchant API

#Dokumentation

#Umgebungen

Die Sandbox ist eine eigene Testkopie von CardV mit Testgeld. API-Keys, Guthaben, Bestellungen und Produkt-IDs sind in beiden Umgebungen verschieden.

#Schnellstart

1. Registrieren. Beantragen Sie im Portal ein Händlerkonto und bestätigen Sie Ihre E-Mail-Adresse.

2. Freigabe abwarten. CardV prüft Ihr Unternehmen. Danach erhalten Sie eine Merchant ID (Ihre Händlernummer), zum Beispiel M00000001.

3. Sandbox öffnen. Melden Sie sich im Portal an und wählen Sie oben Sandbox. Sie erhalten 1.000 USD Testgeld.

4. API-Key erstellen. Gehen Sie im Portal zu Integrations → API keys. Erstellen Sie einen Key. Das Portal zeigt die Key-ID und das Signing Secret einmal an. Speichern Sie das Secret in Ihrem Secret Store.

5. Guthaben prüfen:

   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. Produkt suchen:

   ShellCopy

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

   Wählen Sie ein Produkt mit "availability": "available" und notieren Sie seine sku_id.

7. Preis abfragen:

   ShellCopy

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

   Notieren Sie merchant_price. Das ist Ihr Preis pro Stück.

8. Bestellen. Signieren Sie die Anfrage wie jede andere. Nehmen Sie ein Beispiel aus Authentifizierung und diesen Body:

   JSONCopy

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

   Sie erhalten HTTP 201 und eine CardV-Bestell-ID wie O-00001234.

9. Codes abrufen. Rufen Sie GET/api/v1/orders/O-00001234 auf, bis der Status succeeded ist. Die Codes stehen in items[].deliveries[]: card_number, pin_code und redeem_url. Sie können sich auch per Webhook benachrichtigen lassen, sobald die Bestellung fertig ist.

10. Live gehen, sobald die Sandbox-Checkliste erledigt ist.

Die IDs und Preise oben sind Beispiele. Verwenden Sie die Werte aus Ihrem eigenen Katalog.

#Die API im Überblick

Es gibt sechzehn Endpunkte. Alle Pfade beginnen mit /api/v1.

Alle anderen Endpunkte antworten mit HTTP 403, wenn Sie sie mit einem API-Key aufrufen:

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

Handy-Aufladungen sind unter Handy-Aufladung beschrieben.

#IDs

Speichern Sie IDs als Text und zerlegen Sie sie nicht. Siehe Grundregeln.

#Im Merchant Portal

• Wallet aufladen und E-Mail-Warnung bei niedrigem Guthaben
• Bestellverlauf, Suche und CSV-Export
• Rechnungen zu Bestellungen
• Wallet-Buchungen und Abgleich
• Webhooks einrichten, Zustellverlauf ansehen und erneut senden
• API-Keys
• IP-Allowlist
• Teammitglieder und Rollen
• Audit-Log
• Zwei-Faktor-Authentifizierung (2FA)
• Wechsel zwischen Live und Sandbox

#Kompatibilität und Support

Wir können jederzeit neue Felder und neue Statuswerte in Antworten ergänzen. Ignorieren Sie Felder, die Sie nicht kennen. Behandeln Sie einen unbekannten Bestellstatus als „noch nicht fertig“. Verlassen Sie sich nicht auf den Wortlaut von Fehlermeldungen.

Schreiben Sie an [email protected] und nennen Sie Ihre Merchant ID, die Umgebung, die Bestell-IDs, die Uhrzeit (UTC) und den HTTP-Status. Schicken Sie nie API-Keys, Signaturen, Webhook-Secrets oder Kartencodes.