API-Referenz

Basis-URL

Produktion

https://cryptomerchant.online/api/v1https://cryptomerchant.online/api/v1

Lokale Entwicklung

http://localhost:3000/api/v1http://localhost:3000/api/v1

Eine maschinenlesbare Beschreibung dieser API finden Sie unter /openapi.json (OpenAPI 3.1). Sie können sie in Postman oder einen Client-Generator importieren.

Authentifizierung

Senden Sie Ihren geheimen Schlüssel bei jeder Anfrage im Authorization-Header als Bearer-Token. Erstellen Sie Schlüssel im Portal unter Entwickler.

Authorization: Bearer cm_live_…

• Schlüssel beginnen im Mainnet mit cm_live_ und im Testnet mit cm_test_.
• Der vollständige Schlüssel wird nur einmal angezeigt, wenn Sie ihn erstellen. Wir speichern nur einen Hash davon, bewahren Sie ihn also sicher auf.
• Verwenden Sie Schlüssel nur auf Ihrem Server. Fügen Sie sie niemals in eine Webseite, eine mobile App oder ein öffentliches Code-Repository ein.
• Wenn ein Schlüssel offengelegt worden sein könnte, widerrufen Sie ihn im Portal und erstellen Sie einen neuen.

Fehler

Schlägt eine Anfrage fehl, hat die Antwort einen HTTP-Fehlerstatus und einen JSON-Body mit einem maschinenlesbaren code und einer menschenlesbaren message:

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTP-Status

400

Die Anfrage ist ungültig, zum Beispiel fehlt ein Feld oder ein Betrag ist zu klein.

401

Der API-Schlüssel fehlt, ist falsch oder wurde widerrufen.

403

Ihr Konto kann dies nicht tun: Es ist noch nicht live oder es ist gesperrt.

404

Das Objekt existiert nicht oder gehört zu einem anderen Unternehmen.

409

Die Rechnung kann dies in ihrem aktuellen Status nicht tun, zum Beispiel wenn eine Rechnung storniert werden soll, für die bereits eine Zahlung vorliegt.

500

Bei uns ist etwas schiefgelaufen. Versuchen Sie es etwas später erneut.

Mögliche Codes

invalid_json

Der Request-Body ist kein JSON-Objekt.

invalid_request

Ein Feld fehlt oder ist ungültig. Die Meldung nennt das Feld.

unauthorized

Der API-Schlüssel fehlt, ist falsch oder wurde widerrufen.

account_suspended

Dieses Händlerkonto ist gesperrt.

merchant_not_live

Ihr Konto ist noch nicht live. Schließen Sie zuerst die Einrichtung im Portal ab.

invalid_amount

Der Betrag fehlt, ist keine Zahl oder ist nicht größer als null.

amount_too_small

Der Betrag ist weniger als 0,50 US-Dollar wert.

invalid_asset

Die Coin-ID ist kein bekannter Coin.

asset_not_accepted

Sie akzeptieren diesen Coin nicht.

invalid_state

Die Rechnung kann dies in ihrem aktuellen Status nicht tun.

not_found

Es gibt kein Objekt mit dieser ID.

server_error

Bei uns ist etwas schiefgelaufen.

Das Rechnungsobjekt

Rechnungen haben diese Struktur in API-Antworten und in Webhooks. Beträge sind Dezimal-Strings, sodass keine Genauigkeit verloren geht.

idstring

Rechnungs-ID, beginnend mit inv_.

objectstring

Immer invoice.

statusstring

Der aktuelle Status. Siehe die Liste der Status unten.

amountstring

Der von Ihnen verlangte Preis, in currency.

currencystring

Die Währung des Preises, zum Beispiel USD.

amount_usdstring

Der Preis in US-Dollar.

descriptionstring | null

Ihre Beschreibung, die dem Kunden angezeigt wird.

order_idstring | null

Ihre eigene Bestellreferenz.

customer_emailstring | null

Die E-Mail-Adresse des Kunden, falls Sie eine angegeben haben.

metadataobject

Das Objekt, das Sie beim Erstellen der Rechnung übergeben haben, unverändert zurückgegeben.

coinobject | null

Der vom Kunden gewählte Coin oder der Coin, in dem er tatsächlich bezahlt hat, mit id, symbol und network. null, bis ein Coin gewählt ist.

requested_coinobject | null

