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 und zeigen Sie ihn mit dem Code an, den CardV Ihnen per E-Mail schickt. Speichern Sie ihn in Ihrem Secret Store.

5. Guthaben prüfen:

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

   ShellCopy

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

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

7. Preis abfragen:

   ShellCopy

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

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

8. Bestellen. Diese Anfrage muss signiert sein. 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.2500"}
     ]
   }

   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[].display_fields. 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 sieben 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 (Mobilfunkguthaben) sind über die API nicht verfügbar.

#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.