ENTWICKLER

API für Kontovorgänge

Lesen Sie das Guthaben, beantragen Sie Rückerstattungen und Auszahlungen, beantworten Sie Streitfälle und verwalten Sie Webhook-Zustellungen. Signieren Sie jede Anfrage wie unter Authentifizierung beschrieben.

Basis-URLhttps://www.manuellsolutions.com/api/v3
API-Version3.0.0

Zu den Vorgängen

Umgebung

SandboxLive

Testen Sie, ohne echtes Geld zu bewegen.

Echte Zahlungen. Ein Live-Schlüssel ist erforderlich.

Guthaben

Lesen Sie Ihr verfügbares und auszahlbares Guthaben.

Das Sandbox-Guthaben ist virtuell. Sandbox-Zahlungen wechseln sofort zu available_amount, ohne ein Wertstellungsdatum abzuwarten, sodass Sie Auszahlungen gleich testen können.

Das Live-Guthaben besteht aus echten Zahlungseingängen. Eine Zahlung wartet in pending_settlement_amount bis zu ihrem Wertstellungsdatum und wechselt dann zu available_amount.

GET/api/v3/balance

Guthaben abrufen

Antwort · 200

Guthabenübersicht.

`Balance`

Feld	Typ	Erforderlich	Beschreibung
`currency_code`	`string`	Erforderlich	Konfigurierte Basiswährung der Plattform. `USDEURAEDTRY`
`available_amount`	`string`	Erforderlich	Gesamtes verfügbares Guthaben über die Link-, API- und Shop-Wallets. Ein Sandbox-Schlüssel liest stattdessen das isolierte virtuelle API-Wallet.
`pending_settlement_amount`	`string`	Erforderlich	Eingezogen, aber noch nicht gutgeschrieben (Wertstellungsdatum steht aus). Mit einem Sandbox-Schlüssel immer 0.00, da Sandbox-Zahlungen nicht auf ein Wertstellungsdatum warten.
`environment`	`string`	Erforderlich	Umgebung, zu der die Werte gehören (die Umgebung des Signaturschlüssels). `livesandbox`

Antwort · Beispiel

{
  "currency_code": "USD",
  "available_amount": "48200.00",
  "pending_settlement_amount": "250.00",
  "environment": "live"
}

Mögliche Fehler

9000026503

GET/api/v3/balance/withdrawable

Auszahlbares Guthaben abrufen

Antwort · 200

Übersicht des auszahlbaren Guthabens.

`WithdrawableBalance`

Feld	Typ	Erforderlich	Beschreibung
`currency_code`	`string`	Erforderlich	Konfigurierte Basiswährung der Plattform. `USDEURAEDTRY`
`withdrawable_amount`	`string`	Erforderlich	Gesamtes verfügbares Link-, API- und Shop-Guthaben; POST /withdrawals kann nur das API-Wallet belasten und wendet zusätzliche Prüfungen an. Ein Sandbox-Schlüssel liest das isolierte virtuelle API-Wallet.
`can_withdraw`	`boolean`	Erforderlich	Der Wert ist false, wenn ein Teilsaldo eines Wallets negativ ist.
`environment`	`string`	Erforderlich	Umgebung, zu der die Werte gehören (die Umgebung des Signaturschlüssels). `livesandbox`

Antwort · Beispiel

{
  "currency_code": "USD",
  "withdrawable_amount": "48200.00",
  "can_withdraw": true,
  "environment": "live"
}

Mögliche Fehler

9000026503

Rückerstattungen

Fordern Sie eine Rückerstattung oder Stornierung an und verfolgen Sie sie.

In Live gilt: HTTP 202 bedeutet, dass die Anfrage entgegengenommen wurde, nicht dass die Rückerstattung abgeschlossen ist. Verfolgen Sie das Ergebnis über die Status-Endpunkte: requested, dann awaiting_provider_manual, dann completed; oder rejected / cancelled.

In der Sandbox wird eine Anfrage sofort abgeschlossen (standardmäßig completed). Senden Sie X-CAV-Sandbox-Scenario: rejected, um eine abgelehnte Rückerstattung zu testen.

Live-Anfragen werden geprüft. Verfolgen Sie die Rückabwicklung bis completed, rejected oder cancelled. Nur ein abgeschlossener refund sendet payment.refunded; einen void verfolgen Sie mit GET.

POST/api/v3/refundsIdempotency-Key erforderlich