Normalerweise null. Wenn der Kunde in einem anderen Coin oder über ein anderes Netzwerk bezahlt hat und die Zahlung angerechnet wurde, ist dies der Coin, den die Rechnung verlangt hat, mit denselben Feldern wie coin. Siehe Falscher Coin oder falsches Netzwerk.

pay_addressstring | null

Die Einzahlungsadresse für diese Rechnung. null, bis ein Coin gewählt ist.

pay_amountstring | null

Der genaue zu sendende Betrag im gewählten Coin.

network_fee_amountstring

Teil von pay_amount: die Gas-Gebühr, die der Kunde zusätzlich zum Preis bezahlt, im Coin. 0, wenn keine anfällt.

network_fee_usdstring

Dieselbe Gas-Gebühr in US-Dollar.

rate_usdstring | null

Der fixierte Preis einer Einheit des gewählten Coins in US-Dollar.

received_amountstring

Wie viel bisher eingegangen ist, im gewählten Coin.

received_usdstring

Der Wert des bisher Eingegangenen in US-Dollar.

overpaid_amountstring

Wie viel mehr bezahlt wurde, als die Rechnung verlangt hat, im gewählten Coin.

refunded_amountstring

Wie viel Sie bei dieser Zahlung mit Erstattungslinks erstattet haben, im gezahlten Coin. 0, wenn nichts.

checkout_urlstring

Die Rechnungsseite. Leiten Sie Ihren Kunden zum Bezahlen hierher.

redirect_urlstring | null

Wohin der Kunde nach dem Bezahlen gehen kann.

expires_atISO 8601

Wann die Rechnung abläuft, wenn keine Zahlung erkannt wird.

paid_atISO 8601 | null

Wann die Rechnung bezahlt wurde, oder null.

created_atISO 8601

Wann die Rechnung erstellt wurde.

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Rechnungsstatus

openOffen

Erstellt. Der Kunde hat noch keinen Coin gewählt.

awaiting_paymentZahlung ausstehend

Ein Coin ist gewählt, die Einzahlungsadresse ist zugewiesen und der Kurs ist fixiert.

confirmingWird bestätigt

Eine Zahlung wurde on-chain erkannt und wartet auf Bestätigungen.

underpaidUnterbezahlt

Bei der bestätigten Zahlung fehlt mehr als Ihre Toleranz. Der Kunde kann den Rest bezahlen oder eine Erstattung verlangen.

paidBezahlt

Bezahlt und bestätigt. Der Betrag abzüglich der Gebühr ist in Ihrem Guthaben. Eine Teilerstattung behält diesen Status bei.

expiredAbgelaufen

Die Zeit ist abgelaufen, bevor eine Zahlung erkannt wurde.

cancelledStorniert

Die Rechnung wurde storniert, bevor eine Zahlung erkannt wurde.

refundedErstattet

Dem Kunden wurde bei einer unterbezahlten Rechnung der gesendete Betrag erstattet, oder Sie haben bei einer bezahlten Rechnung alles erstattet, was Sie behalten haben.

Rechnung erstellen

POST/invoices

Erstellt eine Rechnung und gibt das Rechnungsobjekt mit Status 201 zurück. Leiten Sie Ihren Kunden zu ihrer checkout_url.

Body-Parameter

amountErforderlichnumber | string

Der Preis als Zahl oder Dezimal-String. Muss mindestens 0,50 US-Dollar wert sein.

currencyOptionalstring

Die Währung des Preises, zum Beispiel USD. Standard ist USD.

descriptionOptionalstring

Wofür der Kunde bezahlt, bis zu 300 Zeichen. Wird auf der Rechnungsseite angezeigt.

order_idOptionalstring

Ihre eigene Bestellreferenz, bis zu 120 Zeichen, um die Rechnung einer Bestellung zuzuordnen.

customer_emailOptionalstring

Die E-Mail-Adresse des Kunden. Zahlungen werden im Portal nach Kunde gruppiert.

customer_nameOptionalstring

Der Name des Kunden, bis zu 120 Zeichen.

redirect_urlOptionalstring

Eine vollständige URL, zu der der Kunde nach dem Bezahlen gehen kann.

metadataOptionalobject

Ein beliebiges JSON-Objekt bis 4 KB. Wird unverändert an der Rechnung und in Webhooks zurückgegeben.

coinOptionalstring

Wählt einen Coin anhand seiner ID vorab aus, zum Beispiel USDT.TRON. Er muss einer Ihrer akzeptierten Coins sein.

