> ## 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 Inbound Transaction (Brazil)

> Create an inbound transaction to receive a payment. Returns a QR code for the payer to scan.
Account must be a Brazil (BRL) account. Transaction starts in `pending` status until payment is confirmed.




## OpenAPI

````yaml /api-reference/openapi.es.yaml post /br/transactions/inbound
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=<hex>` 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: Checkout hospedado y payouts bancarios para Chile (CLP)
  - name: Bolivia
    description: Cash-in con QR y payouts ACH para Bolivia (BOB)
  - name: Checkouts
    description: Sesiones de checkout hospedado para AR, BR, CL y BO
paths:
  /br/transactions/inbound:
    post:
      tags:
        - Brazil
      summary: Create Inbound Transaction (Brazil)
      description: >
        Create an inbound transaction to receive a payment. Returns a QR code
        for the payer to scan.

        Account must be a Brazil (BRL) account. Transaction starts in `pending`
        status until payment is confirmed.
      operationId: createBrInboundTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundTransactionRequest'
      responses:
        '201':
          description: Transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundTransactionResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Account not found
        '502':
          description: Payment provider error or invalid provider response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrazilProviderError'
components:
  schemas:
    InboundTransactionRequest:
      type: object
      description: >-
        Request to create an inbound transaction (receive payment) for Brazil
        BRL accounts
      required:
        - accountId
        - amount
        - email
      properties:
        accountId:
          type: string
          format: uuid
          description: ID of the account to receive funds into
        amount:
          type: number
          format: decimal
          description: Amount to receive (positive)
        email:
          type: string
          format: email
          description: Payer email for the charge
        webhookUrl:
          type: string
          format: uri
          description: Optional URL to receive status updates
    InboundTransactionResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
          description: HG.Cash transaction ID
        qrCode:
          type: string
          description: QR code string for the payer to scan (base64 or PIX string)
        pixCopiaECola:
          type: string
          description: PIX copy-paste string (alternative to QR code)
        status:
          type: string
          enum:
            - pending
    BrazilProviderError:
      type: object
      required:
        - error
        - code
        - type
      description: >-
        Safe provider-related error (no internal details or duplicate message
        fields)
      properties:
        error:
          type: string
          description: Human-readable message for clients
        code:
          type: string
          description: Stable machine-readable code (e.g. BR_INBOUND_PROVIDER_MISSING_TXID)
        type:
          type: string
          description: Error category (e.g. provider_error, provider_invalid_response)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        User API authentication token with format `cash_<64-char-hex>`. Sample
        value
        `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`.

````