Crear un depósito

Crea un depósito para que tu cliente lo pague con el método que elegiste en Obtener métodos de pago. La respuesta te dice cómo paga tu cliente: un enlace a una página de pago alojada por Cashela, o instrucciones de pago.

POST/api/v1/pay-in/deposit-creation

Autenticación	HTTP Basic (api_key:api_secret)
Mueve dinero	Sí
Cabeceras opcionales	Idempotency-Key, X-Trace-Id

Cuerpo de la petición

El cuerpo tiene dos partes: campos fijos, siempre obligatorios, y campos del pagador, que dependen del método de pago.

Campos fijos (todos obligatorios)

Campo	Tipo	Descripción
payment_type	string	Un tipo de pago disponible para country (por ejemplo BANK_TRANSFER, CREDIT_CARD, VOUCHER).
payment_method	string	El código payment_method de la opción que devolvió Obtener métodos de pago para ese país y tipo.
amount	number	Positivo, con dos decimales como máximo, de 0.01 a 99999999.99.
country	string	Código ISO de 3 letras del país del depósito.
external_identifier	string (≤ 255)	Tu identificador único de este depósito (por ejemplo, tu número de pedido). Único por cuenta. Ver Idempotencia.
invoice_description	string (≤ 255)	Qué está pagando tu cliente. Texto plano: se rechazan etiquetas HTML.
notification_url	string (≤ 255)	Tu endpoint HTTPS para la notificación firmada. Debe usar https, no puede llevar credenciales incrustadas y no puede apuntar a una dirección privada o interna. Ver Webhooks.
redirect_url	string (≤ 255)	URL https válida a la que vuelve tu cliente después de la página de pago. Su dominio debe estar en tus URLs de retorno aprobadas.
logo	string (≤ 255)	URL absoluta de tu logo (por ejemplo https://partner.example.com/logo.png), que se muestra en la página de pago.
mobile	boolean	Si tu cliente está en un dispositivo móvil. Es un booleano, no un número de teléfono.
language	string	en o es: idioma de la página de pago.
fee_on_payer	boolean	true suma las comisiones a lo que paga tu cliente; false las descuenta de lo que se te acredita.
client_ip	string	La IP pública de tu cliente (IPv4 o IPv6), no la de tu servidor. En pagos con tarjeta, su ubicación debe coincidir con country.

logo y client_ip son obligatorios

Una petición sin logo o sin client_ip se rechaza con 422 y errors.logo / errors.client_ip. Los booleanos (mobile, fee_on_payer) deben ser true/false de JSON: cualquier otro valor se lee como ausente ("The mobile field is required.").

Campos del pagador (dependen del método)

Envía todos los campos que aparecen en required_fields / mandatory_fields de la opción elegida, en la raíz del JSON, como strings de hasta 255 caracteres. Los habituales son first_name, last_name, email, phone, document_key y document_number; según el país y el método también pueden pedirse middle_name, second_last_name, address, city, region, zip_code o campos propios del método como cbu (Argentina, 22 dígitos).

Sus reglas, los documentos aceptados y mensajes de validación reales están en Datos del pagador y documentos.

Ejemplo

curl https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "Idempotency-Key: order-2026-0001" \
  -H "X-Trace-Id: 6f1c2b7e-3a4d-4e5f-9a8b-1c2d3e4f5a6b" \
  -d '{
    "payment_type": "BANK_TRANSFER",
    "payment_method": "BX",
    "amount": 25.50,
    "country": "CHL",
    "external_identifier": "order-2026-0001",
    "invoice_description": "Order 2026-0001",
    "notification_url": "https://partner.example.com/webhooks/cashela",
    "redirect_url": "https://partner.example.com/orders/2026-0001",
    "logo": "https://partner.example.com/logo.png",
    "mobile": false,
    "language": "es",
    "fee_on_payer": true,
    "client_ip": "200.27.10.1",
    "first_name": "María José",
    "last_name": "Pérez",
    "email": "maria.perez@example.com",
    "phone": "+56912345678",
    "document_key": "RUT",
    "document_number": "12.345.678-5"
  }'

