Stripe Metadata

Se crei Sessioni di pagamento Stripe tramite l'API, puoi passare il click_id nel campo metadata di Stripe usando la chiave aff_click_id. Selgeo legge questi metadati dai webhook Stripe e attribuisce la conversione al partner referente.

Versione API: v1

Quando usare questo approccio

Usa i metadati Stripe quando:

• Vuoi passare il click_id insieme al tuo valore client_reference_id.
• Crei Sessioni di pagamento ma vuoi usare client_reference_id per i tuoi scopi.

Payment Intent diretti e Abbonamenti non supportati

Selgeo elabora i metadati negli eventi webhook checkout.session.completed e invoice.paid. Usa l'API di conversione oppure crea abbonamenti tramite Stripe Checkout.

La chiave dei metadati

aff_click_id

Implementazione

JavaScript (Node.js)

const stripe = require('stripe')('sk_test_YOUR_STRIPE_KEY');

app.post('/api/create-checkout', async (req, res) => {
  const { priceId, clickId } = req.body;
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: 'https://tuo-sito.com/success',
    cancel_url: 'https://tuo-sito.com/cancel',
    client_reference_id: 'mio_riferimento_interno_123',
    metadata: {
      aff_click_id: clickId || '',
    },
  });
  res.json({ url: session.url });
});

Python

import stripe

stripe.api_key = "sk_test_YOUR_STRIPE_KEY"

@app.route("/api/create-checkout", methods=["POST"])
def create_checkout():
    data = request.get_json()
    session = stripe.checkout.Session.create(
        mode="subscription",
        line_items=[{"price": data["priceId"], "quantity": 1}],
        success_url="https://tuo-sito.com/success",
        cancel_url="https://tuo-sito.com/cancel",
        client_reference_id="mio_riferimento_interno_123",
        metadata={"aff_click_id": data.get("clickId", "")},
    )
    return jsonify({"url": session.url})

PHP

$stripe = new \Stripe\StripeClient('sk_test_YOUR_STRIPE_KEY');
$data = json_decode(file_get_contents('php://input'), true);
$session = $stripe->checkout->sessions->create([
    'mode' => 'subscription',
    'line_items' => [['price' => $data['priceId'], 'quantity' => 1]],
    'success_url' => 'https://tuo-sito.com/success',
    'cancel_url' => 'https://tuo-sito.com/cancel',
    'client_reference_id' => 'mio_riferimento_interno_123',
    'metadata' => ['aff_click_id' => $data['clickId'] ?? ''],
]);
echo json_encode(['url' => $session->url]);

Come Selgeo elabora i metadati

Per gli eventi checkout.session.completed, Selgeo controlla il click_id in questo ordine:

1. client_reference_id nella Sessione di pagamento (se presente e UUID valido).
2. metadata.aff_click_id nella Sessione di pagamento.

Test

1. Configura un partner di test e un link di tracciamento. Invita un partner di test nella dashboard del merchant, poi accedi al portale partner come quel partner e crea un link di referral (nella sezione Link). I link di tracciamento non vengono creati nella dashboard del merchant.
2. Visita il tuo sito tramite il link di tracciamento per registrare un clic.
3. Avvia il tuo flusso di pagamento — il click_id dovrebbe essere passato al tuo backend e incluso nei metadati Stripe come aff_click_id.
4. Completa il pagamento con la carta di test Stripe 4242 4242 4242 4242.
5. Controlla la dashboard Selgeo — verifica che la conversione appaia e sia attribuita al partner di test.

Verificare i metadati in Stripe

Puoi confermare che i metadati siano stati impostati correttamente nel Stripe Dashboard:

1. Trova la Sessione di pagamento.
2. Scorri fino alla sezione Metadata.
3. Verifica che aff_click_id contenga l'UUID previsto.

Passaggi successivi

• API di conversione — per le conversioni non-Stripe
• Webhooks — ricevere notifiche quando le conversioni vengono attribuite
• Modalità test — guida dettagliata ai test