Descripción general de Pay-Out

La API Pay-Out permite a tu negocio enviar dinero a beneficiarios en el extranjero. Cotizas un pago, eliges un pagador (el banco, billetera o red de efectivo que entrega el dinero) y lo ejecutas. El importe se toma de tu billetera Cashela; no interviene ninguna tarjeta ni pago bancario.

Cómo funciona

Descubre adónde puedes enviar dinero: países, servicios y pagadores.
Cotiza: crea una cotización. Fija los importes, la tasa y la comisión durante 30 minutos y lista los pagadores que pueden entregarlo.
Ejecuta: ejecuta la transacción con los datos del beneficiario y uno de los pagadores de la cotización. Cuando Pay-Out está activo para tu cuenta, Cashela reserva el importe en tu billetera e inicia el pago.
Sigue el estado: recibe una notificación firmada en tu callback_url y consulta el estado de la transacción cuando quieras.

Consulta el diagrama de flujo para ver la secuencia completa.

Disponibilidad

Pay-Out está disponible por cuenta, bajo activación: Cashela lo habilita para tu cuenta cuando completas el onboarding. Mientras no esté activo, el descubrimiento y la cotización funcionan, pero ejecutar una transacción responde 503 con el código PARTNER_PAYOUT_DISBURSEMENT_UNAVAILABLE. No se reserva ningún fondo y la cotización sigue vigente hasta que expire, así que puedes repetir la misma llamada cuando Cashela confirme la activación. Consulta Errores.

Antes de empezar

Una cuenta Cashela Business.
Una clave API y un secreto API creados en el Portal de Desarrolladores de tu panel Cashela Business. Consulta Primeros pasos. La clave debe tener acceso a Pay-Out; si no lo tiene, la API responde 403 Insufficient permissions. y debes contactar con Cashela.
Una billetera activa en la moneda desde la que envías, con saldo suficiente. La source.currency de una cotización debe ser una de las monedas de tus billeteras.

Autenticación

Pay-Out usa la misma autenticación HTTP Basic que Pay-In: usuario = tu api_key, contraseña = tu api_secret. Consulta Autenticación para más detalles, listas blancas de IPs y errores de autenticación.

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

Respuesta	Significado
`401` `Unauthorized.`	Credenciales ausentes o incorrectas, credenciales del otro entorno, o una clave desactivada o revocada.
`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 tiene permiso para usar Pay-Out.
`403` `The partner account is not active.`	Tu cuenta de negocio no está activa. Contacta con Cashela.
`429`	Demasiadas peticiones. Espera los segundos que indica la cabecera `Retry-After`.

Entornos

Entorno	URL base
Sandbox	`https://sandbox-api.cashela.com`
Producción	`https://production-api.cashela.com`

Usa la clave de la tarjeta correspondiente (Sandbox o Producción) del Portal de Desarrolladores. Todas las rutas Pay-Out empiezan por /api/v1/pay-out/.

Endpoints

Método	Ruta	Para qué
`GET`	`/api/v1/pay-out/countries`	Países de destino
`GET`	`/api/v1/pay-out/services`	Servicios de pago
`GET`	`/api/v1/pay-out/payers`	Pagadores
`POST`	`/api/v1/pay-out/calculate`	Ver una cotización sin guardarla
`POST`	`/api/v1/pay-out/quotations`	Crear una cotización
`GET`	`/api/v1/pay-out/quotations/{reference}`	Consultar una cotización
`POST`	`/api/v1/pay-out/transactions/{reference}`	Ejecutar una transacción
`GET`	`/api/v1/pay-out/transactions/{reference}`	Consultar una transacción
`POST`	`/api/v1/pay-out/transactions/{reference}/callback`	Reenviar la notificación

Formato de peticiones y respuestas

Envía JSON con Content-Type: application/json y Accept: application/json. Todas las respuestas usan el mismo sobre:

{
  "success": true,
  "data": { },
  "message": "Quotation created successfully."
}

Los errores devuelven success: false y un message. Los errores de validación devuelven 422 con los campos inválidos en errors:

{
  "success": false,
  "message": "Validation failed.",
  "errors": {
    "source.currency": ["The source currency is not available in the authenticated owner main wallets."]
  }
}

Envía la cabecera opcional X-Trace-Id (un UUID sirve) en cada petición y regístrala; indícala a soporte junto con tu external_identifier.

Idempotencia

Tu external_identifier es la clave de idempotencia de un pago:

Si creas otra vez una cotización con el mismo external_identifier y el mismo cuerpo, recibes la cotización existente en lugar de una nueva.
Si ejecutas otra vez la misma cotización con el mismo cuerpo, recibes la transacción existente.
Si reutilizas un external_identifier con un cuerpo distinto, recibes 409.

También puedes enviar la cabecera Idempotency-Key; se guarda con la cotización y la transacción y se devuelve en el objeto idempotency.