BX es un código de ejemplo: usa siempre un payment_method que te devuelva Obtener métodos de pago para tu cuenta. Todos los datos personales de estos ejemplos son ficticios.

Respuesta 200

El depósito, con su estado inicial. Valores ilustrativos.

{
  "success": true,
  "data": {
    "id": "1048576",
    "reference": "210000000000",
    "external_identifier": "order-2026-0001",
    "status": "PROCESSING",
    "status_message": null,
    "details": {
      "invoice_number": "INV-0001",
      "invoice_description": "Order 2026-0001",
      "invoice_country": "CHL",
      "invoice_currency": "CLP",
      "invoice_rate": 940.12,
      "invoice_fee": 0,
      "invoice_tax": 0,
      "invoice_amount": 23973.06,
      "customer": { "first_name": "María José", "last_name": "Pérez", "email": "maria.perez@example.com" },
      "paying": {
        "method": "Bank Transfer",
        "code": "BX",
        "name": "BX",
        "metadata": {
          "iframe": false,
          "redirect_url": "https://…",
          "validity_period": "2026-10-20T15:04:05+00:00"
        }
      },
      "charged_amount": 23973.06,
      "charged_currency": "CLP"
    },
    "card": null,
    "reversals": { "refunds": [], "disputes": [] }
  },
  "message": "Deposit created."
}

Qué leer