Rückerstattung oder Stornierung beantragen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`X-CAV-Sandbox-Scenario`	`string · header`	Optional	Nur für Sandbox-Schlüssel. Wählt das simulierte Ergebnis: `completed` (Standard) oder `rejected` (ohne Wirkung auf das virtuelle Wallet). Ein Live-Schlüssel, der diesen Header sendet, oder ein beliebiger Schlüssel, der einen anderen Wert sendet, erhält 422 `1000001`. Der Header ist nicht Teil der signierten Zeichenkette, aber Teil des Fingerabdrucks des Idempotency-Key; die Wiederverwendung eines Schlüssels mit einem anderen Szenario liefert daher 9000010. Das angewendete Szenario wird im gleichnamigen Antwort-Header zurückgegeben. `completedrejected`

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`payment_code`	`string`	Erforderlich	Code der erfolgreich bezahlten Zahlung, die rückabgewickelt werden soll. `maxLength 16`
`operation_type`	`string`	Erforderlich	`refund` erstattet eine endgültig verbuchte Zahlung; `void` storniert eine Kartenzahlung, die noch nicht endgültig verbucht ist. Beide eröffnen eine Rückabwicklungsanfrage (Status `requested`). Ein Operator prüft sie; nach der Genehmigung wird der Betrag auf Ihrem Guthaben reserviert und der Status lautet `awaiting_provider_manual`, bis die Rückerstattungsreferenz des Anbieters erfasst ist (`completed`); andernfalls endet die Anfrage mit `rejected` oder `cancelled` (die Reservierung wird aufgehoben). Dieser Endpunkt ruft den Anbieter nicht auf. `refundvoid`
`reason`	`string`	Erforderlich	Grund für die Rückabwicklung. `minLength 3maxLength 500`

Anfrage-Body · Beispiel

{
  "payment_code": "ab34cdef",
  "operation_type": "refund",
  "reason": "Customer cancelled the order."
}

Antwort · 202

Rückabwicklung angefordert. Sie wird geprüft und von Hand an den Anbieter übermittelt. Mit einem Sandbox-Schlüssel wird das simulierte Ergebnis zurückgegeben (environment sandbox); auch eine idempotente Wiederholung liefert 202.

`Reversal`

Feld	Typ	Erforderlich	Beschreibung
`id`	`string`	Erforderlich	Kennung der Rückabwicklungsanfrage (UUID).
`operation`	`string`	Erforderlich	Art des Vorgangs. `refundvoid`
`status`	`string`	Erforderlich	Lebenszyklus der Rückabwicklung: `requested` (wartet auf einen Operator) → `awaiting_provider_manual` (genehmigt; der Betrag wird reserviert, bis die Rückerstattungsreferenz des Anbieters erfasst ist) → `completed`, oder `rejected` / `cancelled` (die Reservierung wird aufgehoben). `processing` und `failed` sind reservierte Werte, die derzeit für Zahlungsrückabwicklungen nicht verwendet werden. Mit einem Sandbox-Schlüssel steht der Status sofort fest: `completed` (Standard) oder `rejected`. `requestedprocessingcompletedrejectedfailedawaiting_provider_manualcancelled`
`amount`	`string`	Erforderlich	Vollständiger Betrag der rückabgewickelten Zahlung in der Währung der Zahlung selbst (derselbe Betrag und dieselbe Währung wie bei der Zahlung und ihrem Webhook `payment.refunded`), als Dezimalzeichenkette mit 2 Nachkommastellen. Der Status requested bedeutet nicht, dass Geld bewegt wurde.
`currency`	`string`	Erforderlich	Währung von `amount`: der `currency_code` der rückabgewickelten Zahlung.
`reason`	`string`	Erforderlich	Von Ihnen angegebener Grund.
`provider_reference`	`string \| null`	Erforderlich	Rückerstattungsreferenz des Anbieters, die eingetragen wird, sobald die Rückerstattung über das echte POS abgeschlossen ist. In der Sandbox wird beim Abschluss der simulierten Rückabwicklung eine synthetische Referenz mit dem Präfix `SBX-` zurückgegeben; sie ist kein Datensatz des Anbieters.
`provider_refunded_at`	`string · date-time \| null`	Erforderlich	Zeitpunkt, zu dem die Rückerstattung des Anbieters erfasst wurde (UTC). Bis zum manuellen Abschluss null.
`created_at`	`string · date-time`	Erforderlich	Zeitpunkt der Anfrage (UTC).
`updated_at`	`string · date-time \| null`	Erforderlich	Letzte Statusänderung (UTC).
`payment_code`	`string \| null`	Erforderlich	Code der Zahlung, zu der diese Rückabwicklung gehört (der beim Erstellen der Zahlung zurückgegebene `code`).
`environment`	`string`	Erforderlich	Umgebung der Rückabwicklung (die Umgebung des Signaturschlüssels). `livesandbox`

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Mögliche Fehler

