Stripe Metadata

Si crea Sesiones de pago de Stripe a través de la API, puede pasar el click_id en el campo metadata de Stripe usando la clave aff_click_id. Selgeo lee estos metadatos de los webhooks de Stripe y atribuye la conversión al socio referente.

Versión de API: v1

Cuándo usar este enfoque

Use los metadatos de Stripe cuando:

• Quiere pasar el click_id junto con su propio valor client_reference_id.
• Crea Sesiones de pago pero quiere usar client_reference_id para sus propios fines.

Los Payment Intents directos y las Suscripciones no están soportados

Selgeo procesa metadatos en los eventos webhook checkout.session.completed e invoice.paid. Use la API de conversión en su lugar, o cree suscripciones a través de Stripe Checkout.

La clave de metadatos

aff_click_id

Esta clave se comprueba en objetos de Sesión de pago (via checkout.session.completed) y en objetos de Factura (via invoice.paid).

Implementación

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://su-sitio.com/success',
    cancel_url: 'https://su-sitio.com/cancel',
    client_reference_id: 'mi_referencia_interna_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://su-sitio.com/success",
        cancel_url="https://su-sitio.com/cancel",
        client_reference_id="mi_referencia_interna_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://su-sitio.com/success',
    'cancel_url' => 'https://su-sitio.com/cancel',
    'client_reference_id' => 'mi_referencia_interna_123',
    'metadata' => [
        'aff_click_id' => $data['clickId'] ?? '',
    ],
]);

echo json_encode(['url' => $session->url]);

Cómo procesa Selgeo los metadatos

Para los eventos checkout.session.completed, Selgeo comprueba el click_id en este orden:

1. client_reference_id en la Sesión de pago (si está presente y es un UUID válido).
2. metadata.aff_click_id en la Sesión de pago.

Pruebas

1. Configure un socio de prueba y un enlace de seguimiento. Invite a un socio de prueba en el panel del comerciante, luego inicie sesión en el portal de socios como ese socio y cree un enlace de referido (en Enlaces). Los enlaces de seguimiento no se crean en el panel del comerciante.
2. Visite su sitio a través del enlace de seguimiento para registrar un clic.
3. Active su flujo de pago — el click_id debería pasarse a su backend e incluirse en los metadatos de Stripe como aff_click_id.
4. Complete el pago con la tarjeta de prueba de Stripe 4242 4242 4242 4242.
5. Compruebe el panel de control de Selgeo — verifique que la conversión aparece y está atribuida al socio de prueba.

Verificar los metadatos en Stripe

Puede confirmar que los metadatos se establecieron correctamente en el Stripe Dashboard:

1. Busque la Sesión de pago.
2. Desplácese hasta la sección Metadata.
3. Verifique que aff_click_id contiene el UUID esperado.

Próximos pasos

• API de conversión — para conversiones no-Stripe
• Webhooks — recibir notificaciones cuando se atribuyen conversiones
• Modo de prueba — guía de pruebas detallada