Campo	Descripción
reference	Referencia de Cashela del depósito. Úsala (o tu external_identifier) en GET /transactions/{reference}. Es el ref de la notificación.
status	Estado inicial, normalmente PROCESSING (esperando a tu cliente) u ONHOLD. INREVIEW significa que un documento necesita revisión manual: todavía no se emite enlace de pago. Ver estados.
status_message	Detalle legible cuando lo hay.
details.invoice_*	La factura que ve tu cliente: país, moneda, tasa, comisión, impuesto e importe en esa moneda.
details.customer	Los datos del pagador registrados en el depósito.
details.paying	Cómo paga tu cliente: method, code, name, logo y metadata (abajo).
details.paying.metadata.redirect_url	El enlace de pago. Redirige a tu cliente a él, o ábrelo en una ventana o pestaña nueva. En tarjetas es una página alojada por Cashela (https://www.cashela.com/partner-checkout/{token} en producción).
details.paying.metadata.validity_period	Fecha y hora ISO-8601 hasta la que tu cliente puede pagar (alrededor de una hora en tarjetas). Después, el depósito termina en CANCELLED y no se cobra nada.
details.paying.metadata.iframe	Siempre false: no incrustes la página de pago en un iframe.
details.paying.metadata (otras claves)	En vouchers y transferencias, aquí pueden venir las instrucciones de pago (por ejemplo digitable_line, qr_code, payment_info). Muéstralas a tu cliente.
details.charged_amount, details.charged_currency	Lo que se cobra a tu cliente. En opciones de tarjeta que cobran en USD es el importe en USD, mientras que invoice_* es la estimación en moneda local.
card	{ "network", "last4" } de la tarjeta que pagó, o null (métodos sin tarjeta, o antes del cobro).
reversals	Anulaciones y reembolsos del depósito, si los hay.

Nota

Las instrucciones de pago de details.paying.metadata solo se devuelven mientras el depósito todavía se puede pagar. Cuando es final, ya no se incluyen.

URLs de retorno aprobadas

Tu cliente solo vuelve a un redirect_url cuyo dominio hayas aprobado. Administra la lista tú mismo en el Developer Portal de tu Dashboard: abre una API key (el ícono del ojo) y usa sus URLs de retorno permitidas:

• Agrega la URL o solo el dominio (por ejemplo https://checkout.mitienda.com o checkout.mitienda.com); solo se acepta https y Cashela guarda el dominio.
• Puedes aprobar varios dominios (hasta 20). La lista es de cada API key, así que una key solo acepta los dominios aprobados para ella.
• Un subdominio de un dominio aprobado también se acepta (pay.mitienda.com para mitienda.com).
• Aprueba tus dominios de pruebas y de producción antes de crear depósitos que los usen. Un redirect_url en un dominio no aprobado se rechaza con un error de validación (422).

Idempotencia y reintentos seguros

Crear un depósito mueve dinero, así que un reintento nunca debe crear un segundo depósito.

• Cada depósito lleva tu external_identifier único. Guárdalo antes de llamar a la API.
• También puedes enviar la cabecera Idempotency-Key. Si no la envías, la clave es el external_identifier.
• Las claves son propias de tus credenciales y de tu entorno.

Repites la petición con…	Resultado
La misma clave y el mismo cuerpo	200 con el depósito original. No se crea nada nuevo ni se cobra dos veces.
La misma clave y un cuerpo distinto	409 PARTNER_PAYIN_IDEMPOTENCY_CONFLICT: “A deposit already exists for this external_identifier or idempotency key with a different payload.” No se crea nada.

Si la petición original falló (por ejemplo, la red de pago la rechazó), repetirla devuelve el mismo fallo sin volver a intentarlo. Para intentarlo de nuevo con datos corregidos, usa un external_identifier nuevo.

Después de un timeout o un 5xx, reintenta con la misma clave y el mismo cuerpo, o consulta el depósito con GET /api/v1/pay-in/transactions/{external_identifier} antes de decidir.

Validación y errores

Un 422 con errors significa que no se creó ni se cobró nada. Corrige los campos y vuelve a enviar.

{
  "success": false,
  "status": false,
  "message": "The logo field is required.",
  "errors": {
    "logo": ["The logo field is required."]
  }
}

errors lista cada campo no válido con sus mensajes; message es un resumen legible. status: false es un alias obsoleto de success: false; lee success. Algunas cuentas reciben además field_errors[] (una entrada por campo con field, code y expected_format).

Errores de dominio habituales en este endpoint:

HTTP	Código	Qué hacer
404	PARTNER_PAYIN_PAYMENT_METHOD_NOT_FOUND	El método no está disponible para ese país, cuenta o entorno. Vuelve a consultar los métodos.
404	PARTNER_PAYIN_COUNTRY_NOT_FOUND	País desconocido.
403	PARTNER_PAYIN_RAIL_NOT_ENABLED_FOR_TENANT	Este método de pago no está habilitado para tu cuenta. Contacta con Cashela.
409	PARTNER_PAYIN_IDEMPOTENCY_CONFLICT	Misma clave, cuerpo distinto. Ver arriba.
409	PARTNER_PAYIN_EXTERNAL_IDENTIFIER_CONFLICT	Ya existe un depósito con ese external_identifier.
422	PARTNER_PAYIN_AMOUNT_BELOW_MINIMUM / PARTNER_PAYIN_AMOUNT_ABOVE_MAXIMUM	El importe está fuera de los límites del método. El mensaje indica el límite.
422	PARTNER_PAYIN_ROUTE_UNAVAILABLE	El método no está disponible temporalmente. Vuelve a consultar los métodos y elige otro, o reintenta más tarde.
422	PARTNER_PAYIN_PROVIDER_REJECTED	La red de pago rechazó el depósito, normalmente por los datos del pagador. Cuando puede, la respuesta indica el campo en provider_reason. Corrígelo y reintenta con un external_identifier nuevo.
422	PARTNER_PAYIN_COMPLIANCE_BLOCKED	El depósito no se puede crear por motivos de cumplimiento.
502	PARTNER_PAYIN_PROVIDER_ERROR	Falló la red de pago. Consulta el depósito antes de enviar una petición nueva.

El campo code es opcional: léelo cuando venga, pero no dependas de él. Lista completa: Errores.

Después de crear el depósito

1. Envía a tu cliente a details.paying.metadata.redirect_url, o muestra las instrucciones.
2. Espera la notificación firmada en tu notification_url.
3. Si no llega, consulta el depósito con Consultar un depósito o pide que se reenvíe con el endpoint de reenvío.