Mit einem vorausgewählten coin werden die Einzahlungsadresse sofort zugewiesen und der Kurs fixiert, sodass pay_address und pay_amount ausgefüllt sind und Sie die Zahlungsdetails in Ihrer eigenen Oberfläche anzeigen können.

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Rechnungen auflisten

GET/invoices

Gibt Ihre Rechnungen seitenweise zurück, neueste zuerst.

Query-Parameter

statusOptionalstring

Nur Rechnungen mit diesem Status, zum Beispiel paid. Muss einer der oben genannten Status sein.

limitOptionalnumber

Wie viele Rechnungen zurückgegeben werden, von 1 bis 100. Standard ist 20.

starting_afterOptionalstring

Eine Rechnungs-ID. Gibt die Rechnungen zurück, die danach kommen, für die nächste Seite.

Die Rechnungen befinden sich in data. Wenn has_more true ist, fordern Sie die nächste Seite an, indem Sie starting_after auf die ID der letzten erhaltenen Rechnung setzen.

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Rechnung abrufen

GET/invoices/{id}

Gibt eine Rechnung anhand ihrer ID zurück.

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Rechnung stornieren

POST/invoices/{id}/cancel

Storniert eine Rechnung. Das funktioniert nur, solange die Rechnung unbezahlt ist und keine Zahlung für sie erkannt wurde.

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Guthaben

GET/balances

Gibt zurück, was Ihr Unternehmen in jedem Coin hält, die Summe in US-Dollar und Ihr Gas-Guthaben.

data[].coin

Die Coin-ID, zum Beispiel USDT.TRON.

data[].symbol

Das Coin-Symbol, zum Beispiel USDT.

data[].network

Das Netzwerk, auf dem sich der Coin befindet.

data[].amount

Wie viel Sie von dem Coin halten, als Dezimal-String.

data[].usd

Sein Wert in US-Dollar zum aktuellen Kurs.

total_usd

Der Wert aller Ihrer Coins in US-Dollar.

gas_balance_usd

Ihr Gas-Guthaben in US-Dollar, mit dem Gas-Gebühren bezahlt werden.

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Akzeptierte Coins

GET/coins

Gibt die Coins zurück, die Sie derzeit akzeptieren, jeweils mit id, symbol, name, network und decimals. Verwenden Sie die id als coin, wenn Sie eine Rechnung erstellen. Zum Beispiel:

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Zahlungslink erstellen

POST/payment-links

Erstellt einen Zahlungslink und gibt ihn mit Status 201 zurück, einschließlich seiner id und seiner teilbaren url.

Body-Parameter

titleErforderlichstring

Der Name dessen, wofür der Kunde bezahlt, bis zu 120 Zeichen.

amountOptionalnumber | string

Ein fester Preis. Lassen Sie ihn weg, damit der Kunde den Betrag eingibt.

currencyOptionalstring

Die Währung des Preises. Standard ist USD.

descriptionOptionalstring

Weitere Details für den Kunden, bis zu 300 Zeichen.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Zahlungslinks auflisten

GET/payment-links

Gibt Ihre 100 neuesten Zahlungslinks in data zurück, neueste zuerst.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Das Auszahlungsobjekt

Auszahlungs-Webhooks (payout.sent und payout.failed) enthalten dieses Objekt in data. Auszahlungen eines Partneranteils aus einer Umsatzaufteilung verwenden dasselbe Objekt, wobei partner_share auf true gesetzt ist.

idstring

Auszahlungs-ID.

objectstring

Immer payout.

coinstring

Die Coin-ID, zum Beispiel USDT.TRON.

amountstring

Der ausgezahlte Betrag, in diesem Coin.

network_feestring

Die Gas-Gebühr für das Senden, in diesem Coin.

to_addressstring

Die Wallet-Adresse, an die gesendet wurde.

statusstring

queued, running, done oder failed.

tx_hashstring | null

Die Transaktions-ID auf der Blockchain, sobald gesendet wurde.

autoboolean

true, wenn die Auszahlung automatisch erfolgte und nicht von einer Person angefordert wurde.

partner_shareboolean

true, wenn diese Auszahlung ein Partneranteil aus einer Umsatzaufteilung ist, der an die Wallet des Partners gesendet wurde.

created_atISO 8601

Wann die Auszahlung erstellt wurde.

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}