GET/api/v3/refunds

Rückerstattungen auflisten

Parameter

Feld	Typ	Erforderlich	Beschreibung
`page`	`integer · query`	Optional	Seitennummer. `minimum 1`
`per_page`	`integer · query`	Optional	Einträge pro Seite. `minimum 1maximum 100`
`status`	`string · query`	Optional	Nach Status filtern. `requestedprocessingawaiting_provider_manualcompletedrejectedfailedcancelled`
`operation_type`	`string · query`	Optional	Nach Vorgang filtern. `refundvoid`

Antwort · 200

Paginierte Rückerstattungen.

Feld	Typ	Beschreibung
`data`	`Reversal[]`
`meta`	`PaginationMeta`

Antwort · Beispiel

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "operation": "refund",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "reason": "Customer cancelled the order.",
      "provider_reference": "string",
      "provider_refunded_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "updated_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Mögliche Fehler

GET/api/v3/refunds/{id}

Status einer Rückerstattung abrufen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID der Rückabwicklung.

Antwort · 200

Die Rückabwicklung.

Objekt: Reversal (Felder siehe Rückerstattung oder Stornierung beantragen).

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Mögliche Fehler

Benachrichtigung

Wird eine Rückerstattung abgeschlossen, geht eine signierte Benachrichtigung payment.refunded an die Webhook-URL der Zahlung. Header, Signatur und Wiederholungen entsprechen den Webhooks. Ein void sendet keine Benachrichtigung.

POSTpayment.refunded

Signierte Benachrichtigung payment.refunded an die Händler-URL

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`event_id`	`string · uuid`	Erforderlich
`event_type`	`string`	Erforderlich	`payment.refunded`
`environment`	`string`	Erforderlich	`sandboxlive`
`occurred_at`	`string · date-time`	Erforderlich
`refund`	`object`	Erforderlich
`refund.public_id`	`string · uuid`	Erforderlich
`refund.status`	`string`	Erforderlich	`completed`
`refund.amount`	`string`	Erforderlich	Positiver Betrag als Dezimalzeichenkette mit fester Skala und 2 Nachkommastellen. "0.00" wird nicht akzeptiert.
`refund.currency_code`	`string`	Erforderlich	Fiat-Währungscode, beschränkt auf die vier unterstützten Währungen. `USDEURAEDTRY`
`refund.completed_at`	`string · date-time`	Erforderlich	Derselbe Zeitpunkt wie `occurred_at`.
`payment`	`object`	Erforderlich
`payment.public_id`	`string · uuid`	Erforderlich
`payment.code`	`string`	Erforderlich	`minLength 1maxLength 16`
`payment.merchant_reference`	`string \| null`	Erforderlich	`maxLength 64`
`order`	`object`	Erforderlich
`order.public_id`	`string · uuid`	Erforderlich

Anfrage-Body · Beispiel

{
  "event_id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "event_type": "payment.refunded",
  "environment": "sandbox",
  "occurred_at": "2026-09-28T12:00:00.000Z",
  "refund": {
    "public_id": "A1B2C3D4-E5F6-4789-8ABC-DEF012345678",
    "status": "completed",
    "amount": "100.00",
    "currency_code": "USD",
    "completed_at": "2026-09-28T12:00:00.000Z"
  },
  "payment": {
    "public_id": "11111111-2222-4333-8444-555555555555",
    "code": "ab34cdef",
    "merchant_reference": "SIP-2026-0001"
  },
  "order": {
    "public_id": "66666666-7777-4888-8999-AAAAAAAAAAAA"
  }
}

Auszahlungen

Fordern Sie eine USDT-Auszahlung (TRC20) an und verfolgen Sie sie.

In Live gilt: HTTP 201 bedeutet, dass die Anfrage angenommen und der Betrag reserviert wurde, nicht dass die USDT gesendet wurden. Prüfen Sie status und tx_hash und kontrollieren Sie die Adresse doppelt: Eine Überweisung auf der Chain lässt sich nicht rückgängig machen.

Eine Sandbox-Auszahlung belastet das virtuelle Guthaben und sendet nie etwas auf die Chain. Es gelten dieselben Regeln wie in der Live-Umgebung, einschließlich Mindestbetrag, Tageslimit und Umrechnungskurs. Senden Sie X-CAV-Sandbox-Scenario: rejected, um eine Ablehnung zu testen. Die Sandbox akzeptiert die TRON-Nulladresse als Ziel; die Live-Umgebung lehnt Burn-Adressen mit 1000030 ab.

