Visión general de la plataforma

Esta página recoge lo que es común a todas las API de Cashela: entornos, credenciales, autenticación, convenciones de las peticiones y cómo pedir ayuda. Los detalles de cada producto están en las guías de Pay-In y Pay-Out.

Entornos

Entorno	URL base	Para qué
Sandbox	`https://sandbox-api.cashela.com`	Desarrollo y pruebas. Sin dinero real.
Producción	`https://production-api.cashela.com`	Transacciones reales con dinero real.

Cada entorno tiene sus propias credenciales, datos y referencias. Nada de lo que creas en sandbox existe en producción.

Credenciales

Tus credenciales las creas tú en el Portal de Desarrolladores de tu panel de Cashela Business (cashela.com/dashboard/developers):

Una tarjeta por entorno, Sandbox y Producción, cada una con sus claves API.
Cada clave tiene una clave API (identificador público) y un secreto API (se muestra una sola vez, al crear o rotar la clave).
Lista blanca de IPs por clave: obligatoria en las claves de producción nuevas (al menos una IP o rango CIDR de TUS servidores, no de tus clientes; la página de pago que abren tus clientes nunca se restringe); opcional en sandbox, donde una lista vacía acepta cualquier IP.
Acciones por clave: Deshabilitar / Habilitar, Rotar (la clave anterior sigue funcionando 7 días), Revocar.
Tu sandbox se crea automáticamente. Las claves de producción se emiten cuando se aprueba tu solicitud de go-live.

Guía paso a paso: Primeros pasos.

Autenticación

Todas las peticiones usan autenticación HTTP Basic sobre HTTPS: la api_key es el usuario y el api_secret es la contraseña. Pay-In y Pay-Out usan las mismas credenciales.

curl https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Accept: application/json"

Respuesta	Significado
`401 Unauthorized.`	Faltan credenciales o son incorrectas, son del otro entorno, o la clave está deshabilitada, revocada o vencida.
`403 IP address is not allowed.`	La clave tiene lista blanca de IPs y la petición llegó desde otra dirección.
`403 Insufficient permissions.`	La clave no puede usar ese endpoint.
`429`	Demasiadas peticiones: espera los segundos de `Retry-After`.

Detalles: Autenticación.

Convenciones

Cuerpos de petición y respuesta en JSON, UTF-8.
Códigos de país: ISO 3166-1 alfa-3 (MEX, USA, BRA). Códigos de moneda: ISO 4217 (USD, MXN, BRL).
Nombres de campo en snake_case (first_name, external_identifier).
Los endpoints GET solo reciben parámetros de consulta.
Envía tu propio identificador de correlación en la cabecera X-Trace-Id y cítalo a soporte.

Buenas prácticas de seguridad

Guarda los secretos solo en tus servidores; nunca en navegadores, apps móviles ni repositorios.
Usa una clave por sistema y rótalas periódicamente.
Configura la lista blanca de IPs en las claves de producción.
Verifica la firma de cada webhook antes de confiar en él. Ver Webhooks de Pay-In.
Haz idempotentes tus handlers de webhooks y reintenta de forma segura con tus propios identificadores. Ver Idempotencia.

Guías

¿Necesitas ayuda?

Contacta con el soporte de Cashela indicando el X-Trace-Id y la referencia de la transacción.