Produkte und Bestellungen

Siehe auch: Authentifizierung · Grundregeln · Webhooks

#Konto und Guthaben

#Konto

GET/api/v1/account zeigt Ihre Firmendaten und ob die API für Sie freigeschaltet ist.

{
  "merchant_id": "M00000001",
  "name": "Acme Shop",
  "legal_name": "Acme Shop Ltd",
  "billing_email": "[email protected]",
  "status": "active",
  "kyb_status": "approved",
  "api_access_enabled": true,
  "default_currency": "USD",
  "purchase_limits": {
    "currency": "USD",
    "verified": true,
    "max_order_amount": "1000.00",
    "daily_order_amount_limit": "10000.00",
    "daily_order_count_limit": 1000,
    "used_today_amount": "120.50",
    "used_today_count": 3,
    "day_resets_at": "2026-10-01T00:00:00+00:00"
  }
}

• default_currency ist die Währung Ihrer Wallet. Alle Preise, die Sie bezahlen, sind in dieser Währung.
• api_access_enabled ist true, sobald CardV Ihr Unternehmen freigegeben hat.

#Guthaben

GET/api/v1/balance zeigt, wie viel Guthaben Sie ausgeben können.

{
  "currency": "USD",
  "balance": "1520.40",
  "reserved_amount": "0.00",
  "available_balance": "1520.40",
  "low_balance_threshold": "200.00",
  "low_balance_notified_at": null,
  "is_active": true
}

• available_balance können Sie jetzt ausgeben. Es ist balance minus reserved_amount.
• Eine Bestellung über available_balance hinaus wird abgelehnt. Es wird nichts abgebucht.
• low_balance_threshold ist die Schwelle für die E-Mail bei niedrigem Guthaben. Sie legen sie im Portal fest.
• Guthaben laden Sie im Portal auf.

#Wechselkurs

GET/api/v1/fx-rates?quote=EUR liefert den Kurs von USD in eine andere Währung.

Nutzen Sie ihn, wenn Ihr Shop nicht in USD verkauft. CardV belastet Ihr Wallet immer in USD. Der Kurs hilft Ihnen nur, Ihre eigenen Preise festzulegen.

{
  "base": "USD",
  "quote": "EUR",
  "rate": "0.9234",
  "as_of": "2026-10-11T07:05:00Z"
}

• quote ist ein ISO-4217-Währungscode, zum Beispiel EUR, GBP oder JPY.
• base ist optional. Nur USD wird unterstützt.
• rate gibt an, wie viele Einheiten von quote Sie für 1 USD erhalten. Der Wert ist ein Dezimal-String. Lesen Sie ihn nicht als Float.
• as_of ist der Zeitpunkt, an dem CardV diesen Kurs zuletzt aktualisiert hat. Kurse werden stündlich aktualisiert.
• quote=USD liefert "rate": "1".
• Speichern Sie den Kurs bei sich. Einige Abfragen pro Tag genügen.

Signieren Sie diese Anfrage wie jede andere. Der signierte Pfad enthält den Query-String, zum Beispiel /api/v1/fx-rates?quote=EUR.

#Produkte (SKUs)

Eine SKU ist ein einzelnes Produkt, das Sie kaufen können, zum Beispiel „Steam Wallet 10 USD“. Ihre ID sieht so aus: S000456. Preisabfragen und Bestellungen beziehen sich immer auf eine SKU.

#Produktmodelle

Jede SKU gehört zu einem dieser Modelle. Unterscheiden Sie sie anhand von denomination_type und product_type.

• vertical ist die Produktlinie, nicht das Modell. Auch Direktaufladungen können vertical: "gift_card" haben.
• Jede SKU mit festem oder freiem Betrag kann statt eines Codes als CardV-Einlöse-Link geliefert werden. Die SKU hat dann delivery_mode: "voucher". Sie erhalten einen Link (delivery_type: "link", der Link steht in redeem_url). Ihr Kunde öffnet ihn und erhält so den Code. Geben Sie ihn wie einen Code an Ihren Kunden weiter.

