FivoDocs
Docs/API-Integration

API-Integration

Erstellen Sie individuelle Zahlungsabläufe und Backend-Integrationen.

Übersicht

Während das Widget der einfachste Weg ist, Zahlungen zu akzeptieren, gibt Ihnen die Fivo API volle Kontrolle für individuelle Integrationen. Nutzen Sie die API, um:

  • Individuelle Zahlungserlebnisse zu erstellen
  • Zahlungshistorie programmatisch abzufragen
  • In Ihre bestehenden Backend-Systeme zu integrieren
  • Zahlungen serverseitig zu erstellen

Checkout Sessions

Checkout Sessions sind die empfohlene Methode, um Zahlungen über eine serverseitige Integration zu akzeptieren. Ihr Server erstellt eine Sitzung, leitet den Kunden auf eine von Fivo gehostete Zahlungsseite weiter und überprüft die Zahlung, wenn der Kunde zurückkehrt.

Wann welche Methode verwenden

Widget einbetten

Feste Produkte, Spenden, statische Seiten

Backend: Nein

Widget + data-amount-from

Warenkörbe, dynamische Beträge

Backend: Nein

Direkter Link

E-Mails, Social Media, QR-Codes

Backend: Nein

Checkout Sessions

E-Commerce, SaaS, Auftragsabwicklung

Backend: Ja (API Key)

Vollständiges Beispiel (Node.js / Express)

server.js
const express = require('express');
const app = express();

const FIVO_API = 'https://api.fivo.finance';
const FIVO_API_KEY = process.env.FIVO_API_KEY;

// 1. Customer clicks "Pay": create a session and redirect
app.post('/checkout', async (req, res) => {
  const response = await fetch(FIVO_API + '/checkout/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': FIVO_API_KEY,
    },
    body: JSON.stringify({
      amount: req.body.amount,
      currency: 'USDC',
      // Fivo appends ?session_id=cs_live_... automatically
      return_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel',
      metadata: { order_id: req.body.orderId },
    }),
  });

  const { data } = await response.json();
  res.redirect(303, data.url);
});

// 2. Customer returns after payment: verify and fulfill
app.get('/success', async (req, res) => {
  const response = await fetch(
    FIVO_API + '/checkout/sessions/' + req.query.session_id,
    { headers: { 'X-API-Key': FIVO_API_KEY } }
  );
  const { data } = await response.json();

  if (data.status === 'complete' && data.payment) {
    // Fulfill the order
    res.send('Payment confirmed! TX: ' + data.payment.tx_hash);
  } else {
    res.send('Payment pending. Status: ' + data.status);
  }
});

app.listen(3000);

cURL-Beispiel

Create a Checkout Session
curl -X POST https://api.fivo.finance/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fivo_live_abc123..." \
  -d '{
    "amount": "49.99",
    "currency": "USDC",
    "return_url": "https://yoursite.com/success",
    "metadata": { "order_id": "order_123" }
  }'
i

Vollständige Referenz

Siehe die für alle Parameter, Antwortschemas und Sitzungsstatuswerte.API-Referenz

Basis-URL

https://api.fivo.finance
i

Produktions-API

Dies ist der Produktions-API-Endpunkt. Alle Anfragen werden im Mainnet verarbeitet. Wir werden alle Händler vor etwaigen Breaking Changes benachrichtigen.

Authentifizierung

Die Fivo API verwendet zwei Authentifizierungsmethoden:

JWT-Token

Für Dashboard- und Benutzersitzungen. Wird nach dem Login erhalten. Läuft nach 15 Minuten ab.

Authorization: Bearer <token>

API Keys

Für Server-zu-Server-Integrationen. Im Dashboard erstellt. Laufen nicht ab, können aber widerrufen werden.

X-API-Key: <api_key>

