> ## 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. # Create Outbound Transaction (Colombia) > Create a COP payout from an operative COP account. Omit `destinationType` or send `bank` for Fast Pay / ACH. Send `breb_key` or `breb_qr` for Bre-B. Success is `201` with `id` and `status: processing`. Amount plus the outbound fee must fit the net balance, or the API returns `409` with `code: INSUFFICIENT_NET_BALANCE`. A non-COP account returns `400`. `Bloqueada` or `Cerrada` returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /co/transactions/outbound openapi: 3.1.0 info: title: HG.Cash API description: > # ๐Ÿš€ HG.Cash Transaction API Modern REST API for users to create outbound transactions from their accounts. ## ๐Ÿงพ How it works - We assign accounts to your user in HG.Cash - When these accounts have transactions (inbound or outbound), HG.Cash will notify your backend using the webhook URL you configure in the HG.Cash dashboard - **Webhook signature (HMAC)**: In account settings you can generate a signing secret. When configured, each webhook POST includes the header `X-HG-Webhook-Signature: sha256=` where the value is HMAC-SHA256 of the raw JSON body using your secret. Verify this in your endpoint to ensure the request is authentic. - To create cash-outs (money leaving your accounts), you must call the **Cash Out** endpoint: **Create Transaction Request (Cash Out)** (`POST /transactions`) ## ๐Ÿ“Š Getting Started 1. **Generate your API token** in the account settings page 2. **Test endpoints** using the interactive documentation below 3. **Implement** in your backend services (never expose tokens in frontend) 4. **Monitor** your integration and handle errors appropriately ## ๐Ÿ” Authentication This API uses **Bearer Token** authentication. Include your user API token in the Authorization header, for example `Authorization: Bearer cash_your_token_here`. ## โš ๏ธ Important Security Notes - Never share or expose your user API authentication token - Store tokens securely on your backend servers only - All API calls must be made from secure backend services - Contact administrators immediately if your token is compromised 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: Production server - url: http://dev.hg.cash/api/v1 description: Development server security: - bearerAuth: [] tags: - name: Transactions description: >- Transaction Management - Create and manage transactions in the HG.Cash system. All transaction endpoints require authentication. - name: Accounts description: >- Accounts - Retrieve account information and balances for the authenticated user. All account endpoints require authentication. - name: Reference Data description: >- Reference Data - Get reference data like transaction statuses and types. These endpoints require authentication. - name: Webhooks description: Webhooks - Event notifications sent to your HTTP endpoint. - name: Brazil description: >- Transaction management - Create and manage transactions in Pix system for Brazil operations - name: Chile description: Hosted checkout and bank payouts for Chile (CLP) - name: Bolivia description: QR cash-in and ACH payouts for Bolivia (BOB) - name: Colombia description: >- Hosted checkout cash-in and bank, Bre-B key, or Bre-B QR payouts for Colombia (COP) - name: Checkouts description: Hosted checkout sessions for AR, BR, CL, BO, and CO - name: Claims description: Dispute claims with transfer receipt evidence paths: /co/transactions/outbound: post: tags: - Colombia summary: Create Outbound Transaction (Colombia) description: > Create a COP payout from an operative COP account. Omit `destinationType` or send `bank` for Fast Pay / ACH. Send `breb_key` or `breb_qr` for Bre-B. Success is `201` with `id` and `status: processing`. Amount plus the outbound fee must fit the net balance, or the API returns `409` with `code: INSUFFICIENT_NET_BALANCE`. A non-COP account returns `400`. `Bloqueada` or `Cerrada` returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. operationId: createCoOutboundTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundRequest' examples: bank: summary: Bank payout value: accountId: YOUR_ACCOUNT_UUID amount: '50000.00' accountType: cc bankCode: '1001' accountNumber: '0000000001' beneficiaryFullName: Ana Ejemplo documentType: cc documentNumber: '1000000000' brebKey: summary: Bre-B key 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: Bre-B QR value: destinationType: breb_qr accountId: YOUR_ACCOUNT_UUID amount: '15000.00' qrValue: 000201010212EXAMPLEQR responses: '201': description: Payout accepted content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 status: processing '400': description: > Validation failed, account currency is not COP, the account is not supported for this operation, or the Bre-B QR amount does not match (`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: Unauthorized '403': description: >- Account is not operative (`Bloqueada` or `Cerrada`) or is restricted (`Restringida`) content: application/json: schema: $ref: '#/components/schemas/ColombiaAccountStatusError' examples: notOperative: summary: Account is not operative value: error: Account is not operative code: ACCOUNT_NOT_OPERATIVE restricted: summary: Account is restricted value: error: Account is restricted code: RESTRICTED '404': description: Account not found '409': description: Amount plus outbound fee exceeds net balance content: application/json: schema: $ref: '#/components/schemas/ColombiaInsufficientNetBalance' '500': description: Internal server error '502': description: Unable to complete this payout with the payment provider 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: > Outbound COP payout. Omit `destinationType` or send `bank` for Fast Pay / ACH. Bank requires `accountType`, `bankCode`, `accountNumber` (max 20), `beneficiaryFullName`, `documentType`, and `documentNumber`. The bank must support Fast Pay or ACH and the chosen account type. `breb_key` requires `keyValue`, `beneficiaryFullName`, `documentType`, and `documentNumber`. Do not send bank fields. `breb_qr` requires `qrValue` (EMV or base64). Beneficiary and document are optional. If the QR encodes a fixed amount, `amount` must match or the API returns `400` with `code: BREB_QR_AMOUNT_MISMATCH`. required: - accountId - amount properties: destinationType: type: string enum: - bank - breb_key - breb_qr description: Defaults to `bank` when omitted accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: description: Positive amount. String values allow at most 2 decimal places. oneOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d{1,2})?$ accountType: type: string enum: - cc - ch - dp description: >- Required for bank. `cc` checking, `ch` savings, `dp` electronic deposit. bankCode: type: string pattern: ^\d{4}$ description: Required for bank. 4-digit code from GET /co/banks. accountNumber: type: string maxLength: 20 description: Required for bank beneficiaryFullName: type: string description: Required for bank and Bre-B key. Optional for Bre-B QR. documentType: $ref: '#/components/schemas/ColombiaDocumentType' documentNumber: type: string keyValue: type: string description: Required for `breb_key` qrValue: type: string description: Required for `breb_qr`. EMV or base64 payload. phone: type: string description: Optional E.164 phone. Required when `documentType` is `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 when a Colombia payout cannot be completed or its status cannot be refreshed properties: error: type: string code: type: string description: >- CO_OUTBOUND_PROVIDER_CREATE_FAILED or 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` Citizenship ID, `nit` NIT, `ce` Foreign ID, `pa` Passport, `ppt` PPT, `ti` Identity card, `rc` Birth certificate, `te` Foreign card, `die` Foreign identification document, `nd` No document (Nequi). Most numbers are digits only. Passport (`pa`) and PPT (`ppt`) are alphanumeric. `nd` is bank-only, only for bank code `1507`. `documentNumber` must be `ND`, and `phone` (E.164) is required. `nd` is rejected on Bre-B. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > User API authentication token with format `cash_<64-char-hex>`. Sample value `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.