> ## Documentation Index > Fetch the complete documentation index at: https://docs.hg.cash/llms.txt > Use this file to discover all available pages before exploring further. # Crear transacción saliente (Colombia) > Crea un payout en COP desde una cuenta COP operativa. Omita `destinationType` o envíe `bank` para Fast Pay / ACH. Envíe `breb_key` o `breb_qr` para Bre-B. El éxito es `201` con `id` y `status: processing`. El monto más la comisión de salida debe caber en el saldo neto, o la API responde `409` con `code: INSUFFICIENT_NET_BALANCE`. Una cuenta que no es COP responde `400`. `Bloqueada` o `Cerrada` responde `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` responde `403` con `code: RESTRICTED`. ## OpenAPI ````yaml /api-reference/openapi.es.yaml post /co/transactions/outbound openapi: 3.1.0 info: title: HG.Cash API description: > # 🚀 API de transacciones HG.Cash API REST moderna para que los usuarios creen transacciones de salida desde sus cuentas. ## 🧾 Cómo funciona - HG.Cash asigna cuentas a su usuario - Cuando estas cuentas tienen movimientos (entrada o salida), HG.Cash notificará su backend usando la URL de webhook que configure en el panel de HG.Cash - **Firma de webhooks (HMAC)**: En la configuración de la cuenta puede generar un secreto de firma. Cuando está configurado, cada POST de webhook incluye el encabezado `X-HG-Webhook-Signature: sha256=` donde el valor es HMAC-SHA256 del cuerpo JSON sin procesar usando su secreto. Verifíquelo en su endpoint para asegurar que la solicitud es auténtica. - Para crear retiros (dinero que sale de sus cuentas), debe llamar al endpoint **Cash Out**: **Crear solicitud de transacción** (`POST /transactions`) ## 📊 Primeros pasos 1. **Genere su token de API** en la página de configuración de la cuenta 2. **Pruebe los endpoints** usando la documentación interactiva a continuación 3. **Implemente** en sus servicios de backend (nunca exponga tokens en el frontend) 4. **Supervise** su integración y maneje los errores adecuadamente ## 🔐 Autenticación Esta API usa autenticación **Bearer Token**. Incluya el token de API del usuario en el encabezado Authorization, por ejemplo `Authorization: Bearer cash_your_token_here`. ## ⚠️ Notas importantes de seguridad - Nunca comparta ni exponga su token de autenticación de API de usuario - Almacene los tokens de forma segura solo en sus servidores de backend - Todas las llamadas a la API deben realizarse desde servicios de backend seguros - Contacte a los administradores inmediatamente si su token se ve comprometido version: 1.0.0 contact: name: HG.Cash API Support email: api-support@hg.cash license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://hg.cash/api/v1 description: Servidor de producción - url: http://dev.hg.cash/api/v1 description: Servidor de desarrollo security: - bearerAuth: [] tags: - name: Transacciones description: >- Gestión de transacciones - Crear y administrar transacciones en el sistema HG.Cash. Todos los endpoints de transacciones requieren autenticación. - name: Cuentas description: >- Cuentas - Obtener información de cuentas y saldos del usuario autenticado. Todos los endpoints de cuentas requieren autenticación. - name: Datos de referencia description: >- Datos de referencia - Obtener datos de referencia como estados y tipos de transacción. Estos endpoints requieren autenticación. - name: Webhooks description: Webhooks - Notificaciones de eventos enviadas a su endpoint HTTP. - name: Brasil description: Brasil — Crear y consultar transacciones PIX (BRL). - name: Chile description: Chile — Checkout hospedado y payouts bancarios (CLP). - name: Bolivia description: Bolivia — Cash-in con QR y payouts ACH (BOB). - name: Colombia description: >- Colombia — Cash-in con checkout hospedado y payouts bancarios, llave Bre-B o QR Bre-B (COP). - name: Checkouts description: Sesiones de checkout hospedado para AR, BR, CL, BO y CO - name: Claims description: Reclamos con evidencia de comprobante de transferencia paths: /co/transactions/outbound: post: tags: - Colombia summary: Crear transacción saliente (Colombia) description: > Crea un payout en COP desde una cuenta COP operativa. Omita `destinationType` o envíe `bank` para Fast Pay / ACH. Envíe `breb_key` o `breb_qr` para Bre-B. El éxito es `201` con `id` y `status: processing`. El monto más la comisión de salida debe caber en el saldo neto, o la API responde `409` con `code: INSUFFICIENT_NET_BALANCE`. Una cuenta que no es COP responde `400`. `Bloqueada` o `Cerrada` responde `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` responde `403` con `code: RESTRICTED`. operationId: createCoOutboundTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundRequest' examples: bank: summary: Payout bancario value: accountId: YOUR_ACCOUNT_UUID amount: '50000.00' accountType: cc bankCode: '1001' accountNumber: '0000000001' beneficiaryFullName: Ana Ejemplo documentType: cc documentNumber: '1000000000' brebKey: summary: Llave Bre-B value: destinationType: breb_key accountId: YOUR_ACCOUNT_UUID amount: '25000.00' keyValue: '@EXAMPLEKEY' beneficiaryFullName: Ana Ejemplo documentType: cc documentNumber: '1000000000' email: payer@example.com brebQr: summary: QR Bre-B value: destinationType: breb_qr accountId: YOUR_ACCOUNT_UUID amount: '15000.00' qrValue: 000201010212EXAMPLEQR responses: '201': description: Payout aceptado content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 status: processing '400': description: > Validación fallida, la moneda de la cuenta no es COP, la cuenta no admite esta operación, o el monto del QR Bre-B no coincide (`code: BREB_QR_AMOUNT_MISMATCH`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ColombiaValidationError' - $ref: '#/components/schemas/ColombiaBrebQrAmountMismatch' - type: object required: - error properties: error: type: string example: Account currency must be COP for this operation '401': description: No autorizado '403': description: >- La cuenta no está operativa (`Bloqueada` o `Cerrada`) o está restringida (`Restringida`) content: application/json: schema: $ref: '#/components/schemas/ColombiaAccountStatusError' examples: notOperative: summary: La cuenta no está operativa value: error: Account is not operative code: ACCOUNT_NOT_OPERATIVE restricted: summary: La cuenta está restringida value: error: Account is restricted code: RESTRICTED '404': description: Cuenta no encontrada '409': description: El monto más la comisión de salida supera el saldo neto content: application/json: schema: $ref: '#/components/schemas/ColombiaInsufficientNetBalance' '500': description: Error interno del servidor '502': description: No se pudo completar este payout con el proveedor de pago content: application/json: schema: $ref: '#/components/schemas/ColombiaProviderError' example: error: Unable to complete this payout with the payment provider. code: CO_OUTBOUND_PROVIDER_CREATE_FAILED type: provider_error components: schemas: ColombiaOutboundRequest: type: object description: > Payout saliente en COP. Omita `destinationType` o envíe `bank` para Fast Pay / ACH. Banco exige `accountType`, `bankCode`, `accountNumber` (máx. 20), `beneficiaryFullName`, `documentType` y `documentNumber`. El banco debe admitir Fast Pay o ACH y el tipo de cuenta elegido. `breb_key` exige `keyValue`, `beneficiaryFullName`, `documentType` y `documentNumber`. No envíe campos bancarios. `breb_qr` exige `qrValue` (EMV o base64). Beneficiario y documento son opcionales. Si el QR trae un monto fijo, `amount` debe coincidir o la API responde `400` con `code: BREB_QR_AMOUNT_MISMATCH`. required: - accountId - amount properties: destinationType: type: string enum: - bank - breb_key - breb_qr description: Si se omite, el valor es `bank` accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: description: Monto positivo. Los valores string admiten como máximo 2 decimales. oneOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d{1,2})?$ accountType: type: string enum: - cc - ch - dp description: >- Obligatorio para banco. `cc` corriente, `ch` ahorros, `dp` depósito electrónico. bankCode: type: string pattern: ^\d{4}$ description: Obligatorio para banco. Código de 4 dígitos de GET /co/banks. accountNumber: type: string maxLength: 20 description: Obligatorio para banco beneficiaryFullName: type: string description: Obligatorio para banco y llave Bre-B. Opcional para QR Bre-B. documentType: $ref: '#/components/schemas/ColombiaDocumentType' documentNumber: type: string keyValue: type: string description: Obligatorio para `breb_key` qrValue: type: string description: Obligatorio para `breb_qr`. Payload EMV o base64. phone: type: string description: Teléfono E.164 opcional. Obligatorio cuando `documentType` es `nd`. example: '+570000000000' email: type: string format: email example: payer@example.com description: type: string maxLength: 40 webhookUrl: type: string format: uri ColombiaOutboundResponse: type: object required: - id - status properties: id: type: string format: uuid status: type: string enum: - processing ColombiaValidationError: type: object required: - error - details properties: error: type: string example: Validation failed details: type: array items: type: object properties: field: type: string message: type: string ColombiaBrebQrAmountMismatch: type: object required: - error - code properties: error: type: string example: Bre-B QR amount does not match the amount encoded in the QR code: type: string enum: - BREB_QR_AMOUNT_MISMATCH details: type: object properties: qrAmountCents: type: integer requestedAmountCents: type: integer ColombiaAccountStatusError: type: object required: - error - code properties: error: type: string code: type: string enum: - ACCOUNT_NOT_OPERATIVE - RESTRICTED ColombiaInsufficientNetBalance: type: object required: - error - code properties: error: type: string example: Insufficient balance to cover transfer and fee code: type: string enum: - INSUFFICIENT_NET_BALANCE details: type: object ColombiaProviderError: type: object required: - error - code - type description: >- Error cuando un payout de Colombia no puede completarse o no se puede actualizar su estado properties: error: type: string code: type: string description: >- CO_OUTBOUND_PROVIDER_CREATE_FAILED o CO_TRANSACTION_STATUS_PROVIDER_ERROR type: type: string description: provider_error ColombiaDocumentType: type: string enum: - cc - nit - ce - pa - ppt - ti - rc - te - die - nd description: > `cc` cédula de ciudadanía, `nit` NIT, `ce` cédula de extranjería, `pa` pasaporte, `ppt` PPT, `ti` tarjeta de identidad, `rc` registro civil, `te` tarjeta de extranjería, `die` documento de identificación extranjero, `nd` sin documento (Nequi). La mayoría de los números son solo dígitos. Pasaporte (`pa`) y PPT (`ppt`) son alfanuméricos. `nd` es solo bancario y solo para el código de banco `1507`. `documentNumber` debe ser `ND` y `phone` (E.164) es obligatorio. `nd` se rechaza en Bre-B. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token de autenticación de API de usuario con formato `cash_<64-char-hex>`. Valor de ejemplo `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.