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.


    ## 🔐 Authentication


    This API uses **Bearer Token** authentication. Include your user API token
    in the Authorization header:


    ```

    Authorization: Bearer cash_your_token_here

    ```


    ## 📊 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


    ## ⚠️ 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: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        User API authentication token with format: `cash_<64-char-hex>`


        Example:
        `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`
  schemas:
    Transaction:
      type: object
      description: Outbound transaction creation request by a user
      required:
        - accountId
        - amount
      properties:
        accountId:
          type: string
          format: uuid
          description: ID of the user's account to send funds from
          example: 550e8400-e29b-41d4-a716-446655440123
        fromName:
          type: string
          description: Name of the transaction sender
          example: Juan Pérez
          maxLength: 255
        toName:
          type: string
          description: Name of the transaction recipient
          example: María García
          maxLength: 255
        fromCBU:
          type: number
          description: CBU (bank account number) of the sender
          example: 170001540000000020000
        toCBU:
          type: string
          description: Recipient CBU (22 digits). Provide either toCBU or toCVU.
          example: '1100015400000000000021'
        toCVU:
          type: string
          description: Recipient CVU (22 digits). Provide either toCBU or toCVU.
          example: '0000003100012345678901'
        amount:
          type: number
          format: decimal
          description: Transaction amount (must be positive)
          example: 15000.5
        fromCUIT:
          type: number
          description: CUIT/CUIL of the sender
          example: 20123456789
        toCUIT:
          type: number
          description: CUIT/CUIL of the recipient
          example: 27987654321
        concept:
          type: string
          description: Transaction concept or description
          example: Payment for services
          maxLength: 500
        externalDate:
          type: string
          format: date-time
          description: Transaction date in your system (ISO 8601 format)
          example: '2024-06-19T10:30:00Z'
        coelsaCode:
          type: string
          description: Coelsa transaction code
          example: COELSA123456
          maxLength: 100
        data:
          type: object
          description: Additional JSON data for the transaction
          example:
            reference: REF-001
            category: services
            metadata:
              source: mobile_app
              version: 1.2.3
        webhookUrl:
          type: string
          format: uri
          description: Optional webhook URL to receive status updates for this request
          example: https://client.example.com/webhooks/transaction-request
    TransactionRequestResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Internal transaction request ID
          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
            - PROCESSING
            - DONE
            - ERROR
          example: PENDING
    TransactionStatus:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: pending
        description:
          type: string
          example: Transaction is pending processing
    TransactionType:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
        name:
          type: string
          example: transfer
        description:
          type: string
          example: Bank transfer transaction
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid request
        message:
          type: string
          example: The provided data is invalid
        details:
          type: object
          description: Additional error details
          example:
            field: amount
            code: INVALID_VALUE
    TransactionRequestStatusWebhook:
      type: object
      description: >
        Payload sent to your webhook endpoint when a transaction request status
        changes.


        Notes:

        - Numeric values (like `amount`, CBU/CUIT) are sent as strings to
        preserve precision and formatting.

        - Configure your webhook URL in the account settings page.
      required:
        - id
        - externalID
        - amount
        - currency
        - direction
        - status
        - type
        - accountId
      properties:
        id:
          type: string
          format: uuid
          description: Internal transaction ID
          example: 789e0123-e89b-12d3-a456-426614174999
        externalID:
          type: string
          description: External ID provided when creating the transaction
          example: TXN-2024-001234
        amount:
          type: string
          description: Transaction amount as a decimal string
          example: '15000.50'
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
          example: ARS
        direction:
          type: string
          enum:
            - Inbound
            - Outbound
          description: Transaction direction
          example: Inbound
        status:
          type: string
          description: Current transaction request status
          example: PENDING
        type:
          type: string
          description: Type of notification. Always "request" for transaction requests
          example: request
        accountId:
          type: string
          format: uuid
          description: HG.Cash account ID associated with the transaction
          example: 550e8400-e29b-41d4-a716-446655440123
        error:
          type: string
          description: Optional error message when status is ERROR
          example: Insufficient funds on destination account
        errorCode:
          type: string
          description: Machine-readable error code when status is ERROR
          enum:
            - INSUFFICIENT_BALANCE
            - DESTINATION_ERROR
          example: INSUFFICIENT_BALANCE
        fromName:
          type: string
          description: Name of the sender
          example: Juan Pérez
        toName:
          type: string
          description: Name of the recipient
          example: María García
        fromCBU:
          type: string
          description: Sender CBU (22-digit). Sent as string.
          pattern: ^\d{22}$
          example: '1700015400000000000010'
        toCBU:
          type: string
          description: Recipient CBU (22-digit). Sent as string.
          pattern: ^\d{22}$
          example: '1100015400000000000021'
        toCVU:
          type: string
          description: Recipient CVU (22-digit). Sent as string.
          pattern: ^\d{22}$
          example: '0000003100012345678901'
        fromCUIT:
          type: string
          description: Sender CUIT/CUIL (11-digit). Sent as string.
          pattern: ^\d{11}$
          example: '20123456789'
        toCUIT:
          type: string
          description: Recipient CUIT/CUIL (11-digit). Sent as string.
          pattern: ^\d{11}$
          example: '27987654321'
        concept:
          type: string
          description: Transaction concept or description
          example: Payment for services
        coelsaCode:
          type: string
          description: Coelsa transaction code
          example: COELSA123456
