> ## 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. # Verificar destinatário (Venezuela) > Consulta um destinatário antes de um payout. Não cria uma transação, não reserva USDT e não salva uma conta bancária. Obrigatórios: `accountId` (conta USDT operativa da qual quem chama pode pagar), `email`, `documentoIdentidad`, `tipoDocumento`. Opcional: `numeroCuenta`. Quando enviado, `ready` significa que a verificação de identidade está aprovada e essa conta já está registrada. Quando omitido, `ready` significa aprovado e que já existe uma conta bancária registrada. `documentoIdentidad` é somente dígitos. A letra fica em `tipoDocumento` (`V`, `J`, `P` ou `E` de `GET /ve/banks`). Um prefixo correspondente `V-`, `J-`, `P-` ou `E-` é aceito e removido. Uma conta inexistente retorna `404`. Quem não pode pagar a partir dessa conta, ou uma conta que não é USDT da Venezuela, retorna `403`. Uma conta não operativa retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion` e `ciudad` são obrigatórios somente quando o e-mail ainda não está registrado (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). Quando esses campos estão presentes e o e-mail continua sem registro, a resposta é `kyc_not_started` sem `kyc_url`. Esta chamada não registra esse e-mail. Um documento que não corresponde a um e-mail existente retorna `400` com `code: VE_IDENTITY_UNCONFIRMED` e não inicia a verificação de identidade. O `status` de sucesso é `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started` ou `kyc_declined`. `kyc_declined` inclui `code: VE_KYC_DECLINED`. Para um e-mail que já está registrado e não tem sessão, esta chamada pode iniciar a verificação e retornar `kyc_url`. Para um destinatário existente, `kyc_not_started` retorna `kyc_url` quando uma URL de sessão foi emitida. `kyc_in_progress` inclui `kyc_url` somente quando o payload de status tem uma, ou quando um payout neste `accountId` já armazenou uma. Não leia essa URL em transações de outra conta. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /ve/recipients/kyc openapi: 3.1.0 info: title: HG.Cash API description: > # 🚀 API de transações HG.Cash API REST moderna para usuários criarem transações de saída a partir de suas contas. ## 🧾 Como funciona - A HG.Cash atribui contas ao seu usuário - Quando essas contas têm movimentação (entrada ou saída), a HG.Cash notifica o seu backend usando a URL de webhook configurada no painel - **Assinatura de webhooks (HMAC)**: Nas configurações da conta é possível gerar um segredo de assinatura. Quando configurado, cada POST de webhook inclui o cabeçalho `X-HG-Webhook-Signature: sha256=` com HMAC-SHA256 do corpo JSON usando o seu segredo. Verifique no seu endpoint para garantir autenticidade. - Para criar saques é necessário chamar o endpoint **Cash Out**: **Criar solicitação de transação** (`POST /transactions`) ## 📊 Primeiros passos 1. **Gere seu token de API** na página de configurações da conta 2. **Teste os endpoints** com a documentação interativa 3. **Implemente** nos seus serviços de backend (nunca exponha tokens no frontend) 4. **Monitore** a integração e trate erros adequadamente ## 🔐 Autenticação Esta API usa autenticação **Bearer Token**. Inclua o token de API do usuário no cabeçalho Authorization, por exemplo `Authorization: Bearer cash_your_token_here`. ## ⚠️ Segurança - Não compartilhe nem exponha o token de autenticação da API - Armazene tokens apenas em servidores backend seguros - Todas as chamadas devem ser feitas a partir de backends seguros - Se o token for comprometido, entre em contato com os administradores imediatamente 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 produção - url: http://dev.hg.cash/api/v1 description: Servidor de desenvolvimento security: - bearerAuth: [] tags: - name: Transações description: >- Gestão de transações — Criar e gerenciar transações no sistema HG.Cash. Todos os endpoints de transação exigem autenticação. - name: Contas description: >- Contas — Obter informações de conta e saldos do usuário autenticado. Todos os endpoints de conta exigem autenticação. - name: Dados de referência description: >- Dados de referência — Obter dados de referência como status e tipos de transação. Esses endpoints exigem autenticação. - name: Webhooks description: Webhooks — Notificações de eventos enviadas ao seu endpoint HTTP. - name: Brasil description: Brasil — Criar e consultar transações PIX (BRL). - name: Chile description: Chile — Checkout hospedado e payouts bancários (CLP). - name: Bolívia description: Bolívia — Cash-in com QR e payouts ACH (BOB). - name: Colômbia description: >- Colômbia — Cash-in com checkout hospedado e payouts bancários, chave Bre-B ou QR Bre-B (COP). - name: Venezuela description: Venezuela — Cash-in e payouts em USDT. - name: Checkouts description: Sessões de checkout hospedado para AR, BR, CL, BO e CO - name: Claims description: Reclamações com evidência de comprovante de transferência paths: /ve/recipients/kyc: post: tags: - Venezuela summary: Verificar destinatário (Venezuela) description: > Consulta um destinatário antes de um payout. Não cria uma transação, não reserva USDT e não salva uma conta bancária. Obrigatórios: `accountId` (conta USDT operativa da qual quem chama pode pagar), `email`, `documentoIdentidad`, `tipoDocumento`. Opcional: `numeroCuenta`. Quando enviado, `ready` significa que a verificação de identidade está aprovada e essa conta já está registrada. Quando omitido, `ready` significa aprovado e que já existe uma conta bancária registrada. `documentoIdentidad` é somente dígitos. A letra fica em `tipoDocumento` (`V`, `J`, `P` ou `E` de `GET /ve/banks`). Um prefixo correspondente `V-`, `J-`, `P-` ou `E-` é aceito e removido. Uma conta inexistente retorna `404`. Quem não pode pagar a partir dessa conta, ou uma conta que não é USDT da Venezuela, retorna `403`. Uma conta não operativa retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion` e `ciudad` são obrigatórios somente quando o e-mail ainda não está registrado (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). Quando esses campos estão presentes e o e-mail continua sem registro, a resposta é `kyc_not_started` sem `kyc_url`. Esta chamada não registra esse e-mail. Um documento que não corresponde a um e-mail existente retorna `400` com `code: VE_IDENTITY_UNCONFIRMED` e não inicia a verificação de identidade. O `status` de sucesso é `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started` ou `kyc_declined`. `kyc_declined` inclui `code: VE_KYC_DECLINED`. Para um e-mail que já está registrado e não tem sessão, esta chamada pode iniciar a verificação e retornar `kyc_url`. Para um destinatário existente, `kyc_not_started` retorna `kyc_url` quando uma URL de sessão foi emitida. `kyc_in_progress` inclui `kyc_url` somente quando o payload de status tem uma, ou quando um payout neste `accountId` já armazenou uma. Não leia essa URL em transações de outra conta. operationId: checkVeRecipientKyc requestBody: required: true content: application/json: schema: type: object required: - accountId - email - documentoIdentidad - tipoDocumento properties: accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID email: type: string format: email example: payer@example.com documentoIdentidad: type: string description: >- Somente dígitos. Um prefixo correspondente `V-`, `J-`, `P-` ou `E-` é removido. example: '00000000' tipoDocumento: type: string description: >- `value` do catálogo em `country.documentTypes`. `V`, `J`, `P` ou `E`. example: V numeroCuenta: type: string firstName: type: string lastName: type: string prefijoTelefono: type: string example: '+58' numeroTelefono: type: string example: '0000000000' direccion: type: string ciudad: type: string example: accountId: YOUR_ACCOUNT_UUID email: payer@example.com documentoIdentidad: '00000000' tipoDocumento: V responses: '200': description: Resultado da verificação. Não cria uma transação. content: application/json: schema: $ref: '#/components/schemas/VenezuelaRecipientKycResponse' examples: ready: summary: Aprovado e há uma conta bancária registrada value: status: ready not_registered: summary: O e-mail não está registrado value: status: kyc_not_started declined: summary: Verificação recusada value: status: kyc_declined code: VE_KYC_DECLINED '400': description: >- A validação falhou, faltam dados do destinatário (`VE_RECIPIENT_DETAILS_REQUIRED`), ou o documento não corresponde ao e-mail (`VE_IDENTITY_UNCONFIRMED`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaPreflightError' examples: details_required: summary: Um e-mail novo não tem nome, telefone, endereço ou cidade value: error: >- Name, phone, address, and city are required to register a new recipient. code: VE_RECIPIENT_DETAILS_REQUIRED identity: summary: O documento não corresponde ao e-mail value: error: >- The document does not match the email. Verification was not started. code: VE_IDENTITY_UNCONFIRMED '401': description: Não autorizado '403': description: >- Sem acesso, a conta não é USDT da Venezuela, a conta não está operativa (`ACCOUNT_NOT_OPERATIVE`), ou a conta está `Restringida` (`RESTRICTED`). 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: Não pode pagar a partir desta conta value: error: You do not have access to this account not_operative: summary: A conta não está operativa value: error: Account is not operative code: ACCOUNT_NOT_OPERATIVE restricted: summary: Account is restricted value: error: Account is restricted code: RESTRICTED '404': description: Conta não encontrada content: application/json: schema: type: object required: - error properties: error: type: string example: Account not found '500': description: Erro interno do servidor components: schemas: VenezuelaRecipientKycResponse: type: object required: - status properties: status: type: string enum: - ready - kyc_approved_no_account - kyc_in_progress - kyc_not_started - kyc_declined kyc_url: type: string format: uri description: >- Para um e-mail que já está registrado e não tem sessão, esta chamada pode iniciar a verificação e retornar esta URL. Para um destinatário existente, `kyc_not_started` inclui isto quando uma URL de sessão foi emitida. `kyc_in_progress` inclui somente quando o payload de status tem uma, ou quando um payout neste `accountId` já armazenou uma. Nunca é lida de transações de outra conta. Omitida em `kyc_not_started` se o e-mail não está registrado. code: type: string enum: - VE_KYC_DECLINED description: Presente somente quando `status` é `kyc_declined`. 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 VenezuelaPreflightError: type: object required: - error - code description: >- Devolvido quando um payout ou a verificação do destinatário é rejeitado antes de existir uma transação. A string `error` diz o que corrigir em uma falha de conta bancária ou de documento. properties: error: type: string code: type: string enum: - VE_RECIPIENT_DETAILS_REQUIRED - VE_IDENTITY_UNCONFIRMED - VE_KYC_DECLINED - VE_KYC_NOT_APPROVED - VE_INVALID_DOCUMENT - VE_INVALID_BANK - missing_cuenta_id - missing_terms securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token de autenticação da API do usuário com o formato `cash_<64-char-hex>`. Valor de exemplo `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.