Mindestbetrag und Tageslimit werden von Manuell pro Konto festgelegt; unterhalb des Mindestbetrags liefert die API 9000019, oberhalb des Limits 9000021. In der Live-Umgebung sendet ein Operator von Manuell die USDT und trägt tx_hash ein (sent) oder lehnt die Anfrage mit einer Begründung ab (rejected); der Betrag geht dann an Ihr Guthaben zurück.

POST/api/v3/withdrawalsIdempotency-Key erforderlich

USDT-Auszahlung beantragen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`X-CAV-Sandbox-Scenario`	`string · header`	Optional	Nur für Sandbox-Schlüssel. Wählt das simulierte Ergebnis: `sent` (Standard) oder `rejected` (ohne Wirkung auf das virtuelle Wallet). Ein Live-Schlüssel, der diesen Header sendet, oder ein beliebiger Schlüssel, der einen anderen Wert sendet, erhält 422 `1000001`. Der Header ist nicht Teil der signierten Zeichenkette, aber Teil des Fingerabdrucks des Idempotency-Key; die Wiederverwendung eines Schlüssels mit einem anderen Szenario liefert daher 9000010. Das angewendete Szenario wird im gleichnamigen Antwort-Header zurückgegeben. `sentrejected`

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`amount`	`string`	Erforderlich	Aus dem API-Wallet zu reservierender Betrag in der konfigurierten Basiswährung der Plattform, als Dezimalzeichenkette mit 2 Nachkommastellen. Mindestbetrag und Tageslimit legt der Plattformbetreiber pro Konto fest: Ein Betrag unter dem Mindestbetrag liefert 9000019, ein Betrag über dem Tageslimit 9000021. Ihre Limits erfahren Sie bei Ihrem Account-Manager.
`address`	`string`	Erforderlich	Ihre eigene, geprüfte TRON-Adresse für eine USDT-TRC20-Auszahlung. Das Beispiel ist ein Platzhalter und wird unverändert abgelehnt. `maxLength 64`
`address_acknowledged`	`boolean`	Erforderlich	Muss true sein – Sie bestätigen, dass die Zieladresse korrekt ist und die Überweisung nicht rückgängig gemacht werden kann.

Anfrage-Body · Beispiel

{
  "amount": "250.00",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "address_acknowledged": true
}

Antwort · 201

Auszahlung angefordert. Das Guthaben wird reserviert; der On-Chain-Versand erfolgt von Hand. Mit einem Sandbox-Schlüssel wird das simulierte Ergebnis zurückgegeben (environment sandbox); auch eine idempotente Wiederholung liefert 201.

`Withdrawal`

Feld	Typ	Erforderlich	Beschreibung
`id`	`string`	Erforderlich	Kennung der Auszahlungsanfrage (UUID).
`status`	`string`	Erforderlich	Lebenszyklusstatus der Auszahlung: `requested` → `sent` oder `rejected`. Den On-Chain-Versand führt der Plattformbetreiber von Hand durch. Mit einem Sandbox-Schlüssel steht der Status sofort fest: `sent` (Standard) oder `rejected`. `requestedsentrejected`
`amount`	`string`	Erforderlich	Angeforderter und aus dem API-Wallet reservierter Betrag in der Basiswährung der Plattform, als Dezimalzeichenkette mit 2 Nachkommastellen; es ist kein USDT-Betrag.
`currency`	`string`	Erforderlich	Basiswährung, in der der Betrag angegeben ist.
`asset`	`string`	Erforderlich	Auszahlungs-Asset (USDT).
`network`	`string`	Erforderlich	Auszahlungsnetzwerk (TRC20).
`address`	`string`	Erforderlich	Von Ihnen angegebene Zieladresse.
`usdt_amount`	`string`	Erforderlich	Beim Annehmen der Anfrage berechneter USDT-Betrag als Dezimalzeichenkette mit fester Skala und 6 Nachkommastellen. Dieses Feld allein bestätigt keine Überweisung auf der Chain.
`tx_hash`	`string \| null`	Erforderlich	On-Chain-Transaktions-Hash, der nach dem Versand eingetragen wird. In der Sandbox wird für eine Auszahlung mit `sent` ein synthetischer 64-stelliger Hash zurückgegeben; es findet keine Überweisung auf der Chain statt.
`rejection_reason`	`string \| null`	Erforderlich	Begründung, die bei Ablehnung eingetragen wird. In der Sandbox enthält eine abgelehnte Auszahlung `Sandbox scenario: rejected`.
`requested_at`	`string · date-time`	Erforderlich	Zeitpunkt der Anfrage (UTC).
`processed_at`	`string · date-time \| null`	Erforderlich	Zeitpunkt des Versands oder der Ablehnung (UTC).
`created_at`	`string · date-time`	Erforderlich	Erstellungszeitpunkt des Datensatzes (UTC).
`environment`	`string`	Erforderlich	Umgebung der Auszahlung (die Umgebung des Signaturschlüssels). `livesandbox`

