Enregistrer les paiements de n’importe quel prestataire

01Créer une clé qui peut enregistrer des paiements

Sur la page Setup du site, sous API keys, nommez une clé et cochez Record payments. La clé ne s’affiche qu’une fois ; la liste la marque Records payments. Une clé sans cette option ne peut que lire, et est refusée ici avec 403.

02Envoyer chaque paiement

Quand votre serveur encaisse un paiement, quel que soit le prestataire, envoyez-le à POST https://tallybyoutpost.com/api/v1/payments avec la clé en Authorization: Bearer … et un corps JSON. Joignez-y l’identifiant de visiteur de l’acheteur, lu dans le cookie _tally_vid de sa requête :

// 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,
)

03Les champs

amountnombreobligatoire

Le montant payé, dans l’unité principale de la devise (29.99), taxes comprises. Une chaîne décimale fonctionne aussi. Supérieur à 0 : un amount de 0 est un essai gratuit, qui n’enregistre rien.

currencychaîneobligatoire

Son code ISO 4217 à trois lettres : USD, EUR, JPY.

transaction_idchaîneobligatoire

L’identifiant du paiement dans votre système, 200 caractères au plus (un nombre fonctionne aussi). Il est unique au sein du site : le renvoyer est traité comme un doublon, pas comme un second paiement.

tally_visitor_idchaîne

La valeur du cookie _tally_vid, qui lie le paiement à sa visite. datafast_visitor_id et visitor_id sont lus de la même façon.

emailchaîne

L’e-mail de l’acheteur, pour un rapprochement par e-mail. Haché dès son arrivée ; seul le hachage est conservé. customer_email fonctionne aussi.

namechaîne

Accepté, pour que le corps de DataFast fonctionne tel quel, et jamais stocké. customer_name aussi.

customer_idchaîne

Votre identifiant pour l’acheteur. Un renouvellement sans subscription_id suit le premier paiement du client.

subscription_idchaîne

Regroupe les paiements d’un abonnement, pour que chaque renouvellement suive son premier paiement.

renewalbooléen

Ce paiement renouvelle un abonnement (subscription_id, ou à défaut customer_id, indique lequel). Il est attribué comme l’a été le premier paiement.

refundedbooléen

Il s’agit d’un remboursement de amount sur le paiement que désigne transaction_id. Les remboursements partiels sont acceptés.

refund_idchaîne

Votre identifiant pour le remboursement, quand un paiement a plusieurs remboursements partiels. Sans lui, un second remboursement du même paiement est un doublon.

is_free_trialbooléen

Un essai sans rien de payé : rien n’est enregistré, et la réponse est 200.

taxnombrepar défaut : 0

La part de amount qui correspond aux taxes, pour que les revenus soient comptés hors taxes.

timestampchaînepar défaut : maintenant

Le moment du paiement : ISO 8601 avec son fuseau, comme 2026-11-10T12:00:00Z. Au plus quelques minutes dans le futur.

Tout autre champ du corps est ignoré.

04Ce qui est renvoyé

200 avec du JSON, dès que le paiement est enregistré ou l’était déjà :

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

Toute autre réponse est une erreur, comme partout dans l’API : {"error": {"code", "message"}}, où le message est une phrase que vous pouvez afficher telle quelle.

05Renouvellements et remboursements

Un renouvellement désigne son abonnement (ou son client) et définit renewal ; il est attribué comme l’a été le premier paiement de l’abonnement :

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}'

Un remboursement définit refunded, désigne le paiement qu’il annule par son transaction_id, et donne le montant remboursé. Donnez à chaque remboursement partiel d’un même paiement son propre 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"}'

06Comment chaque paiement est lié

Selon les mêmes règles que pour tout prestataire, après la réponse : un identifiant de visiteur lie avec une confiance élevée (comme les métadonnées Checkout), un e-mail avec une confiance moyenne (quand le navigateur de l’acheteur a appelé identify avec cet e-mail), et les renouvellements et remboursements suivent le paiement auquel ils se rattachent. Comment fonctionne le rattachement.

07Vérifier que ça marche