Ejecutar una transacción

Al ejecutar una cotización se crea la transacción de pago. Cashela reserva el importe cotizado en tu billetera e inicia la entrega a través del pagador que elijas.

Endpoint

POST/api/v1/pay-out/transactions/{reference}

{reference} es la reference de la cotización que devuelve Crear una cotización (tu external_identifier). La cotización debe estar en estado ONHOLD y sin caducar.

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

Cuerpo

Campo	Tipo	Obligatorio	Descripción
external_identifier	string	Sí	Debe ser el mismo external_identifier de la cotización. Hasta 255 caracteres.
pay_out_payer_id	integer	Sí, salvo que envíes payer_id	Pagador que entrega el dinero. Usa un id de payers_available de la cotización.
payer_id	integer	Alternativa a pay_out_payer_id	Mismo significado. Envía uno de los dos.
beneficiary	object	Sí, para una persona	La persona que recibe el dinero. Ver abajo.
receiving_business	object	Sí, para una empresa	Úsalo en lugar de beneficiary cuando quien recibe es una empresa.
credit_party_identifier	object	Depende del pagador	Datos de la cuenta donde se abona el dinero (por ejemplo un número de cuenta).
sender	object	No	La persona que envía el dinero.
sending_business	object	No	Úsalo en lugar de sender cuando quien envía es una empresa.
purpose_of_remittance	string	No	Motivo del pago, hasta 255 caracteres.
required_documents	array	No	Documentos que exige el pagador, si los hay.
callback_url	string	No	URL HTTPS donde Cashela envía las notificaciones de estado. Hasta 255 caracteres. Debe ser una dirección https:// pública.

Datos del beneficiario y de la cuenta

Cashela lee estos campos de beneficiary:

Campo	Descripción
first_name	Nombre.
last_name	Apellidos.
msisdn	Teléfono. Se acepta phone como alias; si envías los dos deben ser el mismo número.
email	Correo electrónico.
country_id	ID de país en Cashela (el id de Países de pago). Debe ser el país de destino de la cotización.
registration_number, tax_id	Números de identificación, cuando el corredor los exige.

Para receiving_business, envía registered_name (la razón social) en lugar de first_name y last_name, más los mismos campos de contacto e identificación.

Los campos que exige credit_party_identifier y los campos extra del beneficiario dependen del pagador y del país. La API todavía no los devuelve: pide a Cashela la lista de campos de cada corredor que vayas a usar.

Ejemplo

curl -X POST "https://sandbox-api.cashela.com/api/v1/pay-out/transactions/payout-2026-000123" \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_identifier": "payout-2026-000123",
    "pay_out_payer_id": 123,
    "callback_url": "https://example.com/webhooks/cashela-payout",
    "purpose_of_remittance": "family_support",
    "sender": { "first_name": "Jane", "last_name": "Example" },
    "beneficiary": {
      "first_name": "Ana",
      "last_name": "Ejemplo",
      "msisdn": "+573001234567",
      "email": "ana@example.com",
      "country_id": 48
    },
    "credit_party_identifier": {}
  }'

Rellena credit_party_identifier con los campos de cuenta del corredor.

{
  "success": true,
  "data": {
    "id": "9f2c6a1e-0000-0000-0000-000000000000",
    "reference": "payout-2026-000123",
    "external_identifier": "payout-2026-000123",
    "quotation_reference": "payout-2026-000123",
    "status": "PROCESSING",
    "transaction_status": "PENDING",
    "transaction_message": "Partner PayOut transaction created and funds reserved.",
    "idempotency": { "key": "payout-2026-000123", "external_identifier": "payout-2026-000123" },
    "transaction_type": "C2C",
    "funding": { "source": "main_u_wallet", "currency": "USD", "amount": 103.5 },
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "amount": 395000, "currency": "COP", "country_iso_code": "COL" },
    "fee": { "amount": 3.5, "currency": "USD" },
    "rate": 3950,
    "payer": { "type": "pay_out_payer", "id": 123, "name": "Example Bank", "currency": "COP", "country": "COL", "service": { "id": 2, "name": "Bank deposit" } },
    "callback": { "url": "https://example.com/webhooks/cashela-payout", "last_response": null },
    "purpose_of_remittance": "family_support",
    "created_at": "2026-10-19T12:05:00+00:00",
    "updated_at": "2026-10-19T12:05:00+00:00"
  },
  "message": "Payout transaction processed successfully."
}

Los valores son ilustrativos. La respuesta puede incluir otros campos; no construyas sobre campos que no aparecen abajo.

Campos de la respuesta

Campo	Descripción
id	ID de la transacción en Cashela.
reference	Referencia de la transacción. Es la misma que la de la cotización.
external_identifier	Tu ID.
quotation_reference	Referencia de la cotización ejecutada.
status	Estado de la transacción. Consulta Estados.
transaction_status, transaction_message	Estado de la entrega y un mensaje legible. Cuando status es FAILED, transaction_message indica el motivo.
idempotency	Clave de idempotencia y external_identifier guardados con la transacción.
transaction_type	C2C, C2B, B2C o B2B.
funding	Lo que se tomó de tu billetera: currency, amount y payment_status. source es siempre main_u_wallet (tu billetera principal).
source, destination	Importes, monedas y países.
fee	Comisión y su moneda.
rate	Tasa de cambio aplicada.
payer	Pagador que entrega el dinero.
callback	Tu callback_url y el resultado de la última notificación enviada.
purpose_of_remittance	Motivo que enviaste.
created_at, updated_at	Marcas de tiempo ISO 8601.

