Monedero y fondeo

Tu saldo prepagado en MXN: fondea por SPEI, tarjeta o PayPal y consulta cada transacción.

El monedero es tu saldo prepagado en pesos: cada guía se debita de él al precio cotizado. Fondéalo por transferencia SPEI a tu CLABE dedicada, con tarjeta o con PayPal.

Endpoints

Fondea por SPEI (recomendado)

Cada organización recibe una CLABE dedicada: cualquier transferencia SPEI a esa cuenta se acredita automáticamente a tu monedero, sin conciliación manual.

curl -X POST https://api.sendit.mx/v1/wallet/funding-instructions \
  -H "Authorization: Bearer <jwt>"

{
  "success": true,
  "data": {
    "id": "clxfund123abc",
    "type": "mx_bank_transfer",
    "clabe": "646180111812345678",
    "bankName": "STP",
    "bankCode": "646",
    "status": "ACTIVE",
    "createdAt": "2026-07-17T01:00:00.000Z"
  }
}

El endpoint es idempotente: llamarlo de nuevo devuelve la misma CLABE. Comparte la CLABE con tu equipo de finanzas y fondea por SPEI desde cualquier banco. El crédito aparece en minutos como una transacción CREDIT.

Fondea con tarjeta

curl -X POST https://api.sendit.mx/v1/wallet/fund/card \
  -H "Authorization: Bearer <jwt>" \
  -H "Idempotency-Key: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3QyAbc123xyz",
    "clientSecret": "pi_3QyAbc123xyz_secret_def456",
    "amount": 500,
    "currency": "MXN",
    "publishableKey": "pk_test_xxxxx"
  }
}

Parámetros del cuerpo

Usa el clientSecret con Stripe.js en tu frontend para capturar la tarjeta y completar 3D Secure. Confirmado el pago, el monedero se acredita automáticamente.

El fondeo con PayPal funciona igual vía POST /v1/wallet/fund/paypal (acepta un returnUrl opcional para el regreso tras la aprobación).

Consulta el estado del pago

GET /v1/wallet/fund/pi_3QyAbc123xyz/status

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3QyAbc123xyz",
    "status": "succeeded",
    "amount": 500,
    "currency": "MXN",
    "paymentMethodType": "card",
    "walletCredited": true
  }
}

Cuando status es succeeded y walletCredited es true, el saldo ya refleja el fondeo.

Fondea con OXXO (efectivo)

Para pagar en efectivo, usa POST /v1/wallet/fund/oxxo. Genera un vale con código de barras: muéstralo o imprímelo y paga en cualquier tienda OXXO. El vale vence en 3 días. El monedero se acredita cuando OXXO confirma el pago, así que trátalo como pendiente hasta entonces. Consulta el estado del pago con /v1/wallet/fund/:paymentIntentId/status.

Parámetros del cuerpo

curl -X POST https://api.sendit.mx/v1/wallet/fund/oxxo \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3Oxxo123xyz",
    "hostedVoucherUrl": "https://payments.stripe.com/oxxo/voucher/...",
    "expiresAfter": 1800000000,
    "amount": 500,
    "currency": "MXN"
  }
}

hostedVoucherUrl es el vale imprimible. expiresAfter es la fecha de vencimiento, en segundos epoch Unix. El saldo se actualiza cuando el pago en efectivo se libera. Hasta entonces la transacción queda pendiente.

Consulta tu saldo

GET /v1/wallet/balance

{
  "success": true,
  "data": {
    "id": "clxwallet123",
    "balance": "1500.00",
    "currency": "MXN",
    "lowBalanceThreshold": "100.00",
    "lowBalanceAlertSent": false,
    "hasFundingSource": true
  }
}

Los montos son cadenas decimales. Nunca hagas aritmética flotante con dinero.

Con una llave sk_test_ este endpoint devuelve el saldo de prueba. Ver Modo de prueba.

Configura la alerta de saldo bajo

PATCH /v1/wallet/settings define a partir de qué saldo quieres recibir un aviso. Requiere rol ADMIN o superior, y el alcance wallet:write si usas una llave de API.

curl -X PATCH https://api.sendit.mx/v1/wallet/settings \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "lowBalanceThreshold": 500 }'

Manda null para desactivar la alerta.

Resumen de movimientos

Para tarjetas de “ingresos vs. egresos” sin recorrer todas las transacciones, GET /v1/wallet/summary agrega el periodo que pidas. Ambos parámetros de fecha son opcionales (from inclusivo, to exclusivo):

GET /v1/wallet/summary?from=2026-07-01&to=2026-08-01

{
  "success": true,
  "data": {
    "income": "1050.00",
    "expenses": "730.50",
    "net": "314.50",
    "adjustments": "-5.00",
    "transactionCount": 7,
    "currency": "MXN",
    "byType": {
      "CREDIT": { "count": 2, "amount": "1000.00" },
      "REFUND": { "count": 1, "amount": "50.00" },
      "DEBIT": { "count": 3, "amount": "-730.50" },
      "ADJUSTMENT": { "count": 1, "amount": "-5.00" }
    }
  }
}

income suma créditos y reembolsos. expenses es la magnitud de los débitos, que se guardan en negativo. Todos los montos son cadenas decimales.

El resumen respeta el modo de la petición. Con ?livemode=false agrega los movimientos de prueba.

Revisa tus transacciones

GET /v1/wallet/transactions?type=CREDIT&page=1&limit=20

{
  "success": true,
  "data": [
    {
      "id": "clxtx_spei_456",
      "type": "CREDIT",
      "amount": "1000.00",
      "currency": "MXN",
      "balanceAfter": "2500.00",
      "description": "Depósito vía transferencia bancaria SPEI",
      "referenceType": "stripe_bank_transfer",
      "status": "COMPLETED",
      "createdAt": "2026-07-17T10:00:00.000Z"
    },
    {
      "id": "clxtx_label_789",
      "type": "DEBIT",
      "amount": "326.82",
      "currency": "MXN",
      "balanceAfter": "1500.00",
      "description": "Compra de guía DHL Express Nacional",
      "referenceType": "label_purchase",
      "referenceId": "clxq1w2e3r4t5y6u7i8o9p0a",
      "metadata": { "carrierCode": "DHL" },
      "status": "COMPLETED",
      "createdAt": "2026-07-17T09:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 143, "totalPages": 8 }
}

Los fondeos con tarjeta, PayPal y OXXO comparten el referenceType stripe_payment_intent. Para distinguirlos, lee metadata.funding_method: vale card, paypal u oxxo.

Cada transacción trae balanceAfter. El historial es un estado de cuenta completo y auditable.

Errores