Antwort · Beispiel

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

Mögliche Fehler

GET/api/v3/withdrawals

Auszahlungen auflisten

Parameter

Feld	Typ	Erforderlich	Beschreibung
`page`	`integer · query`	Optional	Seitennummer. `minimum 1`
`per_page`	`integer · query`	Optional	Einträge pro Seite. `minimum 1maximum 100`
`status`	`string · query`	Optional	Nach Status filtern. `requestedsentrejected`

Antwort · 200

Paginierte Auszahlungen.

Feld	Typ	Beschreibung
`data`	`Withdrawal[]`
`meta`	`PaginationMeta`

Antwort · Beispiel

{
  "data": [
    {
      "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "asset": "USDT",
      "network": "TRC20",
      "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
      "usdt_amount": "249.000000",
      "tx_hash": null,
      "rejection_reason": null,
      "requested_at": "2026-09-26T09:30:00.000Z",
      "processed_at": null,
      "created_at": "2026-09-26T09:30:00.000Z",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Mögliche Fehler

GET/api/v3/withdrawals/{id}

Status einer Auszahlung abrufen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID der Auszahlung.

Antwort · 200

Die Auszahlung.

Objekt: Withdrawal (Felder siehe USDT-Auszahlung beantragen).

Antwort · Beispiel

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

Mögliche Fehler

Rückbuchungen

Listen Sie Rückbuchungen auf und reichen Sie Ihre Nachweise ein.

Streitfälle kommen von den Kartennetzwerken, daher legen Sie in der Sandbox selbst einen Test-Streitfall mit POST /api/v3/sandbox/disputes an. Siehe Kontovorgänge testen.

Manuell erfasst einen Streitfall, sobald die Bank ihn meldet. Der strittige Betrag wird von Ihrem Guthaben abgezogen (das Guthaben kann negativ werden, und can_withdraw wird false) und wieder gutgeschrieben, wenn Sie gewinnen. Senden Sie Ihre Nachweise vor evidence_due_at; ein neuer Idempotency-Key ersetzt Ihre frühere Notiz, solange der Streitfall offen ist.

GET/api/v3/disputes

Streitfälle auflisten

Parameter

Feld	Typ	Erforderlich	Beschreibung
`page`	`integer · query`	Optional	Seitennummer. `minimum 1`
`per_page`	`integer · query`	Optional	Einträge pro Seite. `minimum 1maximum 100`
`status`	`string · query`	Optional	Nach Status filtern. `openunder_reviewwonlost`

Antwort · 200

Paginierte Streitfälle.

Feld	Typ	Beschreibung
`data`	`Dispute[]`
`meta`	`PaginationMeta`

`Dispute`

Feld	Typ	Erforderlich	Beschreibung
`id`	`string`	Erforderlich	Kennung des Streitfalls (UUID).
`service`	`string`	Erforderlich	Dienst, zu dem die strittige Zahlung gehört: `api` für eine über diese API erstellte Zahlung, `link` für einen Zahlungslink.
`amount`	`string`	Erforderlich	Strittiger Betrag (Dezimalzeichenkette).
`currency`	`string`	Erforderlich	Währung des Streitfalls.
`status`	`string`	Erforderlich	Status des Streitfalls. `openunder_reviewwonlost`
`reason`	`string`	Erforderlich	Kategorie des Streitfallgrunds. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`
`reason_note`	`string \| null`	Erforderlich	Begründung der Bank, wörtlich übernommen.
`occurred_on`	`string · date`	Erforderlich	Datum, an dem der Streitfall eröffnet wurde (YYYY-MM-DD).
`evidence_due_at`	`string · date-time \| null`	Erforderlich	Frist für die Einreichung von Nachweisen (UTC). Ein Sandbox-Streitfall bleibt nach der Erstellung 7 Tage lang für Nachweise offen.
`evidence_submitted_at`	`string · date-time \| null`	Erforderlich	Zeitpunkt, zu dem die Plattform die Verteidigung bei der Bank eingereicht hat.
`merchant_evidence_note`	`string \| null`	Erforderlich	Die von Ihnen eingereichte Notiz.
`merchant_evidence_submitted_at`	`string · date-time \| null`	Erforderlich	Zeitpunkt, zu dem Sie Ihre Notiz eingereicht haben.
`resolved_at`	`string · date-time \| null`	Erforderlich	Zeitpunkt des Abschlusses des Streitfalls.
`created_at`	`string · date-time`	Erforderlich	Erstellungszeitpunkt des Datensatzes (UTC).
`payment_code`	`string \| null`	Erforderlich	Code der API-Zahlung, zu der der Streitfall gehört (der beim Erstellen der Zahlung zurückgegebene `code`); null, wenn der Streitfall keiner API-Zahlung zugeordnet ist.
`environment`	`string`	Erforderlich	Umgebung des Streitfalls (die Umgebung des Signaturschlüssels). `livesandbox`

Antwort · Beispiel

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "service": "api",
      "amount": "250.00",
      "currency": "USD",
      "status": "open",
      "reason": "fraud",
      "reason_note": "string",
      "occurred_on": "2026-09-26",
      "evidence_due_at": "2026-09-26T09:00:00.000Z",
      "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "merchant_evidence_note": "string",
      "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "resolved_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Mögliche Fehler

GET/api/v3/disputes/{id}

Streitfall abrufen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID des Streitfalls.

Antwort · 200

Der Streitfall.

Objekt: Dispute (Felder siehe Streitfälle auflisten).

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Mögliche Fehler

POST/api/v3/disputes/{id}/evidenceIdempotency-Key erforderlich

Nachweis zum Streitfall einreichen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID des Streitfalls.

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`note`	`string`	Erforderlich	Ihr Nachweistext zum Streitfall. `minLength 3maxLength 4000`

Anfrage-Body · Beispiel

{
  "note": "Order 4821 was delivered on 2026-09-25. Carrier reference ABC123."
}

Antwort · 200

Nachweis erfasst; der Status des Streitfalls ändert sich nicht. Eine identische idempotente Wiederholung liefert den ursprünglichen Antwort-Body.

Objekt: Dispute (Felder siehe Streitfälle auflisten).

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Mögliche Fehler

Zustellungen verwalten

Prüfen Sie Webhook-Zustellungen und wiederholen Sie fehlgeschlagene.

Die Adresse für Benachrichtigungen wird je Umgebung unter “API-Schlüssel und Integration” festgelegt. Die folgenden Endpunkte listen Zustellungen auf und reihen fehlgeschlagene erneut ein.

GET/api/v3/webhooks/deliveries

Webhook-Zustellungen auflisten

Parameter

Feld	Typ	Erforderlich	Beschreibung
`page`	`integer · query`	Optional	Seitennummer. `minimum 1`
`per_page`	`integer · query`	Optional	Einträge pro Seite. `minimum 1maximum 100`
`status`	`string · query`	Optional	Nach Status filtern. `pendingdeliveredfailed`

Antwort · 200

Paginierte Zustellungen.

Feld	Typ	Beschreibung
`data`	`WebhookDelivery[]`
`meta`	`PaginationMeta`

`WebhookDelivery`

Feld	Typ	Beschreibung
`id`	`string`	Kennung der Zustellung (UUID).
`event`	`string`	Ereignistyp der Zustellung: `payment.paid`, `payment.refunded` oder `payment.failed`. Ein fehlgeschlagener Versuch ist nicht endgültig; die Zahlung bleibt created und kann später bezahlt werden.
`status`	`string`	Status der Zustellung. `pendingdeliveredfailed`
`payment_code`	`string \| null`	Zugehöriger Zahlungscode, falls vorhanden.
`attempt_count`	`integer`	Bisherige Anzahl der Zustellversuche.
`last_status_code`	`integer \| null`	HTTP-Status des letzten Versuchs.
`last_error`	`string \| null`	Legacy-Rohfehler der Zustellung; verwenden Sie last_error_code und last_error_message.
`last_error_code`	`string \| null`	Stabiler maschinenlesbarer Fehlercode für die Zustellung. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	Kurze lesbare Fehlermeldung zur Zustellung, ausgewählt über Accept-Language.
`next_attempt_at`	`string · date-time \| null`	Zeitpunkt des nächsten geplanten Wiederholungsversuchs (UTC).
`delivered_at`	`string · date-time \| null`	Zeitpunkt der Zustellung (UTC).
`created_at`	`string · date-time`	Erstellungszeitpunkt des Datensatzes (UTC).

Antwort · Beispiel

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "event": "payment.paid",
      "status": "pending",
      "payment_code": null,
      "attempt_count": 1,
      "last_status_code": null,
      "last_error": null,
      "last_error_code": null,
      "last_error_message": null,
      "next_attempt_at": null,
      "delivered_at": null,
      "created_at": "2026-09-26T09:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Mögliche Fehler

1000001422

GET/api/v3/webhooks/deliveries/{id}

Webhook-Zustellung abrufen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID der Zustellung.

Antwort · 200

Die Zustellung, einschließlich URL und Payload.

`WebhookDeliveryDetail`

Feld	Typ	Beschreibung
`id`	`string`	Kennung der Zustellung (UUID).
`event`	`string`	Ereignistyp der Zustellung: `payment.paid`, `payment.refunded` oder `payment.failed`. Ein fehlgeschlagener Versuch ist nicht endgültig; die Zahlung bleibt created und kann später bezahlt werden.
`status`	`string`	Status der Zustellung. `pendingdeliveredfailed`
`payment_code`	`string \| null`	Zugehöriger Zahlungscode, falls vorhanden.
`attempt_count`	`integer`	Bisherige Anzahl der Zustellversuche.
`last_status_code`	`integer \| null`	HTTP-Status des letzten Versuchs.
`last_error`	`string \| null`	Legacy-Rohfehler der Zustellung; verwenden Sie last_error_code und last_error_message.
`last_error_code`	`string \| null`	Stabiler maschinenlesbarer Fehlercode für die Zustellung. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	Kurze lesbare Fehlermeldung zur Zustellung, ausgewählt über Accept-Language.
`next_attempt_at`	`string · date-time \| null`	Zeitpunkt des nächsten geplanten Wiederholungsversuchs (UTC).
`delivered_at`	`string · date-time \| null`	Zeitpunkt der Zustellung (UTC).
`created_at`	`string · date-time`	Erstellungszeitpunkt des Datensatzes (UTC).
`url`	`string`	Ihre Webhook-URL für diese Zustellung.
`payload`	`object \| null`	Der gesendete JSON-Body.

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

Mögliche Fehler

9000024404

POST/api/v3/webhooks/deliveries/{id}/retryIdempotency-Key erforderlich

Fehlgeschlagene Zustellung erneut versuchen

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	`string · uuid · path`	Erforderlich	Die ID der Zustellung.

Antwort · 200

Fehlgeschlagene Zustellung erneut eingereiht. Eine identische idempotente Wiederholung liefert die ursprüngliche Antwort zur Einreihung, ohne einen weiteren Versuch auszulösen.

Objekt: WebhookDeliveryDetail (Felder siehe Webhook-Zustellung abrufen).

Antwort · Beispiel

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

Mögliche Fehler

Zustellfehler

last_error ist ein Legacy-Feld; verwenden Sie in neuen Integrationen last_error_code.

Feld	Beschreibung
`invalid_webhook_target`	Das Webhook-Ziel ist ungültig.
`webhook_target_private_network`	Das Webhook-Ziel wird zu einem privaten Netzwerk aufgelöst.
`webhook_environment_invalid`	Die Webhook-Umgebung ist ungültig.
`webhook_signing_unavailable`	Das Webhook konnte nicht signiert werden.
`webhook_response_unsuccessful`	Das Ziel hat keine 2xx-Antwort gegeben.
`webhook_egress_proxy_unreachable`	Der Ausgangs-Proxy für die Zustellung ist nicht erreichbar.
`webhook_unreachable`	Das Webhook-Ziel ist nicht erreichbar.
`webhook_delivery_failed`	Die Webhook-Zustellung ist fehlgeschlagen.

Dienststatus und Wartung

Einzelne Dienste können vorübergehend in Wartung genommen werden. Betroffen sind nur neue Vorgänge; dieser Abschnitt zeigt, was stoppt, was weiterläuft und wie Sie den Status abfragen.

GET/api/v3/service-statusÖffentlich

Dienststatus abrufen

Antwort · 200

Dienste in Wartung (die Liste kann leer sein).

Feld	Typ	Erforderlich	Beschreibung
`data`	`ServiceStatusItem[]`	Erforderlich	Dienste, die sich gerade in Wartung befinden; eine leere Liste bedeutet, dass keiner betroffen ist.

`ServiceStatusItem`

Feld	Typ	Erforderlich	Beschreibung
`service`	`string`	Erforderlich	Dienstcode: `api_collection` (über die API erstellte Zahlungen und deren Zahlungsseiten), `withdrawals` (Auszahlungsanfragen) oder einer der Werte `link_collection`, `storefront`, `usdt_sales` und `balance_load` (weitere Dienste der Plattform). `api_collectionlink_collectionwithdrawalsstorefrontusdt_salesbalance_load`
`until`	`string · date-time \| null`	Erforderlich	Voraussichtlicher Zeitpunkt der Rückkehr (UTC, ISO-8601) oder null. Es ist nur eine Schätzung: Die Wartung endet nicht von selbst, und nach Ablauf dieses Zeitpunkts ist das Feld null.
`note`	`string \| null`	Erforderlich	Kurze Klartextnachricht des Plattformbetreibers oder null. `maxLength 240`

Antwort · Beispiel

{
  "data": [
    {
      "service": "api_collection",
      "until": "2026-10-01T12:00:00Z",
      "note": "Planned maintenance."
    }
  ]
}

Weitere Antworten

429Anfragelimit überschritten.

Mögliche Fehler

1000005429

Paginierung

Listen-Endpunkte akzeptieren page (Standard 1) und per_page (Standard 20, maximal 100) und liefern data und meta.

`PaginationMeta`

Feld	Typ	Erforderlich	Beschreibung
`page`	`integer`	Erforderlich	Seitennummer, beginnend bei 1.
`per_page`	`integer`	Erforderlich	Einträge pro Seite (1–100).
`total`	`integer`	Erforderlich	Gesamtzahl der passenden Datensätze.
`total_pages`	`integer`	Erforderlich	ceil(total / per_page).

Kontovorgänge testen

Guthaben, Rückerstattungen, Auszahlungen und Streitfälle funktionieren in der Sandbox mit denselben Endpunkten, Bodys und Fehlercodes wie live.

Sandbox-Zahlungen wechseln sofort zu available_amount, ohne ein Wertstellungsdatum abzuwarten.
Rückerstattungs- und Auszahlungsanfragen werden sofort abgeschlossen. Der Header X-CAV-Sandbox-Scenario wählt das Ergebnis.
Streitfälle kommen von der Bank, daher legen Sie in der Sandbox einen mit POST /api/v3/sandbox/disputes an.

Prüfen Sie Tests zu Rückerstattungen, Auszahlungen und Streitfällen unter “Sandbox-Vorgänge”.

Ergebnis wählen

Rückerstattungs- und Auszahlungsanfragen verwenden dieselben Endpunkte und Bodys wie in der Live-Umgebung. Um das Ergebnis zu wählen, fügen Sie den optionalen Header X-CAV-Sandbox-Scenario hinzu. Er ist nicht Teil der Signatur. Mit einem Live-Schlüssel wird der Header mit 422 (1000001) abgelehnt, damit aus einem Test nie eine echte Anfrage werden kann.

X-CAV-Sandbox-Scenario

X-CAV-Sandbox-Scenario: rejected

Endpunkt	Header-Werte	Standard	Wirkung
`POST /api/v3/refunds`	`completed` `rejected`	`completed`	`completed` schließt die Rückerstattung ab und belastet das virtuelle Guthaben; `rejected` erfasst die Ablehnung und ändert nichts.
`POST /api/v3/withdrawals`	`sent` `rejected`	`sent`	`sent` belastet das virtuelle Guthaben und füllt `tx_hash` mit einem Platzhalterwert; `rejected` gibt den Betrag frei.
`POST /api/v3/sandbox/disputes`	`open` `won` `lost`	`open`	Wird im Request-Body angegeben, nicht in einem Header. `open`, `won` oder `lost`.

Test-Streitfall

Streitfälle kommen von den Kartenorganisationen und können live nicht von Ihrer Seite ausgelöst werden. Dies ist der einzige reine Sandbox-Endpunkt: Er erstellt einen Test-Streitfall für eine bezahlte Sandbox-Zahlung und gibt dasselbe Dispute-Objekt zurück wie die Live-Umgebung.

POST/api/v3/sandbox/disputesIdempotency-Key erforderlich

Sandbox-Streitfall für eine bezahlte Sandbox-Zahlung erstellen

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`payment_code`	`string`	Erforderlich	Ersetzen Sie dies durch den Code einer bezahlten Zahlung, die Sie mit Ihrem eigenen Sandbox-Schlüssel erstellt haben. `maxLength 16`
`scenario`	`string`	Optional	Zu erfassendes Ergebnis: `open` (Standard) bleibt für Nachweise offen; `won` und `lost` sind bereits abgeschlossen. `openwonlost`
`reason`	`string`	Erforderlich	Kategorie des Streitfallgrunds; dieselben Werte wie `Dispute.reason`. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`

Anfrage-Body · Beispiel

{
  "payment_code": "ab34cdef",
  "scenario": "open",
  "reason": "fraud"
}

Antwort · 201

Streitfall erfasst; eine idempotente Wiederholung liefert denselben Streitfall.

Objekt: Dispute (Felder siehe Streitfälle auflisten).

Antwort · Beispiel

{
  "id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": null,
  "occurred_on": "2026-09-30",
  "evidence_due_at": "2026-10-07T09:00:00.000Z",
  "evidence_submitted_at": null,
  "merchant_evidence_note": null,
  "merchant_evidence_submitted_at": null,
  "resolved_at": null,
  "created_at": "2026-09-30T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "sandbox"
}