Crear una cotización

Una cotización fija los importes, la tasa de cambio y la comisión de un pago y lista los pagadores que pueden entregarlo. Después la ejecutas con Ejecutar una transacción. Una cotización es válida durante 30 minutos.

Endpoint

POST/api/v1/pay-out/quotations

Autenticación: HTTP Basic con tu clave y tu secreto API. Consulta Autenticación.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
external_identifier	string	Sí	Tu ID único para este pago, hasta 255 caracteres. Se convierte en la reference de la cotización y es la clave de idempotencia (ver abajo).
mode	string	Sí	SOURCE_AMOUNT: tú fijas el importe a enviar. DESTINATION_AMOUNT: tú fijas el importe que recibe el beneficiario.
transaction_type	string	Sí	C2C, C2B, B2C o B2B.
service_id	integer	Sí	ID de servicio que Cashela te facilita para tu integración.
pay_out_service_id	integer	No	Limita la cotización a un servicio. Usa un id de Servicios de pago.
payer_id	integer	No	Limita la cotización a un pagador. Usa un id de Pagadores.
source.currency	string	Sí	Moneda desde la que envías (ISO 4217). Debe ser la moneda de una de tus billeteras activas.
source.country_iso_code	string	Sí	Código de 3 letras del país de envío, por ejemplo USA.
source.amount	number	Con SOURCE_AMOUNT	Importe a enviar.
destination.currency	string	Sí	Moneda que recibe el beneficiario, por ejemplo COP.
destination.country_iso_code	string	Sí	Código de 3 letras del país de destino, por ejemplo COL.
destination.amount	number	Con DESTINATION_AMOUNT	Importe que recibe el beneficiario.

Los importes son números positivos con dos decimales como máximo, de 0.01 a 99999999.99. Los códigos de moneda y de país no distinguen mayúsculas.

Ejemplo

curl -X POST "https://sandbox-api.cashela.com/api/v1/pay-out/quotations" \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Trace-Id: 6f1d2c4e-8b0a-4a57-9c1e-2f3a4b5c6d7e" \
  -d '{
    "external_identifier": "payout-2026-000123",
    "mode": "SOURCE_AMOUNT",
    "transaction_type": "C2C",
    "service_id": 1,
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "currency": "COP", "country_iso_code": "COL" }
  }'

{
  "success": true,
  "data": {
    "id": 98765,
    "reference": "payout-2026-000123",
    "external_identifier": "payout-2026-000123",
    "status": "ONHOLD",
    "status_message": null,
    "idempotency": { "key": "payout-2026-000123", "external_identifier": "payout-2026-000123" },
    "mode": "SOURCE_AMOUNT",
    "transaction_type": "C2C",
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "amount": 395000, "currency": "COP", "country_iso_code": "COL" },
    "sent_amount": { "amount": 100, "currency": "USD" },
    "wholesale_fx_rate": 3950,
    "fee": { "amount": 3.5, "currency": "USD" },
    "creation_date": "2026-10-19T12:00:00.000000Z",
    "expiration_date": "2026-10-19T12:30:00.000000Z",
    "payers_available": [
      { "id": 123, "name": "Example Bank", "currency": "COP", "country": "COL", "service": { "id": 2, "name": "Bank deposit" } }
    ],
    "next_action": { "type": "execute_transaction", "endpoint": "..." }
  },
  "message": "Quotation created successfully."
}

Los importes, tasas e IDs son ilustrativos. Una llamada correcta responde 200.

Campos de la respuesta

Campo	Tipo	Descripción
id	integer	ID de la cotización en Cashela.
reference	string	Referencia de la cotización. Es tu external_identifier. Úsala en la ruta de la transacción.
external_identifier	string	Tu ID, devuelto tal cual.
status	string	ONHOLD mientras se puede ejecutar, EXPIRED pasados 30 minutos. Una vez ejecutada, sigue a la transacción (PROCESSING, COMPLETED, FAILED).
status_message	string o null	Detalle del estado, si lo hay.
idempotency	object	La cabecera Idempotency-Key que enviaste (o tu external_identifier si no enviaste ninguna) y tu external_identifier.
mode	string	Modo que pediste.
transaction_type	string	Tipo de transacción que pediste.
source	object	Importe enviado, moneda y país.
destination	object	Importe que recibe el beneficiario, moneda y país.
sent_amount	object	Importe enviado y su moneda.
wholesale_fx_rate	number	Tasa de cambio aplicada a la cotización.
fee	object	Comisión y su moneda (la moneda de origen).
creation_date	string	Cuándo se creó la cotización.
expiration_date	string	Cuándo caduca (30 minutos después de crearse).
payers_available	array	Pagadores que pueden entregar este pago: id, name, currency, country, service. Elige uno para la transacción.
next_action.type	string	Siempre execute_transaction.

Precaución

Usa las rutas de esta página. No llames a la URL de next_action.endpoint.

Idempotencia

La cotización se identifica por tu external_identifier:

• Si envías otra vez el mismo cuerpo con el mismo external_identifier, recibes la cotización existente. No se crea otra.
• Si envías un cuerpo distinto con un external_identifier que ya usaste, recibes 409 A quotation already exists for this external_identifier or idempotency key with a different payload.
• Si la cotización existente ha caducado, la repetición la devuelve con estado EXPIRED. Crea una cotización nueva con un external_identifier nuevo.

Errores

Estado	Mensaje (ejemplos)	Qué hacer
422	Validation failed. con errors	Corrige los campos que aparecen en errors. Una source.currency que no es moneda de ninguna de tus billeteras falla aquí.
422	No eligible PayOut candidate was found for the requested destination.	Ningún pagador atiende ese país, moneda y filtros. Revisa los catálogos.
422	No PayOut quote could be calculated for the requested operation.	Ningún pagador pudo cotizar ese importe. Prueba otro importe o pagador, o contacta con Cashela.
422	The selected pay_out_service_id is not valid.	Usa un id de Servicios de pago.
409	A quotation already exists for this external_identifier ...	Consulta Idempotencia.
503	Exchange rate is currently unavailable for this destination.	Reintenta más tarde.

Los errores de autenticación están en la descripción general.

Consultar una cotización

GET/api/v1/pay-out/quotations/{reference}

Devuelve el mismo objeto que la creación. {reference} es la reference de la cotización (tu external_identifier). Una referencia desconocida devuelve 404 Quotation not found for this partner.

curl "https://sandbox-api.cashela.com/api/v1/pay-out/quotations/payout-2026-000123" \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Accept: application/json"

Vista previa sin guardar

POST /api/v1/pay-out/calculate recibe el mismo cuerpo que una cotización (external_identifier es opcional) y devuelve las cotizaciones que pueden ofrecer los pagadores, sin crear una cotización. Úsalo para mostrar una estimación antes de que el usuario confirme.

La respuesta trae status: "calculated", una selected_quote (la que elegiría Cashela) y available_quotes. En cada una, lee:

Campo	Descripción
pay_out_payer_id	Pagador de esta cotización.
payer_name	Nombre del pagador.
amounts.send_amount	Importe enviado.
amounts.receiving_amount	Importe que recibe el beneficiario.
amounts.amount_paid	Importe que se toma de tu billetera.
fee.estimated_fee	Comisión.
rate.platform_rate	Tasa de cambio.

Una vista previa no reserva la tasa. Crea una cotización para fijarla.

Siguiente paso

Ejecuta la transacción con la reference de la cotización y uno de los payers_available.