> ## 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. # Check recipient (Venezuela) > Check a recipient before a payout. This does not create a transaction, does not reserve USDT, and does not save a bank account. Required: `accountId` (operative USDT account the caller can pay from), `email`, `documentoIdentidad`, `tipoDocumento`. Optional: `numeroCuenta`. When `numeroCuenta` is sent, `ready` means identity verification is approved and that account is already on file. When it is omitted, `ready` means approved and a bank account is already on file. `documentoIdentidad` is digits only. The letter belongs in `tipoDocumento` (`V`, `J`, `P`, or `E` from `GET /ve/banks`). A matching `V-`, `J-`, `P-`, or `E-` prefix is accepted and stripped. A missing account returns `404`. A caller who cannot pay from that account, or an account that is not a Venezuela USDT account, returns `403`. A non-operative account returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion`, and `ciudad` are required only when the email is not already registered (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). When those fields are present and the email is still not registered, the response is `kyc_not_started` without `kyc_url`. This call does not register that email. A document that does not match an existing email returns `400` with `code: VE_IDENTITY_UNCONFIRMED` and does not start identity verification. Success `status` is `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started`, or `kyc_declined`. `kyc_declined` includes `code: VE_KYC_DECLINED`. For an email that is already registered and has no session, this call can start verification and return `kyc_url`. For an existing recipient, `kyc_not_started` returns `kyc_url` when a session URL was issued. `kyc_in_progress` includes `kyc_url` only when the status payload has one, or when a payout on this `accountId` already stored one. Do not read that URL from another account's transactions. ## OpenAPI ````yaml /api-reference/openapi.yaml post /ve/recipients/kyc 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/recipients/kyc: post: tags: - Venezuela summary: Check recipient (Venezuela) description: > Check a recipient before a payout. This does not create a transaction, does not reserve USDT, and does not save a bank account. Required: `accountId` (operative USDT account the caller can pay from), `email`, `documentoIdentidad`, `tipoDocumento`. Optional: `numeroCuenta`. When `numeroCuenta` is sent, `ready` means identity verification is approved and that account is already on file. When it is omitted, `ready` means approved and a bank account is already on file. `documentoIdentidad` is digits only. The letter belongs in `tipoDocumento` (`V`, `J`, `P`, or `E` from `GET /ve/banks`). A matching `V-`, `J-`, `P-`, or `E-` prefix is accepted and stripped. A missing account returns `404`. A caller who cannot pay from that account, or an account that is not a Venezuela USDT account, returns `403`. A non-operative account returns `403` with `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` returns `403` with `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion`, and `ciudad` are required only when the email is not already registered (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). When those fields are present and the email is still not registered, the response is `kyc_not_started` without `kyc_url`. This call does not register that email. A document that does not match an existing email returns `400` with `code: VE_IDENTITY_UNCONFIRMED` and does not start identity verification. Success `status` is `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started`, or `kyc_declined`. `kyc_declined` includes `code: VE_KYC_DECLINED`. For an email that is already registered and has no session, this call can start verification and return `kyc_url`. For an existing recipient, `kyc_not_started` returns `kyc_url` when a session URL was issued. `kyc_in_progress` includes `kyc_url` only when the status payload has one, or when a payout on this `accountId` already stored one. Do not read that URL from another account's transactions. 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: >- Digits only. A matching `V-`, `J-`, `P-`, or `E-` prefix is stripped. example: '00000000' tipoDocumento: type: string description: >- Catalogue `value` from `country.documentTypes`. `V`, `J`, `P`, or `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: Recipient check result. Does not create a transaction. content: application/json: schema: $ref: '#/components/schemas/VenezuelaRecipientKycResponse' examples: ready: summary: Approved and a bank account is on file value: status: ready not_registered: summary: Email is not registered value: status: kyc_not_started declined: summary: Verification declined value: status: kyc_declined code: VE_KYC_DECLINED '400': description: >- Validation failed, recipient details are required (`VE_RECIPIENT_DETAILS_REQUIRED`), or the document does not match the email (`VE_IDENTITY_UNCONFIRMED`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaPreflightError' examples: details_required: summary: New email is missing name, phone, address, or city value: error: >- Name, phone, address, and city are required to register a new recipient. code: VE_RECIPIENT_DETAILS_REQUIRED identity: summary: Document does not match the email value: error: >- The document does not match the email. Verification was not started. code: VE_IDENTITY_UNCONFIRMED '401': description: Unauthorized '403': description: >- No access, the account is not a Venezuela USDT account, the account is not operative (`ACCOUNT_NOT_OPERATIVE`), or the account is `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: Cannot pay from this account 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: Internal server error 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: >- For an email that is already registered and has no session, this call can start verification and return this URL. For an existing recipient, `kyc_not_started` includes this when a session URL was issued. `kyc_in_progress` includes it only when the status payload has one, or when a payout on this `accountId` already stored one. Never taken from another account's transactions. Omitted on `kyc_not_started` for an email that is not registered. code: type: string enum: - VE_KYC_DECLINED description: Present only when `status` is `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: >- Returned when a payout or recipient check is rejected before a transaction exists. The `error` string says what to fix for a bank-account or document failure. 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: > 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.