> ## 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 solicitud de transacción (Cash Out) > Crea una nueva solicitud de transacción desde una de sus cuentas. Esto no realiza una transferencia bancaria en cadena. Puede proporcionar un `webhookUrl` para recibir actualizaciones de estado. ## 📝 Campos obligatorios - `accountId`: ID de su cuenta a debitar - `toCBU` o `toCVU`: CBU/CVU bancario del destinatario (22 dígitos) - `amount`: Número decimal positivo - `webhookUrl` opcional: URL para recibir actualizaciones de estado ## 🔍 Reglas de validación - La cuenta debe pertenecer al usuario autenticado - El CBU debe ser un número válido de 22 dígitos - `externalID` opcional debe ser único por cuenta si se proporciona ## OpenAPI ````yaml /api-reference/openapi.es.yaml post /transactions 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: Checkouts description: Sesiones de checkout hospedado para AR, BR, CL y BO paths: /transactions: post: tags: - Transacciones summary: Crear solicitud de transacción (Cash Out) description: > Crea una nueva solicitud de transacción desde una de sus cuentas. Esto no realiza una transferencia bancaria en cadena. Puede proporcionar un `webhookUrl` para recibir actualizaciones de estado. ## 📝 Campos obligatorios - `accountId`: ID de su cuenta a debitar - `toCBU` o `toCVU`: CBU/CVU bancario del destinatario (22 dígitos) - `amount`: Número decimal positivo - `webhookUrl` opcional: URL para recibir actualizaciones de estado ## 🔍 Reglas de validación - La cuenta debe pertenecer al usuario autenticado - El CBU debe ser un número válido de 22 dígitos - `externalID` opcional debe ser único por cuenta si se proporciona operationId: createTransactionRequest requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Transaction' examples: basic_request_cbu: summary: Solicitud básica description: >- Campos mínimos obligatorios para una solicitud de transferencia de salida value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCBU: '1100015400000000000021' amount: 15000.5 basic_request_cvu: summary: Solicitud básica con CVU description: Campos mínimos obligatorios usando destino CVU value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCVU: '0000003100012345678901' amount: 15000.5 complete_request: summary: Solicitud completa con webhook description: >- Solicitud de transferencia de salida con metadatos opcionales y URL de webhook para actualizaciones de estado value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCBU: '1100015400000000000021' amount: 25000 toName: María García toCUIT: 27987654321 concept: Payment for consulting services externalDate: '2024-06-19T10:30:00Z' coelsaCode: COELSA123456 data: reference: REF-001 category: services client_id: CLIENT-789 webhookUrl: https://client.example.com/webhooks/transaction-request responses: '201': description: Solicitud de transacción creada correctamente content: application/json: schema: $ref: '#/components/schemas/TransactionRequestResponse' examples: success: summary: Creación exitosa value: id: 789e0123-e89b-12d3-a456-426614174999 externalID: REQ-2024-001234 createdAt: '2024-06-19T10:30:00Z' status: PENDING '400': description: Solicitud incorrecta - Datos proporcionados inválidos content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Error de validación value: error: Validation failed message: The provided data is invalid details: amount: Amount must be positive currency: Currency must be 3 letters '401': description: No autorizado - Token inválido o ausente content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Token ausente value: error: Authentication required message: Bearer token is required invalid_token: summary: Token inválido value: error: Invalid token message: The provided token is invalid or expired '403': description: Prohibido - La cuenta no pertenece al usuario autenticado content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden_account: summary: Acceso a cuenta denegado value: error: You do not have access to this account '404': description: No encontrado '409': description: Conflicto - No se puede crear la solicitud content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate_external_id: summary: ID externo duplicado value: error: >- Transaction request with this external ID already exists for this account code: DUPLICATE_EXTERNAL_ID message: The provided externalID already exists for this account insufficient_net_balance: summary: Saldo neto insuficiente description: >- Rechazado porque el saldo neto (saldo - comisiones pendientes) es inferior al monto solicitado value: error: Insufficient net balance code: INSUFFICIENT_NET_BALANCE message: >- Net available balance (balance - pending fees) is not enough to cover the requested amount details: accountId: 550e8400-e29b-41d4-a716-446655440123 currency: ARS amount: 15000.5 balance: 12000 pendingFees: 2000 netBalance: 10000 '500': description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: server_error: summary: Error del servidor value: error: Internal server error message: An unexpected error occurred components: schemas: Transaction: type: object description: Solicitud de creación de transacción de salida por un usuario required: - accountId - amount properties: accountId: type: string format: uuid description: ID de la cuenta del usuario desde la cual enviar fondos example: 550e8400-e29b-41d4-a716-446655440123 fromName: type: string description: Nombre del remitente de la transacción example: Juan Pérez maxLength: 255 toName: type: string description: Nombre del destinatario de la transacción example: María García maxLength: 255 fromCBU: type: number description: CBU (número de cuenta bancaria) del remitente example: 170001540000000020000 toCBU: type: string description: CBU del destinatario (22 dígitos). Proporcione toCBU o toCVU. example: '1100015400000000000021' toCVU: type: string description: CVU del destinatario (22 dígitos). Proporcione toCBU o toCVU. example: '0000003100012345678901' amount: type: number format: decimal description: Monto de la transacción (debe ser positivo) example: 15000.5 fromCUIT: type: number description: CUIT/CUIL del remitente example: 20123456789 toCUIT: type: number description: CUIT/CUIL del destinatario example: 27987654321 concept: type: string description: Concepto o descripción de la transacción example: Payment for services maxLength: 500 externalDate: type: string format: date-time description: Fecha de la transacción en su sistema (formato ISO 8601) example: '2024-06-19T10:30:00Z' coelsaCode: type: string description: Código de transacción Coelsa example: COELSA123456 maxLength: 100 data: type: object description: Datos JSON adicionales para la transacción example: reference: REF-001 category: services metadata: source: mobile_app version: 1.2.3 webhookUrl: type: string format: uri description: >- URL de webhook opcional para recibir actualizaciones de estado de esta solicitud example: https://client.example.com/webhooks/transaction-request TransactionRequestResponse: type: object properties: id: type: string format: uuid description: ID interno de la solicitud de transacción example: 789e0123-e89b-12d3-a456-426614174999 externalID: type: string example: REQ-2024-001234 createdAt: type: string format: date-time example: '2024-06-19T10:30:00Z' status: type: string enum: - PENDING - AWAITING_REVIEW - PROCESSING - DONE - ERROR - CANCELLED example: PENDING ErrorResponse: type: object description: Carga de error devuelta por la API. additionalProperties: true required: - error properties: error: type: string example: Invalid request code: type: string description: Código de error legible por máquina (cuando esté disponible) example: INSUFFICIENT_NET_BALANCE message: type: string example: The provided data is invalid details: type: object description: Detalles adicionales del error example: field: amount code: INVALID_VALUE 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`. ````