Integración avanzada

Estos campos son opcionales y se agregan a la orden que creás con POST {base_url}/api/v2/orders. Todos van dentro de data.attributes, junto a currency e items.

Al final de la página hay un ejemplo completo con todos los campos juntos.

Monto del envío

Suma el costo de envío al total de la orden. El comprador lo ve como un ítem más en el detalle.

"shipping": {
  "name": "Envío por Correo Argentino",
  "price": {
    "currency": "032",
    "amount": 60100
  }
}

Por ejemplo: un ítem de 150000 ($1.500) más un envío de 60100 ($601) da una orden con price.amount = 210100 ($2.101).

Si no hay envío, no mandes el campo shipping.

URL de retorno

Cuando termina el pago, redirigimos al comprador a tu sitio: a una URL si el pago se aprobó y a otra si falló.

"redirect_urls": {
  "success": "https://mitienda.com/pago-ok?pedido=1234",
  "failed": "https://mitienda.com/pago-fallido?pedido=1234"
}

• Solo se admiten URLs HTTPS.
• Podés agregar parámetros propios (como ?pedido=1234) para saber de qué pedido se trata cuando el comprador vuelve.

Webhook URL

Cuando un pago termina, le enviamos un POST a esta URL con el resultado. Es la forma más confiable de enterarte de un pago, porque llega aunque el comprador cierre el navegador antes de volver a tu sitio.

"webhookUrl": "https://mitienda.com/webhooks/sipago?token=UN_SECRETO_TUYO"

La URL tiene que ser pública: SiPago tiene que poder llegar a ella desde internet. Para probar en tu computadora, podés usar un túnel como ngrok.

Qué te enviamos

Un POST con un JSON como este:

{
  "data": {
    "type": "Payment",
    "order": {
      "uuid": "ea138a99-c9df-44a5-b2bf-09e5db6f8d0c",
      "status": "SUCCESS",
      "source": "api_checkout"
    },
    "payment": {
      "id": 1823,
      "authorizationCode": "901159",
      "refNumber": "62b4a8ff60fee",
      "status": "APPROVED"
    }
  }
}

Cómo responder

• Respondé 200 lo antes posible. Si tenés que hacer algo lento (mandar un mail, facturar…), hacelo después de responder.
• Si tu endpoint responde con un error o no responde, reintentamos el envío: hasta 4 llamados, con unos 2 minutos entre cada uno.
• Por los reintentos, podés recibir el mismo aviso más de una vez. Tu código tiene que ser idempotente: procesar dos veces el mismo uuid no puede, por ejemplo, despachar dos veces el pedido.

Seguridad

El webhook no viene firmado, así que cualquiera que conozca tu URL podría enviarte un aviso falso. Para protegerte:

1. Confirmá siempre el estado con GET /api/v2/orders/{uuid} antes de dar el pedido por pagado. No confíes solo en el contenido del webhook.
2. Agregá un secreto a la URL, por ejemplo ?token=UN_SECRETO_TUYO. Rechazá con 401 los avisos que no lo traigan.

// Ejemplo con Express
app.post('/webhooks/sipago', express.json(), async (req, res) => {
  if (req.query.token !== process.env.WEBHOOK_SECRET) return res.sendStatus(401);
  res.sendStatus(200); // respondé primero

  const uuid = req.body?.data?.order?.uuid;
  const order = await consultarOrden(uuid); // GET /api/v2/orders/{uuid}
  if (order.status === 'SUCCESS') {
    await marcarPedidoComoPagado(uuid); // idempotente
  }
});

Tiempo límite para pagar (expireLimitMinutes)

Pone un tiempo límite, en minutos, para pagar la orden. Una vez vencido, el link ya no sirve.

"expireLimitMinutes": 30

Cuando vence el tiempo:

Ejemplo completo

Una orden con todos los campos opcionales:

curl --request POST 'https://{base_url}/api/v2/orders' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "attributes": {
        "currency": "032",
        "items": [{
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": { "currency": "032", "amount": 100000 },
          "quantity": 1
        }],
        "shipping": {
          "name": "Envío por Correo Argentino",
          "price": { "currency": "032", "amount": 60100 }
        },
        "redirect_urls": {
          "success": "https://mitienda.com/pago-ok?pedido=1234",
          "failed": "https://mitienda.com/pago-fallido?pedido=1234"
        },
        "webhookUrl": "https://mitienda.com/webhooks/sipago?token=UN_SECRETO_TUYO",
        "expireLimitMinutes": 30
      }
    }
  }'