Entwickler/Ökosystem & Ressourcen
CardV für Dujiao-Next
Fügen Sie CardV als Lieferanten in Ihrem Dujiao-Next-Shop hinzu. Sie importieren Geschenkkarten und Spiele-Aufladungen von CardV als eigene Produkte und legen Ihre eigenen Preise fest. Sobald ein Käufer bezahlt, kauft Ihr Shop den Artikel mit Ihrem CardV-Guthaben bei CardV, und der Code erscheint automatisch auf der Bestellseite des Käufers.
#Voraussetzungen
| Dujiao-Next | v1.5.0 oder neuer, mit der Funktion für Upstream-Verbindungen (Menü Integration) |
| CardV-Konto | Ein freigegebenes Händlerkonto mit aktiviertem API-Zugang |
| API-Key | Ein signierter API-Key aus dem Merchant Portal (Key-ID + Signing Secret) |
| Guthaben | Vorausbezahltes CardV-Guthaben in USD. Jede Bestellung Ihres Shops wird daraus bezahlt |
Gegenüber Ihren Käufern sind Sie der Verkäufer: Sie legen die Preise fest, beantworten ihre Fragen und übernehmen ihre Erstattungen.
#Schritt 1: API-Key bereitstellen
Verwenden Sie den API-Key, den Sie bereits im Merchant Portal unter API & Webhooks > API-Schlüssel haben. Für Dujiao-Next brauchen Sie keinen eigenen Key.
- Die Key-ID (im Portal: Schlüssel-ID) beginnt mit
ck_live_. - Das Signing Secret (im Portal: Signatur-Secret) beginnt mit
cs_live_. Es wird nur einmal angezeigt, wenn der Key erstellt wird. Wenn Sie es nicht mehr haben, nutzen Sie beim Key Secret neu erzeugen. Die Key-ID bleibt gleich, und das alte Secret funktioniert sofort nicht mehr.
Ältere Keys ohne Key-ID können nicht verwendet werden. Erstellen Sie stattdessen im Portal einen neuen Key.
#Schritt 2: Verbindung hinzufügen
Öffnen Sie im Dujiao-Next-Admin Integration > Connection Management > New Connection und füllen Sie das Formular aus:
| Feld | Was Sie eintragen | Warum |
|---|---|---|
| Name | Zum Beispiel CardV (USD) | Nur Sie sehen ihn. Mit der Währung im Namen vermeiden Sie später Verwechslungen |
| Base URL | https://b2b.cardv.net/dujiao | Mit /dujiao und nichts dahinter, ohne abschließenden Schrägstrich |
| API Key | Ihre Key-ID (ck_live_…) | |
| API Secret | Ihr Signing Secret (cs_live_…) | Wenn Sie die Verbindung später bearbeiten, lassen Sie das Feld leer, um das gespeicherte Secret zu behalten |
| Protocol | dujiao-next | |
| Callback URL | Leer lassen | CardV sendet keine Callbacks. Ihr Shop fragt das Ergebnis jeder Bestellung selbst ab (siehe So funktioniert die Auslieferung) |
| Max Retries / Retry Intervals | Standardwerte beibehalten (3 / 30,60,120) | Wiederholungen gelten nur für vorübergehende Fehler |
| Exchange Rate | Eine feste Zahl, die Sie selbst eintragen: der aktuelle reale Kurs von USD in Ihre Shop-Währung, als Puffer etwas höher angesetzt. Tragen Sie 1 ein, wenn Ihr Shop in USD verkauft | CardV-Preise sind immer in USD. Dujiao-Next ruft keine Live-Kurse ab, und CardV kann diesen Wert nicht für Sie setzen. Der Standardwert ist 1. Ein Shop, der in einer anderen Währung verkauft, würde eine Karte für 10 USD dann für 10 in seiner eigenen Währung anbieten |
| Price Markup (%) | Ihre Marge, zum Beispiel 15 | Der Standardwert ist 0, also kein Gewinn |
| Price Rounding | Round up (0.1) oder Round up (integer) | Durch Aufrunden liegt Ihr Preis nie unter Ihren Kosten |
| Auto-update price on sync | Yes | Wenn sich ein CardV-Preis ändert, wird Ihr Verkaufspreis bei der nächsten Synchronisierung neu berechnet |
Wechselkurs und Aufschlag werden so kombiniert: CardV-Preis × Wechselkurs × (1 + Aufschlag), dann gerundet. Ein Beispiel: Bei einem Kurs von 7.2 (nur ein Beispiel; tragen Sie den aktuellen Kurs ein, den Sie nachschlagen) und 15 % Aufschlag wird eine Karte für 5.78 USD für 47.9 verkauft.
Wenn sich der Wechselkurs ändert, aktualisieren Sie ihn in der Verbindung und klicken Sie auf Reapply Markup, um die Preise bereits importierter Produkte zu aktualisieren. Gehen Sie genauso vor, wenn Sie den Aufschlag ändern.
#Schritt 3: Verbindung testen
Klicken Sie bei der Verbindung auf Ping. Ping succeeded bedeutet, dass Ihr Key funktioniert, und der Status der Verbindung wechselt auf Active. Wenn stattdessen ein Fehler erscheint, lesen Sie Fehlerbehebung.
#Schritt 4: Produkte importieren
- Öffnen Sie Integration > Product Mappings > Import from Upstream und wählen Sie Ihre CardV-Verbindung.
- Durchsuchen Sie die Kategorien oder wechseln Sie zu Flat List, um einzelne Produkte auszuwählen.
- Wählen Sie eine lokale Kategorie oder aktivieren Sie Auto-create local categories. Ein Produkt braucht eine Kategorie, bevor Sie es speichern können.
- Importieren Sie. Jedes Produkt behält Titel, Beschreibung, Einlöseanleitung und Nennwerte (zum Beispiel
10 USD).
Importierte Produkte sind zunächst nicht im Verkauf. Prüfen Sie jedes Produkt und aktivieren Sie dann im Produkteditor Active.
#Schritt 5: Ein Artikel pro Bestellung festlegen
Öffnen Sie für jedes importierte Produkt den Produkteditor und setzen Sie Max purchase quantity auf 1.
CardV liefert einen Artikel pro Bestellung aus. Bezahlt ein Käufer zwei Codes in einer Bestellung, lehnt CardV den Kauf ab, und Sie müssen diese Bestellung von Hand klären. Dujiao-Next kann dieses Limit nicht automatisch von CardV übernehmen, deshalb müssen Sie es selbst setzen.
Wenn Sie schon im Editor sind, empfehlen wir außerdem:
- Bestandsanzeige im Shop: Wählen Sie Hide quantity. CardV kauft bei der Marke ein, wenn eine Bestellung eingeht. Die Bestandszahl in Ihrem Shop bedeutet daher nur „verfügbar“.
- Bilder: Fügen Sie eigene hinzu, wenn ein Produkt keine hat.
#So funktioniert die Auslieferung
- Der Käufer bezahlt in Ihrem Shop.
- Ihr Shop sendet den Kauf an CardV, und CardV belastet Ihr CardV-Guthaben.
- Ihr Shop fragt die Bestellung bei CardV ab. In unseren Tests kam der Code innerhalb einer Minute an.
- Der Code erscheint auf der Bestellseite des Käufers als
Code,PIN(wenn die Karte eine hat) undExpires(wenn die Karte ein Ablaufdatum hat). Es ist immer ein Code, nie ein Link.
Direkte Aufladungen. Manche Produkte werden direkt dem Spiel- oder App-Konto des Käufers gutgeschrieben. Beim Checkout gibt der Käufer die Angaben ein, die das Produkt braucht, zum Beispiel eine Spieler-ID oder eine Telefonnummer. Wenn die Aufladung erledigt ist, zeigt die Bestellseite des Käufers Top-up completed.
Wenn CardV nicht liefern kann. CardV erstattet die Bestellung auf Ihr CardV-Guthaben, und Ihr Shop markiert den Kauf als storniert. Sie erstatten dann dem Käufer in Ihrem Shop oder helfen ihm weiter.
#Was nicht verfügbar ist
Die Importliste zeigt nur Produkte, die Ihr Shop über diese Verbindung verkaufen kann:
- Nur feste Nennwerte. Karten, bei denen der Käufer seinen eigenen Betrag eingibt, werden nicht angezeigt.
- Nicht aufgeführt: Mobilfunk-Aufladungen, Zahlungs- und Wallet-Produkte, Krypto und Prepaid-Zahlungskarten.
- Nur Codes. Produkte, die nur als Link ausgeliefert werden können, werden nicht angezeigt.
Die angezeigten Preise sind Ihre eigenen CardV-Preise in USD.
#IP-Whitelist
Wenn Sie im Merchant Portal eine IP-Whitelist eingerichtet haben, fügen Sie die öffentliche IP-Adresse des Servers hinzu, auf dem Ihr Dujiao-Next-Shop läuft. Andernfalls lehnt CardV jede Anfrage von diesem Server ab. Für die CardV API und für Dujiao-Next gelten derselbe Key, dieselbe Whitelist und dieselben Anfragelimits.
#Fehlerbehebung
Diese Meldungen sehen Sie im Dujiao-Next-Admin, nach Ping, beim Import oder bei einem Kauf unter Procurement Orders.
| Meldung | Ursache | Was zu tun ist |
|---|---|---|
status 401 (invalid_signature): signature verification failed | Das API Secret ist falsch, oder Sie haben es im Portal neu erzeugt | Kopieren Sie das aktuelle Signing Secret in die Verbindung |
status 403 (invalid_api_key): api key is invalid or disabled | Der API Key ist keine Key-ID (ck_live_…), oder der Key ist deaktiviert | Verwenden Sie die Key-ID eines aktiven Keys |
status 403 (user_disabled): merchant API access is not enabled | Ihr Konto ist noch nicht für den API-Zugang freigegeben | Schließen Sie die Unternehmensprüfung im Portal ab |
status 403 (forbidden): source IP is not allowed for this merchant | Ihre IP-Whitelist enthält den Server Ihres Shops nicht | Fügen Sie die öffentliche IP-Adresse des Servers im Portal hinzu |
status 401 (timestamp_expired): timestamp expired | Die Uhr Ihres Servers weicht um mehr als 60 Sekunden ab | Aktivieren Sie auf dem Server die automatische Zeitsynchronisierung (NTP) |
status 404 gefolgt von einer Webseite | Die Base URL ist falsch, meist fehlt /dujiao | Verwenden Sie https://b2b.cardv.net/dujiao |
CardV wallet balance is insufficient | Ihr CardV-Guthaben reicht für den Kauf nicht aus. Die Bestellung des Käufers bleibt bezahlt | Laden Sie Ihr CardV-Guthaben auf und klicken Sie dann beim Kauf unter Procurement Orders auf Retry |
quantity must be 1: CardV accepts one item per order | Ein Käufer hat mehr als einen Artikel eines Produkts bestellt | Setzen Sie Max purchase quantity auf 1 (Schritt 5) und bearbeiten Sie die Bestellung dann von Hand |
sku is invalid or not available | Das Produkt ist bei CardV nicht mehr verfügbar | Synchronisieren Sie das Mapping. Produkte, die CardV nicht mehr anbietet, werden aus dem Verkauf genommen |
status 429 (rate_limited) | Zu viele Anfragen in einer Minute | Ihr Shop wiederholt die Anfrage selbst. Senken Sie die Synchronisierungshäufigkeit, wenn es weiter passiert |
#FAQ
Brauche ich einen neuen API-Key für Dujiao-Next? Nein. Verwenden Sie den signierten API-Key, den Sie bereits haben. Wenn Sie den Key auch für Ihre eigene Anbindung an die CardV API nutzen, teilen sich beide dieselben Anfragelimits.
Warum lasse ich die Callback URL leer? CardV sendet keine Callbacks an Shops. Ihr Dujiao-Next-Shop fragt jede Bestellung selbst ab, bis das Ergebnis endgültig ist.
Was passiert, wenn sich CardV-Preise ändern? Ist Auto-update price on sync aktiviert, werden Ihre Verkaufspreise bei der nächsten Synchronisierung mit Ihrem Kurs und Aufschlag neu berechnet. Ist es deaktiviert, verkauft Ihr Shop weiter zum alten Preis.
Wo sehe ich diese Bestellungen bei CardV? Auf der Seite Bestellungen im Merchant Portal. Die Spalte Ihre Bestell-ID beginnt mit dujiao:, gefolgt von der Nummer der Dujiao-Next-Teilbestellung (zum Beispiel dujiao:DJ…-01). Wenn Sie CardV-Webhooks eingerichtet haben, werden sie auch für diese Bestellungen ausgelöst.
Kann ich Produkttitel, Beschreibungen und Bilder ändern? Ja. Die Synchronisierung aktualisiert Preise und Verfügbarkeit. Ihre Titel und Bilder überschreibt sie nicht.
Kann ich freie Beträge verkaufen? Über Dujiao-Next noch nicht. Es sind nur feste Nennwerte verfügbar.
#Support
Schreiben Sie an [email protected] und geben Sie Ihre Merchant ID, die Dujiao-Next-Bestellnummer und die Fehlermeldung an. Für Ihre Nutzung von CardV gelten unsere Nutzungsbedingungen.
Fragen zur Integration? Schreiben Sie an [email protected] und nennen Sie Ihre Merchant ID sowie die Bestell- oder Request-ID.