Einen API Key erstellen

  1. Melden Sie sich in Ihrem anFivo Dashboard
  2. Navigieren Sie zu API Keys
  3. Klicken Sie auf Neuen Key erstellen
  4. Geben Sie Ihrem Key einen beschreibenden Namen (z.B. "Produktionsserver")
  5. Kopieren Sie den Key sofort – er wird nicht erneut angezeigt!
!

Halten Sie Ihre Keys geheim

Geben Sie API Keys niemals in clientseitigem Code preis. API Keys sollten nur in serverseitigen Anwendungen verwendet werden, wo sie geheim gehalten werden können.

Beispiel: Zahlungsstatus prüfen

Nachdem ein Kunde über das Widget bezahlt hat, können Sie den Zahlungsstatus überprüfen:

Check Payment Status
// Using fetch (Node.js/Browser): public endpoint, no auth required
const response = await fetch(
  `https://api.fivo.finance/payments/abc123-payment-id/status`
);

const data = await response.json();
console.log(data);

// Response (minimal data for security):
{
  "success": true,
  "data": {
    "id": "abc123-payment-id",
    "status": "completed",
    "is_cross_chain": false,
    "cctp_attestation_status": null,
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Beispiel: Ihre Zahlungen auflisten

Fragen Sie Ihre Zahlungshistorie mit Filtern ab. Erfordert Authentifizierung.

List Payments with Filters
// Using fetch with JWT authentication (from dashboard login)
const response = await fetch(
  `https://api.fivo.finance/payments?status=completed&limit=10`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    }
  }
);

const data = await response.json();
console.log(data);

// Response:
{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "payment-1",
        "amount": "49.99",
        "currency": "USDC",
        "status": "completed",
        "txHash": "0x123...",
        "sourceChain": "MATIC",
        "customerEmail": "customer@example.com",
        "reference": "ORD-2024-001",
        "createdAt": "2025-01-15T10:30:00Z"
      },
      // ... more payments
    ],
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

cURL-Beispiele

Zum schnellen Testen können Sie cURL von der Kommandozeile verwenden:

Get Payment Status (cURL)
# Get payment status (public endpoint)
curl https://api.fivo.finance/payments/PAYMENT_ID/status

# List your payments (requires JWT from login)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.fivo.finance/payments?status=completed&limit=10"

# Get merchant wallet info (public endpoint)
# MERCHANT_ID format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
curl https://api.fivo.finance/merchants/MERCHANT_ID/wallet

SDKs & Bibliotheken

Offizielle SDKs sind in Kürze verfügbar. In der Zwischenzeit können Sie Standard-HTTP-Bibliotheken in jeder Sprache verwenden, um mit der API zu interagieren.

Node.js SDK

Demnächst verfügbar

Python SDK

Demnächst verfügbar

PHP SDK

Demnächst verfügbar

Ratenbegrenzungen

Die API hat Ratenbegrenzungen, um eine faire Nutzung und Systemstabilität zu gewährleisten:

API Key-Endpunkte

200 Anfragen pro Minute

Per: API Key

Allgemeine API

100 Anfragen pro Minute

Per: IP

Zahlungserstellung (Widget)

20 Anfragen pro Minute

Per: IP

Login

5 Anfragen pro 5 Minuten

Per: IP + E-Mail

Registrierung

3 Anfragen pro 15 Minuten

Per: IP

Passwort zurücksetzen

3 Anfragen pro 15 Minuten

Per: IP + E-Mail

2FA-Verifizierung

5 Anfragen pro 5 Minuten

Per: IP

Auszahlungen

10 Anfragen pro 10 Minuten

Per: IP

Kontaktformular

3 Anfragen pro 15 Minuten

Per: IP

Wenn Sie eine Ratenbegrenzung überschreiten, erhalten Sie eine -Antwort mit einem -Header, der angibt, wann Sie es erneut versuchen können.429 Too Many RequestsRetry-After

Vollständige API-Referenz

Sehen Sie die vollständige Liste der Endpunkte, Parameter und Antwortformate.

API-Referenz anzeigen