GET/api/v1/skus listet die SKUs auf, die Sie kaufen können. Beispiel:

GET /api/v1/skus?search=steam&region=US&limit=50&offset=0

Filter (alle optional):

Seitenweise Abfrage: Senden Sie limit (Standard 100, höchstens 500) und offset. Fragen Sie mit steigendem offset weiter ab, bis offset den Wert count erreicht.

{
  "count": 7,
  "limit": 2,
  "results": [
    {
      "sku_id": "S000456",
      "product_id": "P000123",
      "name": "Steam Wallet 10 USD",
      "product_name": "Steam Wallet US",
      "brand": "Steam",
      "region": "US",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "fixed",
      "denomination_value": "10",
      "face_currency": "USD",
      "merchant_price": "9.25",
      "merchant_price_min": "9.25",
      "merchant_price_max": "9.25",
      "settlement_currency": "USD",
      "availability": "available",
      "min_quantity": 1,
      "max_quantity": 100,
      "required_input_schema": [],
      "...": "more fields"
    },
    {
      "sku_id": "S006126",
      "product_id": "P002210",
      "name": "Apple ES",
      "product_name": "Apple ES",
      "brand": "Apple",
      "region": "ES",
      "vertical": "gift_card",
      "product_type": "pin_code",
      "denomination_type": "range",
      "denomination_value": "0",
      "min_face_value": "2",
      "max_face_value": "250",
      "amount_step": null,
      "face_currency": "EUR",
      "merchant_price": "2.28",
      "merchant_price_min": "2.28",
      "merchant_price_max": "284.15",
      "price_label": "From 2.28 USD",
      "settlement_currency": "USD",
      "availability": "available",
      "...": "more fields"
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/skus/{sku_id} liefert eine einzelne SKU mit denselben Feldern.

Die wichtigsten Felder:

Tipps:

• Sie sehen nur SKUs, die aktiv und für Ihr Konto freigegeben sind. Andere SKUs liefern 404.
• Aktualisieren Sie die SKU-Liste alle 5–15 Minuten. Fragen Sie den Preis immer direkt vor der Bestellung ab.
• Zeigen Sie Ihren Kunden die Preise aus Ihrer synchronisierten Liste. Rufen Sie die Preisabfrage nicht bei jedem Seitenaufruf oder für jeden Besucher auf.
• Die Preise von SKUs mit freiem Betrag folgen den Lieferantenkosten und können sich mehrmals am Tag ändern. Aktualisieren Sie merchant_price_min und merchant_price_max bei Ihrer SKU-Synchronisierung.
• filter_options nennt die Marken, Regionen und Produktbereiche, nach denen Sie filtern können.

#Nach Produkten synchronisieren

Wenn Ihr Shop eine Seite pro Produkt mit Betragsauswahl zeigt, synchronisieren Sie Produkte statt SKUs. GET/api/v1/products listet Produkte. Jedes Produkt enthält alle SKUs, die Sie darin kaufen können.

GET /api/v1/products?brand=Steam&region=GB&limit=50&offset=0

Filter und Paging sind dieselben wie bei GET/api/v1/skus. count zählt Produkte, sku_count deren SKUs.

{
  "count": 1,
  "sku_count": 4,
  "limit": 50,
  "results": [
    {
      "product_id": "P000123",
      "product_name": "Steam Wallet UK",
      "brand": "Steam",
      "category": "Gaming",
      "region": "GB",
      "product_type": "pin_code",
      "image_url": "https://b2b.cardv.net/api/v1/catalog-assets/steam.png",
      "required_input_schema": [],
      "skus": [
        {
          "sku_id": "S000456",
          "name": "Steam Wallet 5 GBP",
          "label": "5 GBP",
          "denomination_type": "fixed",
          "denomination_value": "5",
          "face_currency": "GBP",
          "merchant_price": "7.61",
          "settlement_currency": "USD",
          "availability": "available",
          "min_quantity": 1,
          "max_quantity": 100,
          "...": "more fields"
        }
      ]
    }
  ],
  "filter_options": {"brands": [], "regions": [], "categories": [], "verticals": []}
}

GET/api/v1/products/{product_id} liefert ein Produkt mit seinen SKUs sowie description, redemption_instructions, terms und disclaimer.

• Jede SKU in skus hat dieselben Felder und Werte wie in GET/api/v1/skus. Angebot und Bestellung laufen wie gewohnt über die sku_id.
• Nutzen Sie label als Optionstext, zum Beispiel 5 GBP oder Tinder Plus 1 Month. Manche Produkte sind Tarife, keine Beträge.
• Ein Produkt hat genau eine Nennwertwährung und eine Betragsart. Eine SKU mit freiem Betrag ist immer ein eigenes Produkt.
• Die Liste enthält keine langen Texte. Lesen Sie diese einmal pro Produkt über GET/api/v1/products/{product_id}.

#Feste und freie Beträge

Die meisten SKUs haben einen festen Nennwert, zum Beispiel 10 USD. Einige SKUs haben einen Bereich: Ihr Kunde wählt den Betrag selbst, zum Beispiel 5 bis 500 USD.

Bei einer SKU mit Bereich muss amount zwischen min_face_value und max_face_value liegen. Der Betrag ist in face_currency angegeben.

Preis einer SKU mit freiem Betrag. In den SKU- und Produktlisten sind merchant_price und price_label nur der Preis für min_face_value. merchant_price_min und merchant_price_max geben den Preis des kleinsten und des größten Betrags an. Der Preis eines Betrags dazwischen ist kein einfaches Vielfaches von einem der beiden. Holen Sie vor der Festlegung Ihres Verkaufspreises oder einer Bestellung ein Angebot mit dem genauen amount ein und senden Sie dessen merchant_price als expected_unit_price.

Manche SKUs mit Bereich haben zusätzlich ein amount_step. Ist es nicht null, muss amount ein Vielfaches davon sein. Bei "amount_step": "1" können Sie zum Beispiel 25 senden, aber nicht 25.50. Ein Angebot oder eine Bestellung mit einem Betrag, der nicht zur Schrittweite passt, liefert HTTP 400. Es wird nichts abgebucht.

#Direktaufladungen

Manche Produkte laden das Konto Ihres Kunden direkt auf, zum Beispiel ein Spielkonto. Dafür braucht CardV die Kontodaten. Welche das sind, steht in der SKU:

"required_input_schema": [
  {"key": "player_id", "label": "Player ID", "type": "text", "required": true},
  {"key": "server", "label": "Server", "type": "text", "required": false}
]

Senden Sie die Werte in den inputs der Bestellposition, jeweils unter dem passenden key:

"inputs": {"player_id": "123456789", "server": "EU"}

• Ein Feld ist Pflicht, außer es steht "required": false dabei. type ist ein Hinweis für Ihr Formularfeld, zum Beispiel text.
• Fehlt ein Pflichtwert, wird die Bestellung mit einem items-Fehler abgelehnt.
• Diese Werte sind personenbezogene Daten Ihrer Kunden. Schützen Sie sie (siehe Sicherheit).

#Preisabfrage

Eine Preisabfrage nennt Ihnen den aktuellen Preis für eine bestimmte Menge.

GET /api/v1/skus/S000456/quote?quantity=2
GET /api/v1/skus/S000789/quote?quantity=1&amount=25.00

{
  "sku_id": "S000456",
  "settlement_currency": "USD",
  "merchant_price": "9.25",
  "quantity": 2,
  "total_price": "18.50",
  "min_quantity": 1,
  "max_quantity": 100,
  "availability": "available"
}

• Eine Preisabfrage reserviert den Preis nicht. Preise können sich jederzeit ändern.
• Fragen Sie den Preis einmal ab, wenn Ihr Kunde zur Kasse geht, mit einem kurzen Timeout von z. B. 5 Sekunden. Läuft die Abfrage in den Timeout, zeigen Sie weiter Ihren synchronisierten Preis an und versuchen Sie es erneut; zeigen Sie nie eine Fehlerseite, nur weil eine Preisabfrage langsam war.
• Zu Ihrem Schutz senden Sie merchant_price bei der Bestellung als expected_unit_price mit. Senden Sie den Preis aus einer Preisabfrage, nicht einen selbst berechneten Preis: Er muss exakt übereinstimmen, auf den Cent genau. Hat sich der Preis geändert, lehnt CardV die Bestellung ab und bucht nichts ab.
• Liegen Menge oder Betrag außerhalb des erlaubten Bereichs oder ist der Betrag kein Vielfaches von amount_step, erhalten Sie HTTP 400 mit einem quantity- oder amount-Fehler.

#Bestellen

POST/api/v1/orders kauft eine oder mehrere SKUs und bezahlt aus Ihrer Wallet. Wie jede Anfrage muss sie signiert sein.

{
  "external_order_id": "SHOP-20260929-10001",
  "items": [
    {"sku_id": "S000456", "quantity": 2, "expected_unit_price": "9.25"},
    {"sku_id": "S000789", "amount": "25.00", "expected_unit_price": "23.75"},
    {
      "sku_id": "S000900",
      "expected_unit_price": "4.90",
      "inputs": {"player_id": "123456789"}
    }
  ]
}

Nimmt CardV die Bestellung an, wird der gesamte Betrag sofort von Ihrer Wallet abgebucht. Die Lieferung läuft danach im Hintergrund.

Die Antwort kommt mit HTTP 201:

{
  "idempotent_replay": false,
  "order": {
    "order_id": "O-00001234",
    "external_order_id": "SHOP-20260929-10001",
    "status": "accepted",
    "total_amount": "46.20",
    "...": "more fields"
  }
}

Speichern Sie order.order_id. Diese Antwort enthält nie Codes. Die rufen Sie später ab (Bestellung abrufen).

#Abgelehnte Bestellungen

Eine abgelehnte Bestellung liefert HTTP 400. Es wird nichts abgebucht. Der Fehlerschlüssel nennt den Grund:

Beispiel für eine Preisänderung:

{
  "items": "SKU S000456 price changed from 9.25 to 9.41 USD; refresh quote and confirm again."
}

Ihr Konto hat Limits pro Bestellung, für den Tagesumsatz und für die Zahl der Bestellungen pro Tag. GET/api/v1/account zeigt sie in purchase_limits, zusammen mit Ihrer heutigen Nutzung. 0 bedeutet kein Limit. Tageslimits beginnen um 00:00 UTC neu.

#Sicher erneut senden

Ihre Bestellnummer (external_order_id) schützt Sie vor doppelten Käufen. Senden Sie dieselbe Bestellung mit derselben Bestellnummer noch einmal, bucht CardV nicht erneut ab. Sie erhalten die Bestellung zurück, die es schon gibt.

„Dieselbe Bestellung“ heißt: dieselben Positionen in derselben Reihenfolge, jeweils mit gleicher SKU, Menge, gleichem Betrag und gleichen Angaben. Wenn Sie expected_unit_price mitsenden, muss der Wert zum Preis der ersten Bestellung passen.

Eine wiederholte Bestellung wird vor der Guthaben- und Preisprüfung erkannt. Deshalb erhalten Sie immer die erste Bestellung zurück, auch wenn sich der Preis inzwischen geändert hat.

#Ablauf beim erneuten Senden

Wenn Sie keine eindeutige Antwort erhalten, senden Sie einfach dieselbe Bestellung noch einmal.

POST /orders mit Bestellnummer R
 ├─ 201 oder 200 → order_id speichern. Fertig.
 ├─ 400 items / balance / risk → es wurde keine Bestellung angelegt.
 │      Ursache beheben und erneut senden. R darf wiederverwendet werden.
 ├─ 400 external_order_id → R gehört zu einer anderen Bestellung. Anhalten und prüfen.
 ├─ 403 Signaturfehler → neu signieren und denselben Body senden.
 ├─ 429 → Retry-After abwarten, neu signieren, denselben Body senden.
 └─ Timeout, 5xx oder Verbindung abgebrochen
        → denselben Body mit demselben R erneut senden.
          Sie erhalten 201 (der erste Versuch kam nicht an) oder 200 (er kam an).

Regeln:

• Vergeben Sie nie eine neue Bestellnummer, nur weil eine Antwort verloren ging. Ist die erste Anfrage doch angekommen, kaufen Sie mit einer neuen Nummer alles doppelt.
• Jedes erneute Senden braucht einen neuen Zeitstempel, eine neue Nonce und eine neue Signatur. Der Body bleibt gleich.

#Bestellung abrufen

GET/api/v1/orders/{order_id} liefert die Bestellung, ihren Status und ihre Codes.

{
  "order_id": "O-00001234",
  "external_order_id": "SHOP-20260929-10001",
  "status": "succeeded",
  "currency": "USD",
  "total_amount": "18.50",
  "created_at": "2026-09-29T08:15:30.123456Z",
  "updated_at": "2026-09-29T08:15:41.004211Z",
  "items": [
    {
      "sku_id": "S000456",
      "product_name": "Steam Wallet US",
      "quantity": 2,
      "unit_price": "9.25",
      "total_price": "18.50",
      "delivery_count": 2,
      "deliveries": [{"...": "see Codes below"}]
    }
  ],
  "...": "more fields"
}

• total_amount ist der Betrag, der bei Annahme der Bestellung abgebucht wurde.
• items[].unit_price ist der Preis, der für diese Bestellung festgeschrieben ist.
• items[].deliveries enthält die vollständigen Codes. Behandeln Sie die Antwort als geheim.
• invoice_url und delivery_file_url sind Pfade zur Rechnung und zu den Codes als CSV. Beide funktionieren nur im Portal. Mit einem API-Key liefern sie HTTP 403.
• Außerdem enthalten: id (eine alte Nummer, nicht verwenden), events (ein Verlauf nur zur Anzeige) und der Lieferfortschritt pro Position. Diese Felder können Sie ignorieren.
• Eine unbekannte Bestell-ID liefert HTTP 404.

#Bestellstatus und Codes

#Status

accepted ──► processing ──► succeeded
                  │
                  ├──► partially_succeeded   (einige Positionen geliefert, andere nicht)
                  │
                  └──► failed ──► refunded   (Geld zurück in Ihrer Wallet)

Wenn Sie keine Webhooks nutzen, fragen Sie so ab: nach 5 Sekunden, dann nach 10 s, 30 s, 60 s, danach alle 5 Minuten. Bleiben Sie dabei im Anfragelimit. Die meisten Bestellungen sind in Sekunden fertig. Manche brauchen eine manuelle Prüfung und können Stunden dauern.

#Codes

Jede gelieferte Einheit ist ein Objekt in items[].deliveries:

{
  "status": "stored",
  "delivery_type": "card_pin",
  "card_number": "X1234",
  "pin_code": "9876",
  "redeem_url": "",
  "expiry_date": "2027-09-29",
  "instructions": "Redeem at ..."
}

• Geben Sie Ihrem Kunden jedes Feld, das nicht leer ist: card_number, pin_code, redeem_url, expiry_date und instructions.
• delivery_type sagt, was Sie erhalten haben: code, card_pin, link, code_link oder qr.
• Halten Sie redeem_url geheim, genau wie einen Code.
• Löschen, verbergen oder stornieren Sie einen Code nie, nur weil expiry_date leer ist. Zeigen Sie Ihrem Kunden ein Ablaufdatum nur an, wenn es nicht leer ist.
• Geben Sie Ihrem Kunden nie eine Einheit mit dem status voided.
• Direktaufladungen haben meist keine Lieferungen. succeeded heißt dort: Das Konto wurde aufgeladen.
• Webhooks enthalten nie Codes. Rufen Sie die Bestellung ab, nachdem ein Webhook eingegangen ist.