Autenticación

Todas las peticiones Pay-In usan autenticación HTTP Basic:

• Usuario: tu api_key
• Contraseña: tu api_secret

Ambos los creas en el Portal de Desarrolladores. Todas las peticiones van por HTTPS y envían y reciben JSON.

curl

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

Node.js

Node.js

const auth = Buffer.from(`${process.env.CASHELA_API_KEY}:${process.env.CASHELA_API_SECRET}`).toString("base64");
const headers = {
  Authorization: `Basic ${auth}`,
  "Content-Type": "application/json",
  Accept: "application/json",
};

Python

# Python (requests)
import os, requests

session = requests.Session()
session.auth = (os.environ["CASHELA_API_KEY"], os.environ["CASHELA_API_SECRET"])
session.headers.update({"Accept": "application/json"})
r = session.get("https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries")

PHP

// PHP (cURL)
curl_setopt($ch, CURLOPT_USERPWD, getenv('CASHELA_API_KEY') . ':' . getenv('CASHELA_API_SECRET'));

Java

// Java 11+ (java.net.http)
String credentials = System.getenv("CASHELA_API_KEY") + ":" + System.getenv("CASHELA_API_SECRET");
String auth = java.util.Base64.getEncoder()
    .encodeToString(credentials.getBytes(java.nio.charset.StandardCharsets.UTF_8));
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries"))
    .header("Authorization", "Basic " + auth)
    .header("Accept", "application/json")
    .GET()
    .build();

Si tu cliente HTTP no construye la cabecera por ti, envía Authorization: Basic <base64(api_key:api_secret)>; los ejemplos de arriba lo hacen por ti.

El secreto, solo en tu servidor

Tu api_secret también firma las notificaciones que Cashela envía a tu notification_url (ver Webhooks). Quien lo tenga puede llamar a la API en tu nombre y falsificar notificaciones. Nunca lo pongas en un navegador, una app móvil, un repositorio público ni un log.

Usa las credenciales de cada entorno

Entorno	Base URL	Credenciales
Sandbox	https://sandbox-api.cashela.com	Una clave de la tarjeta Sandbox
Producción	https://production-api.cashela.com	Una clave de la tarjeta Producción

Cuando falla la autenticación

Respuesta	Causas habituales
401 {"success": false, "message": "Unauthorized."}	Faltan credenciales; clave o secreto incorrectos; credenciales del otro entorno; la clave está Deshabilitada o revocada; una clave antigua usada después de terminar su periodo de gracia tras una rotación.
403 {"success": false, "message": "IP address is not allowed."}	La clave tiene lista blanca de IPs y la petición llegó desde otra dirección.
403 {"success": false, "message": "Insufficient permissions."}	La clave no tiene permiso para ese endpoint. Contacta con soporte de Cashela.
429	Demasiadas peticiones. Espera los segundos que indica la cabecera Retry-After antes de reintentar.

Consejo

Si peticiones que funcionaban empiezan a responder 401, revisa primero el Estado de la clave en el Portal de Desarrolladores: una clave deshabilitada por error responde 401 Unauthorized. hasta que la vuelvas a habilitar.

Precaución

Los intentos de autenticación fallidos en sandbox cuentan para la verificación Autenticación sin errores del go-live. Ver Salir a producción.

Trace IDs

Envía tu propio identificador de correlación en la cabecera opcional X-Trace-Id en cada petición (un UUID funciona bien) y regístralo en tus logs. Si no lo envías, Cashela genera uno. Cítalo, junto con la reference del depósito, cuando contactes con soporte.

curl https://sandbox-api.cashela.com/api/v1/pay-in/transactions/210000000000 \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "X-Trace-Id: 6f1c2b7e-3a4d-4e5f-9a8b-1c2d3e4f5a6b"

Límites de peticiones

La API limita cuántas peticiones puede hacer una clave. Si superas un límite recibes 429 Too Many Requests con la cabecera Retry-After (segundos). Reintenta pasado ese tiempo, con espera exponencial y aleatoria si se repiten los 429. Algunos endpoints tienen límites propios más estrictos; se indican en la página de cada endpoint.