paths:
  /transactions:
    post:
      summary: Create Transaction Request
      description: >
        Create a new transaction request from one of your accounts. This does
        not perform an on-chain/bank transfer. An admin will process it. You may
        provide a `webhookUrl` to receive status updates.


        ## 📝 Required Fields


        - `accountId`: Your account ID to debit from

        - `toCBU` or `toCVU`: Recipient bank CBU/CVU (22 digits)

        - `amount`: Positive decimal number

        - Optional `webhookUrl`: URL to receive status updates


        ## 🔍 Validation Rules


        - Account must belong to the authenticated user

        - CBU must be a valid 22-digit number

        - Optional `externalID` must be unique per account if provided
      operationId: createTransactionRequest
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
            examples:
              basic_request_cbu:
                summary: Basic request
                description: Minimal required fields for an outbound transfer request
                value:
                  accountId: 550e8400-e29b-41d4-a716-446655440123
                  toCBU: '1100015400000000000021'
                  amount: 15000.5
              basic_request_cvu:
                summary: Basic request with CVU
                description: Minimal required fields using CVU destination
                value:
                  accountId: 550e8400-e29b-41d4-a716-446655440123
                  toCVU: '0000003100012345678901'
                  amount: 15000.5
              complete_request:
                summary: Complete request with webhook
                description: >-
                  Outbound transfer request with optional metadata and webhook
                  URL for status updates
                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: Transaction request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRequestResponse'
              examples:
                success:
                  summary: Successful Creation
                  value:
                    id: 789e0123-e89b-12d3-a456-426614174999
                    externalID: REQ-2024-001234
                    createdAt: '2024-06-19T10:30:00Z'
                    status: PENDING
        '400':
          description: Bad Request - Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Validation Error
                  value:
                    success: false
                    error: Validation failed
                    message: The provided data is invalid
                    details:
                      amount: Amount must be positive
                      currency: Currency must be 3 letters
                duplicate_external_id:
                  summary: Duplicate External ID
                  value:
                    success: false
                    error: Duplicate external ID
                    message: >-
                      Transaction with this external ID already exists for your
                      platform
        '401':
          description: Unauthorized - Invalid or missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing Token
                  value:
                    success: false
                    error: Authentication required
                    message: Bearer token is required
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    error: Invalid token
                    message: The provided token is invalid or expired
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server_error:
                  summary: Server Error
                  value:
                    success: false
                    error: Internal server error
                    message: An unexpected error occurred
  /transaction/{id}/status:
    get:
      summary: Get Transaction Request Status
      description: >
        Retrieve the status of a transaction request created via
        `/transactions`.

        Requires the bearer token of the user that created the request.
      operationId: getTransactionRequestStatus
      tags:
        - Transactions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Transaction request ID
      responses:
        '200':
          description: Status retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  externalID:
                    type: string
                    nullable: true
                  status:
                    type: string
                    enum:
                      - PENDING
                      - PROCESSING
                      - DONE
                      - ERROR
                  errorMessage:
                    type: string
                    nullable: true
                  errorCode:
                    type: string
                    nullable: true
                    enum:
                      - INSUFFICIENT_BALANCE
                      - DESTINATION_ERROR
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /accounts:
    get:
      summary: Get User Accounts
      description: |
        Returns the authenticated user's accounts.
      operationId: getUserAccounts
      tags:
        - Transactions
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                        balance:
                          type: number
                          description: Account balance rounded to 2 decimals
                        currency:
                          type: string
                        number:
                          type: string
                        alias:
                          type: string
                          nullable: true
                        platform:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            name:
                              type: string
                  count:
                    type: integer
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /account/{id}/balance:
    get:
      summary: Get Account Balance
      description: |
        Returns the balance for the authenticated user's account by ID.
      operationId: getAccountBalance
      tags:
        - Transactions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Account ID
      responses:
        '200':
          description: Account balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  balance:
                    type: number
                    description: Account balance rounded to 2 decimals
                  currency:
                    type: string
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /transaction-statuses:
    get:
      summary: Get Transaction Statuses
      description: |
        Retrieve all available transaction statuses.

        Use the returned IDs for informational purposes.

        ## 📋 Common Statuses

        - **processing**: Transaction is being processed
        - **done**: Transaction completed successfully
        - **failed**: Transaction processing failed
      operationId: getTransactionStatuses
      tags:
        - Reference Data
      responses:
        '200':
          description: List of transaction statuses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionStatus'
              examples:
                statuses:
                  summary: Transaction Statuses
                  value:
                    success: true
                    data:
                      - id: 550e8400-e29b-41d4-a716-446655440000
                        name: pending
                        description: Transaction is pending processing
                      - id: 550e8400-e29b-41d4-a716-446655440001
                        name: completed
                        description: Transaction completed successfully
                      - id: 550e8400-e29b-41d4-a716-446655440002
                        name: failed
                        description: Transaction processing failed
        '401':
          description: Unauthorized - Invalid or missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing Token
                  value:
                    success: false
                    error: Authentication required
                    message: Bearer token is required
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    error: Invalid token
                    message: The provided token is invalid or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /transaction-types:
    get:
      summary: Get Transaction Types
      description: |
        Retrieve all available transaction types.

        Use the returned IDs in the `typeID` field when creating transactions.

        ## 📋 Common Types

        - **transfer**: Bank transfer
        - **payment**: Payment transaction
        - **deposit**: Money deposit
        - **withdrawal**: Money withdrawal
      operationId: getTransactionTypes
      tags:
        - Reference Data
      responses:
        '200':
          description: List of transaction types
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionType'
              examples:
                types:
                  summary: Transaction Types
                  value:
                    success: true
                    data:
                      - id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                        name: transfer
                        description: Bank transfer transaction
                      - id: 6ba7b810-9dad-11d1-80b4-00c04fd430c9
                        name: payment
                        description: Payment transaction
                      - id: 6ba7b810-9dad-11d1-80b4-00c04fd430ca
                        name: deposit
                        description: Money deposit transaction
        '401':
          description: Unauthorized - Invalid or missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing Token
                  value:
                    success: false
                    error: Authentication required
                    message: Bearer token is required
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    error: Invalid token
                    message: The provided token is invalid or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
webhooks:
  transaction-request-status-updated:
    post:
      summary: Transaction Request Status Updated
      description: >
        HG.Cash will send this webhook when a transaction request status
        changes. The request body contains the request details and current
        status.

        You can provide a `webhookUrl` in the create request payload, or
        configure a default in user settings.
      operationId: transactionRequestStatusUpdatedWebhook
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestStatusWebhook'
            examples:
              example:
                summary: Example payload
                value:
                  id: 789e0123-e89b-12d3-a456-426614174999
                  externalID: REQ-2024-001234
                  amount: '15000.50'
                  currency: ARS
                  direction: Inbound
                  status: PENDING
                  type: request
                  accountId: 550e8400-e29b-41d4-a716-446655440123
                  fromName: Juan Pérez
                  toName: María García
                  fromCBU: '1700015400000000000010'
                  toCBU: '1100015400000000000021'
                  error: Insufficient funds on destination account
                  fromCUIT: '20123456789'
                  toCUIT: '27987654321'
                  concept: Payment for services
                  coelsaCode: COELSA123456
tags:
  - name: Transactions
    description: >-
      Transaction Management - Create and manage transactions in the HG.Cash
      system. All transaction 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.