Estados

status	Significado
PROCESSING	Fondos reservados en tu billetera y entrega iniciada.
COMPLETED	El pago se entregó. Los fondos reservados se liquidan.
FAILED	El pago falló. Si se habían reservado fondos, vuelven a tu saldo disponible.

Precaución

Algunas comprobaciones de negocio no devuelven un error HTTP: la llamada responde 200 y la transacción vuelve con status: "FAILED" y el motivo en transaction_message. Por ejemplo: Insufficient wallet balance., Recipient country does not match the destination country of the quotation., o un mensaje que empieza por Partner PayOut cannot be dispatched (por ejemplo si no enviaste beneficiary ni receiving_business). En estos casos no se reservan fondos. Revisa siempre status en la respuesta.

Idempotencia

Una cotización solo se puede ejecutar una vez. Si envías otra vez el mismo cuerpo, recibes la transacción existente. Si envías un cuerpo distinto para una cotización ya ejecutada, recibes 409 A transaction already exists for this quotation with a different execution payload.

Errores

Estado	Mensaje	Qué hacer
422	Validation failed. con errors	Corrige los campos que aparecen en errors (por ejemplo una callback_url que no es HTTPS pública).
404	Quotation not found.	Revisa la {reference} de la ruta.
422	Quotation has expired.	Crea una cotización nueva con un external_identifier nuevo.
422	Quotation is not pending execution.	La cotización ya no está en ONHOLD.
422	external_identifier does not match the quotation.	Envía el external_identifier de la cotización.
422	The selected payer is not available for this quotation.	Usa un pagador de payers_available.
404	Payer not found.	Revisa pay_out_payer_id.
503	PARTNER_PAYOUT_DISBURSEMENT_UNAVAILABLE: Sending payouts is not enabled for this environment yet. Execution refused; no funds were reserved.	Pay-Out aún no está activo para tu cuenta. No se reservó nada y la cotización sigue vigente hasta que expire: repite la misma llamada cuando Cashela confirme la activación.
404	Wallet not found for quotation pay currency.	No tienes una billetera activa en la moneda de origen.
409	A transaction already exists for this quotation ...	Consulta Idempotencia.

Consultar una transacción

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

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

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

Úsalo para confirmar el estado final, sobre todo si no te llegó una notificación.

Notificaciones

Si enviaste una callback_url, Cashela le envía un POST:

• justo después de la ejecución, con el estado resultante, y
• cuando la transacción llega a COMPLETED o FAILED.

Cada notificación lleva estas cabeceras:

Cabecera	Descripción
X-Cashela-Event	partner.payout.transaction.updated
X-Cashela-Timestamp	Hora Unix (segundos) en que se calculó la firma.
X-Cashela-Nonce	Valor único por envío (UUID).
X-Cashela-Trace-Id	ID de correlación. Indícalo a soporte.
X-Cashela-Signature	HMAC-SHA256 de {timestamp}.{nonce}.{body} con el api_secret de la clave que ejecutó la transacción mientras siga activa (o la clave activa más reciente de tu cuenta si fue eliminada).

Verifica la firma exactamente igual que en las notificaciones Pay-In: consulta Verificar la firma.

Cuerpo:

{
  "event": "partner.payout.transaction.updated",
  "event_id": "3b6f0c1a-0000-0000-0000-000000000000",
  "api_version": "v1",
  "created_at": "2026-10-19T12:20:00+00:00",
  "data": {
    "reference": "payout-2026-000123",
    "external_identifier": "payout-2026-000123",
    "quotation_reference": "payout-2026-000123",
    "status": "COMPLETED",
    "transaction_status": "COMPLETED",
    "transaction_message": "...",
    "funding": { "source": "main_u_wallet", "currency": "USD", "amount": 103.5 },
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "amount": 395000, "currency": "COP", "country_iso_code": "COL" },
    "fee": { "amount": 3.5, "currency": "USD" },
    "rate": 3950,
    "payer": { "pay_out_payer_id": 123 }
  },
  "context": { "trace_id": "6f1d2c4e-8b0a-4a57-9c1e-2f3a4b5c6d7e" }
}

Los valores son ilustrativos y se omiten algunos campos. Responde con un estado 2xx. Haz tu handler idempotente: la misma transacción puede notificarse más de una vez. Usa Consultar una transacción como fuente de verdad.

Reenviar la notificación

POST/api/v1/pay-out/transactions/{reference}/callback

Vuelve a enviar a su callback_url la notificación del estado actual de la transacción. No necesita cuerpo. Este endpoint está limitado a 6 peticiones por minuto.

La respuesta contiene la transaction (el mismo objeto de arriba) y un objeto callback:

Campo	Descripción
status	dispatched, failed o skipped.
success	true si tu endpoint respondió 2xx.
http_status	Estado que respondió tu endpoint.
reason	Si se omitió: callback_url_not_configured (no hay callback_url HTTPS) o callback_url_blocked (la URL no es una dirección pública).