> ## 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 (Venezuela) > Credit an operative USDT account. `amount` is a positive decimal string, not a JSON number. More than 8 fractional digits are rounded down to 8 and are not rejected. `montoFiat` and `tasaCompra` are VES metadata. When the payment integration is not configured, the API returns `500` with `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, including when `bancoPago` is omitted, and no transaction is created. `502` `VE_BANKS_PROVIDER_ERROR` happens only when `bancoPago` is sent. The bank list is checked before a transaction row exists. That response does not create a row and does not cancel one. `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` and `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` mean a row already exists, that row is cancelled, and the response is `502`. Required: `accountId`, `amount`. Optional: `bancoPago`, `webhookUrl`. `bancoPago` must be an exact `onramp.banks[].name` from `GET /ve/banks`. It is not the numeric id and not a `country.banks[].label`. Omit it to leave the payer bank unset. An unknown name or a raw id returns `400` with `code: VE_INBOUND_INVALID_BANCO_PAGO`. Success is `201` with `id`, `status: pending`, `amount`, `orden_id`, and `montoFiat` / `tasaCompra` only when the create response includes them. A missing account returns `404`. No access returns `403`. `Bloqueada` or `Cerrada` returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. An unsupported account or a non-USDT currency returns `400`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /ve/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=` 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: Venezuela description: USDT cash-in and payouts for Venezuela - name: Checkouts description: Hosted checkout sessions for AR, BR, CL, BO, and CO - name: Claims description: Dispute claims with transfer receipt evidence paths: /ve/transactions/inbound: post: tags: - Venezuela summary: Create inbound transaction (Venezuela) description: > Credit an operative USDT account. `amount` is a positive decimal string, not a JSON number. More than 8 fractional digits are rounded down to 8 and are not rejected. `montoFiat` and `tasaCompra` are VES metadata. When the payment integration is not configured, the API returns `500` with `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, including when `bancoPago` is omitted, and no transaction is created. `502` `VE_BANKS_PROVIDER_ERROR` happens only when `bancoPago` is sent. The bank list is checked before a transaction row exists. That response does not create a row and does not cancel one. `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` and `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` mean a row already exists, that row is cancelled, and the response is `502`. Required: `accountId`, `amount`. Optional: `bancoPago`, `webhookUrl`. `bancoPago` must be an exact `onramp.banks[].name` from `GET /ve/banks`. It is not the numeric id and not a `country.banks[].label`. Omit it to leave the payer bank unset. An unknown name or a raw id returns `400` with `code: VE_INBOUND_INVALID_BANCO_PAGO`. Success is `201` with `id`, `status: pending`, `amount`, `orden_id`, and `montoFiat` / `tasaCompra` only when the create response includes them. A missing account returns `404`. No access returns `403`. `Bloqueada` or `Cerrada` returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. An unsupported account or a non-USDT currency returns `400`. operationId: createVeInboundTransaction requestBody: required: true content: application/json: schema: type: object required: - accountId - amount properties: accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' bancoPago: type: string description: >- Exact `onramp.banks[].name` from `GET /ve/banks`. Not the numeric id. example: ONRAMP_BANK_NAME webhookUrl: type: string format: uri example: accountId: YOUR_ACCOUNT_UUID amount: '100.5' bancoPago: ONRAMP_BANK_NAME responses: '201': description: Cash-in created content: application/json: schema: $ref: '#/components/schemas/VenezuelaInboundCreated' example: id: 550e8400-e29b-41d4-a716-446655440000 status: pending amount: '100.5' orden_id: 1000 '400': description: >- Validation failed, the account is not supported, the currency is not USDT, or `bancoPago` is not an on-ramp bank name (`VE_INBOUND_INVALID_BANCO_PAGO`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaProviderError' - type: object required: - error properties: error: type: string examples: invalid_banco_pago: summary: bancoPago is not an on-ramp bank name value: error: >- bancoPago must match an on-ramp bank name from GET /ve/banks (onramp.banks[].name). code: VE_INBOUND_INVALID_BANCO_PAGO type: validation_error unsupported_account: summary: Account is not supported value: error: Account is not supported for this operation currency: summary: Currency is not USDT value: error: Account currency must be USDT for this operation '401': description: Unauthorized '403': description: >- No access, the account is `Bloqueada` or `Cerrada`, or the account is `Restringida` content: application/json: schema: oneOf: - type: object required: - error properties: error: type: string - type: object required: - error - code properties: error: type: string code: type: string enum: - ACCOUNT_NOT_OPERATIVE - RESTRICTED examples: no_access: summary: No access value: error: You do not have access to this account not_operative: 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 content: application/json: schema: type: object required: - error properties: error: type: string example: Account not found '500': description: The payment integration is not configured, or an internal error content: application/json: schema: $ref: '#/components/schemas/VenezuelaProviderError' example: error: The payment integration is not configured. code: VE_BANKS_PROVIDER_NOT_CONFIGURED type: provider_error '502': description: >- `VE_BANKS_PROVIDER_ERROR` happens only when `bancoPago` is sent. The bank list is checked before a transaction row exists. That response does not create a row and does not cancel one. `VE_INBOUND_PROVIDER_CREATE_FAILED` and `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` mean a row already exists, that row is cancelled, and the response is 502. content: application/json: schema: $ref: '#/components/schemas/VenezuelaProviderError' examples: create_failed: summary: Cash-in could not be created value: error: Unable to complete this request with the payment provider. code: VE_INBOUND_PROVIDER_CREATE_FAILED type: provider_error missing_orden_id: summary: Create response had no order id value: error: >- The payment provider returned an incomplete response. Please try again or contact support. code: VE_INBOUND_PROVIDER_MISSING_ORDEN_ID type: provider_invalid_response banks_failed: summary: >- On-ramp bank list failed before a row exists, only when bancoPago is sent value: error: Unable to fetch banks from the payment provider. code: VE_BANKS_PROVIDER_ERROR type: provider_error components: schemas: VenezuelaUsdtAmount: type: string description: >- Positive USDT decimal string. Not a JSON number. More than 8 fractional digits are rounded down to 8 and are not rejected. VES amounts are not this field. pattern: ^\d+(\.\d+)?$ example: '100.5' VenezuelaInboundCreated: type: object required: - id - status - amount - orden_id properties: id: type: string format: uuid status: type: string enum: - pending amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' orden_id: type: integer montoFiat: type: string description: VES metadata. Included only when the create response has it. tasaCompra: type: string description: VES metadata. Included only when the create response has it. VenezuelaValidationError: 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 VenezuelaProviderError: type: object required: - error - code - type properties: error: type: string code: type: string enum: - VE_BANKS_PROVIDER_NOT_CONFIGURED - VE_BANKS_PROVIDER_ERROR - VE_INBOUND_INVALID_BANCO_PAGO - VE_INBOUND_PROVIDER_CREATE_FAILED - VE_INBOUND_PROVIDER_MISSING_ORDEN_ID type: type: string enum: - provider_error - provider_invalid_response - validation_error 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.