Skip to main content

​
Ciclo de vida del pago

Cada pago pasa por una serie de estados:

​
Liquidación

Cuando un pago se marca como paid, el proceso de liquidación comienza automáticamente:
  1. Se deduce la comisión de la plataforma
  2. Se calcula la comisión del partner (si aplica)
  3. El monto neto se transfiere a la cuenta de recepción del merchant
  4. Se envía webhook con settlement_status: "paid"
La liquidación es en USDC en la red Stellar.

​
Montos

Todos los montos en la API están en la unidad más pequeña de la moneda:
  • 1000 USD = $10.00
  • settlement_amount de 1000 = 10.00 USDC

​
Crear un pago

El amount.value está en la unidad más pequeña de la moneda. Para USD, esto significa centavos. Entonces 1000 = $10.00.
La API devuelve un checkout_id y un qrCode (URI SEP-7) que el cliente puede escanear con cualquier wallet de Stellar.

​
Idempotencia

Los reintentos de red y los envíos duplicados pueden crear pagos duplicados. Para que POST /payments sea seguro de reintentar, envía un encabezado Idempotency-Key — una cadena única (máximo 255 caracteres) que identifica la solicitud lógica:
  • Si una solicitud con la misma clave se reenvía después de que la primera se completó, se devuelve la respuesta del pago original — no se crea un segundo pago.
  • Si la solicitud original aún se está procesando, el reintento recibe 409. El 409 siempre es transitorio — usa un retroceso exponencial corto (p. ej. reintenta tras 1s, luego 2s).
  • Reutilizar una clave con un cuerpo de solicitud distinto devuelve 422 (indica un error del cliente).
  • Una clave de más de 255 caracteres devuelve 400.
Usa una clave estable para un mismo pedido lógico — por ejemplo el id de tu pedido (order-1234). Los plugins oficiales de e-commerce (WooCommerce, PrestaShop, Odoo) lo hacen automáticamente, usando el pedido como clave. Si omites el encabezado, cada solicitud crea un nuevo pago.