Zahlungen von jedem Anbieter erfassen

01Einen Schlüssel erstellen, der Zahlungen erfassen darf

Gib auf der Seite Setup der Website unter API keys einem Schlüssel einen Namen und hake Record payments an. Der Schlüssel wird einmal angezeigt; die Liste kennzeichnet ihn mit Records payments. Ein Schlüssel ohne diesen Haken kann nur lesen und wird hier mit 403 abgelehnt.

02Jede Zahlung senden

Wenn dein Server eine Zahlung annimmt, egal von welchem Anbieter, sende sie an POST https://tallybyoutpost.com/api/v1/payments, mit dem Schlüssel als Authorization: Bearer … und einem JSON-Body. Sende die Besucher-ID des Käufers mit, gelesen aus dem Cookie _tally_vid seiner Anfrage:

// Express with cookie-parser, where your server records a payment it took.
app.post('/paid', async (req, res) => {
  await fetch('https://tallybyoutpost.com/api/v1/payments', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.TALLY_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 29.99,
      currency: 'USD',
      transaction_id: 'order_1042',
      tally_visitor_id: req.cookies['_tally_vid'],
      email: 'buyer@example.com',
    }),
  });
  res.sendStatus(204);
});

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 29.99, "currency": "USD", "transaction_id": "order_1042", "tally_visitor_id": "the _tally_vid cookie"}'

# Where your server records a payment it took (requests, Flask).
import os
import requests

requests.post(
    "https://tallybyoutpost.com/api/v1/payments",
    headers={"Authorization": "Bearer " + os.environ["TALLY_API_KEY"]},
    json={
        "amount": 29.99,
        "currency": "USD",
        "transaction_id": "order_1042",
        "tally_visitor_id": request.cookies.get("_tally_vid"),
        "email": "buyer@example.com",
    },
    timeout=10,
)

03Die Felder

amountZahlerforderlich

Was bezahlt wurde, in der Haupteinheit der Währung (29.99), inklusive Steuer. Ein Dezimal-String geht auch. Mehr als 0: Ein amount von 0 ist ein kostenloser Testzeitraum, der nichts erfasst.

currencyStringerforderlich

Ihr dreistelliger Code nach ISO 4217: USD, EUR, JPY.

transaction_idStringerforderlich

Die ID der Zahlung in deinem System, höchstens 200 Zeichen (eine Zahl geht auch). Sie ist innerhalb der Website eindeutig: Erneut gesendet ist sie ein Duplikat, keine zweite Zahlung.

tally_visitor_idString

Der Wert des Cookies _tally_vid, der die Zahlung mit ihrem Besuch verknüpft. datafast_visitor_id und visitor_id werden genauso gelesen.

emailString

Die E-Mail des Käufers, für einen E-Mail-Abgleich. Beim Eintreffen gehasht; nur der Hash wird behalten. customer_email geht auch.

nameString

Wird angenommen, damit der Body von DataFast unverändert funktioniert, und nie gespeichert. customer_name ebenso.

customer_idString

Deine ID für den Käufer. Eine Verlängerung ohne subscription_id folgt der ersten Zahlung des Kunden.

subscription_idString

Fasst die Zahlungen eines Abos zusammen, damit jede Verlängerung seiner ersten Zahlung folgt.

renewalBoolean

Diese Zahlung verlängert ein Abo (welches, sagt subscription_id, sonst customer_id). Sie wird so zugerechnet wie die erste Zahlung.

refundedBoolean

Dies ist eine Erstattung über amount für die Zahlung, die transaction_id nennt. Teilerstattungen sind in Ordnung.

refund_idString

Deine ID für die Erstattung, wenn eine Zahlung mehrere Teilerstattungen hat. Ohne sie ist eine zweite Erstattung derselben Zahlung ein Duplikat.

is_free_trialBoolean

Ein Testzeitraum ohne Zahlung: Nichts wird erfasst, und die Antwort ist 200.

taxZahlStandard: 0

Der Teil von amount, der Steuer ist, damit Umsatz ohne sie gezählt wird.

timestampStringStandard: jetzt

Wann bezahlt wurde: ISO 8601 mit Zeitzone, etwa 2026-11-10T12:00:00Z. Höchstens ein paar Minuten in der Zukunft.

Alles andere im Body wird ignoriert.

04Was es beantwortet

200 mit JSON, wann immer die Zahlung erfasst wird oder schon erfasst war:

{"message": "Payment recorded. It's linked to its visit within a few seconds.", "transaction_id": "order_1042", "duplicate": false}

Alles andere ist ein Fehler, wie überall in der API: {"error": {"code", "message"}}, wobei die Nachricht ein Satz ist, den du unverändert anzeigen kannst.

05Verlängerungen und Erstattungen

Eine Verlängerung nennt ihr Abo (oder ihren Kunden) und setzt renewal; sie wird so zugerechnet wie die erste Zahlung des Abos:

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 29.99, "currency": "USD", "transaction_id": "inv_2207", "subscription_id": "sub_88", "renewal": true}'

Eine Erstattung setzt refunded, nennt die Zahlung, die sie rückgängig macht, über ihre transaction_id und gibt den erstatteten Betrag an. Gib jeder Teilerstattung einer Zahlung ihre eigene refund_id:

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "currency": "USD", "transaction_id": "order_1042", "refunded": true, "refund_id": "rf_1"}'

06Wie jede Zahlung verknüpft wird

Nach denselben Regeln wie bei jedem Anbieter, nach der Antwort: Eine Besucher-ID verknüpft mit hoher Sicherheit (als Checkout-Metadaten), eine E-Mail mit mittlerer (wenn der Browser des Käufers identify damit aufgerufen hat), und Verlängerungen und Erstattungen folgen der Zahlung, zu der sie gehören. So funktioniert die Verknüpfung.

07Prüfen, ob es geklappt hat