> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar uma Virtual Account

Gere virtual accounts para clientes através da API da Localpayment. Suporte para processamento individual e em lote.

Gere virtual accounts para seus clientes de forma programática através da API da Localpayment. Ofereça suporte tanto à criação de contas individuais quanto ao processamento em lote de múltiplas contas.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Métodos de criação de Virtual Account

Oferecemos opções flexíveis para a criação de virtual accounts, adequadas a diferentes necessidades operacionais. Você pode criar virtual accounts tanto [**online (API)**](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md)  quanto [**offline**](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) e, independentemente do método escolhido, dois modos de criação estão disponíveis:

* [**Criação individual**](#option-1-individual-virtual-account-creation) : Gere virtual accounts individuais com configurações específicas, ideais para fluxos e cenários orientados pelo cliente que exigem personalização por conta.
* [**Criação em lote**](#option-2-create-virtual-accounts-in-batch) : Processe várias virtual accounts em uma única operação, otimizada para geração em massa de contas, integração em massa e cenários onde a eficiência do processamento é priorizada.

| País | On-line | Offline |
| :- | :- | :- |
| **[Argentina](https://docs.localpayment.com/pt-br/docs/argentina.md)** | ✔ | ✔ |
| **[Brasil](https://docs.localpayment.com/pt-br/docs/brazil.md)** | ✔ | — |
| **[Chile](https://docs.localpayment.com/pt-br/docs/chile.md)** | ✔ | ✔ |
| **[Colômbia](https://docs.localpayment.com/pt-br/docs/colombia.md)** | ✔ | — |
| **[Costa Rica (CRC e USD)](https://docs.localpayment.com/pt-br/docs/costa-rica.md)** | ✔ | ✔ |
| **[México (SPEI, SPID e TEF)](https://docs.localpayment.com/pt-br/docs/mexico.md)** | ✔ | ✔ |
| [**Peru (PEN e USD)**](https://docs.localpayment.com/pt-br/docs/peru.md) | ✔ | — |

> [!WARNING]
>
> **Importante**
>
> Depósitos em dinheiro não são aceitos. Contas virtuais só podem receber pagamentos eletrônicos. Qualquer depósito em dinheiro feito em uma conta virtual, seja em uma agência bancária, caixa eletrônico ou qualquer outro canal, não será creditado ao comerciante. Os pagadores devem enviar fundos exclusivamente por transferência bancária, utilizando os sistemas de pagamento eletrônico disponíveis em seu país.

***

## Requisitos do Beneficiário

Compreender as restrições de beneficiários é crucial para a criação bem-sucedida de virtual accounts. Cada país possui regulamentações específicas sobre quem pode ser listado como beneficiário da conta, o que impacta diretamente a forma como você estrutura suas operações de pagamento.

### Requisitos de residência por país

A tabela a seguir descreve quais tipos de beneficiários são aceitos em cada país:

<table>
  <thead>
    <tr>
      <th>
        País
      </th>

      <th>
        Moradores locais
      </th>

      <th>
        Residentes estrangeiros
      </th>

      <th>
        Proprietário da conta
      </th>

      <th>
        Alias
      </th>

      <th>
        Nome de exibição da transferência bancária
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Argentina
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        * **FBO** = Residentes estrangeiros
        * **DDA** = Residentes Locais
      </td>

      <td>
        Criação de até 1 alias
      </td>

      <td>
        * **Nome do beneficiário** (fornecido durante a criação da Virtual Account, se argentino)
        * **Nome legal da entidade Localpayment** (em todos os outros casos)
      </td>
    </tr>

    <tr>
      <td>
        Brasil
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        * **FBO** = Residentes estrangeiros
        * **DDA** = Residentes Locais
      </td>

      <td>
        N / D
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>

    <tr>
      <td>
        Chile
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        N / D
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>

    <tr>
      <td>
        Colômbia
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        Chave padrão
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>

    <tr>
      <td>
        México
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **DDA** = Residentes Locais
      </td>

      <td>
        N / D
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>

    <tr>
      <td>
        Peru
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        N / D
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>

    <tr>
      <td>
        Costa Rica
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        N / D
      </td>

      <td>
        **Nome da entidade legal da Localpayment**
      </td>
    </tr>
  </tbody>
</table>

> [!NOTE]
>
> ###
>
> **Notas**:
>
> * O termo "**Titular da Conta**" refere-se ao nome do titular legal da conta registrado no sistema bancário (o nome visível no nível do banco). **FBO** (Em Benefício de) significa que a conta é aberta em nome da Localpayment, mantendo fundos em benefício do cliente final. **DDA** (Conta de Depósito à Vista) significa que a conta é aberta diretamente em nome do beneficiário.
> * **Alias**: refere-se ao número de aliases (ou tipo de alias) que podem ser registrados para uma Virtual Account, quando suportados.
> * **Nome de exibição da transferência bancária**: refere-se ao nome que aparece para o pagador durante uma transferência eletrônica de fundos para a Virtual Account.

### Informações do beneficiário necessárias para criar uma Virtual Account

**Informações necessárias:**

* **Tipo de beneficiário**: Define se a Virtual Account pertence a um indivíduo ou a uma empresa:
  * INDIVIDUAL: Para uma conta pessoal.
  * COMPANY: Para uma entidade comercial/jurídica.
* **Nome do beneficiário**: Nome completo da pessoa ou razão social da empresa.
* **Documento do Beneficiário**: Informações oficiais de identificação para comprovar a identidade.
* **Endereço**: Endereço completo do beneficiário.
* **Site**: O endereço URL do site do beneficiário.

***

## Requisitos específicos de cada país

Os detalhes de implementação para Virtual Accounts variam conforme o país. Qualquer país não mencionado explicitamente segue o procedimento padrão, sem requisitos especiais. Revise esses requisitos antes da integração:

> [tab] Argentina
>
> | Propriedade | Descrição |
> | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `ARS` (Peso argentino) |
> | Valor mínimo da transação | ARS 1,00 |
> | Valor máximo da transação | Sem limite máximo. |
> | Formato de conta local | Cuenta Virtual Uniforme (CVU) |
> | Câmara de Compensação | COELSA |
> | Número máximo de Virtual Accounts | Ilimitado |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) |
>
> ### Formato da conta
>
> Na Argentina, o CVU (Clave Virtual Uniforme) é um código numérico de 22 dígitos usado por virtual accounts emitidas por PSPs (Prestadores de Serviços de Pagamento).
>
> **Estrutura:**
>
> * Posições 1-3: 3 dígitos - Código da entidade emissora (PSP).
> * Posições 4-7: 4 dígitos - Identificador do tipo de conta dentro do PSP.
> * Posição 8: 1 dígito - Dígito de verificação (checksum).
> * Posições 9-21: 13 dígitos - Número de conta exclusivo dentro do PSP.
> * Posição 22: 1 dígito – Dígito de controle (validador de checksum).
>
> **Exemplo**: `0000003112345678901234`

> [tab] Brasil
>
> | Propriedade | Descrição |
> | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `BRL` (Real brasileiro) |
> | Valor mínimo da transação | BRL 0,01 |
> | Valor máximo da transação | BRL 1.000.000,00 |
> | Formato de conta local | Código do banco, agência e número da conta (usados tanto pelo TED quanto pelo Pix). Para o Pix, o pagador pode usar alternativamente a Chave Pix (alias). |
> | Métodos de depósito aceitos | **Pix** e **TED** |
> | Câmara de Compensação | Pix, TED |
> | Número máximo de Virtual Accounts | Ilimitado |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account) |
>
> ### Formato da conta
>
> No Brasil, cada virtual account é identificada por uma **Pix Key** (alias) e aceita fundos recebidos tanto pela **Pix** quanto pela **TED**. Ambas as plataformas convergem para a mesma conta subjacente, e sua integração recebe a mesma notificação de webhook, independentemente da plataforma utilizada pelo pagador.
>
> **Tanto para transferências TED quanto Pix**, o pagador pode usar os três campos a seguir da resposta da API:
>
> * `beneficiary.bank.code` — o código bancário.
> * `beneficiary.bank.branch.code` — o código da filial (agência).
> * `beneficiary.bank.account.number` — o número da conta.
>
> **Somente para Pix**, o pagador pode usar alternativamente a **chave Pix** (alias) retornada em `beneficiary.bank.account.aliases`. Nenhum outro campo é obrigatório.
>
> **Estrutura da chave Pix:**
>
> Uma Pix Key pode ter um dos seguintes formatos:
>
> * **Número de celular**: 10 dígitos, o número de celular cadastrado do beneficiário.
> * **Endereço de e-mail**: o e-mail cadastrado do beneficiário.
> * **Chave aleatória**: Sequência alfanumérica gerada pelo sistema.
>
> **Notas**:
>
> * Contas individuais (PF) podem registrar até 5 Pix Keys, enquanto contas corporativas (PJ) podem registrar até 20.

> [tab] Chile
>
> > [!WARNING]
> >
> > Esteja ciente dos limites de transferência bancária e das regras de segurança locais para evitar rejeições de transações. Consulte o [guia do Chile](https://docs.localpayment.com/pt-br/docs/chile.md#banking-transaction-limits-and-rules) para obter informações detalhadas.
>
> | Propriedade | Descrição |
> | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `CLP` (Peso chileno) |
> | Valor mínimo da transação | CLP 1,00 |
> | Valor máximo da transação | CLP 7.000.000,00 |
> | Formato de conta local | Número da conta (entre 6 e 16 dígitos) |
> | Câmara de Compensação | CCA |
> | Número máximo de Virtual Accounts | Por favor, entre em contato com seu Gerente de Conta. |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) |

> [tab] Colômbia
>
> | Propriedade | Descrição |
> | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `COP` (Peso colombiano) |
> | Valor mínimo da transação | COP 1,00 |
> | Valor máximo da transação | COP 12.110.000,00 |
> | Formato de conta local | Sistema de Cuentas de Deposito (CUD) |
> | Câmara de Compensação | ACH Colombia |
> | Número máximo de Virtual Accounts | Ilimitado |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account) |

> [tab] Costa Rica
>
> | Propriedade | SINPE - IN | SINPE USD - IN |
> | - | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `CRC` (Colón costarriquenho) | `USD` (Dólar americano) |
> | Valor mínimo da transação | CRC 1,00 | USD 1,00 |
> | Valor máximo da transação | CRC 100.000.000.000,00 | USD 1.000.000.000.000,00 |
> | Formato de conta local | IBAN (22 caracteres) | IBAN (22 caracteres) |
> | Câmara de Compensação | SINPE (Banco Central de Costa Rica) | SINPE (Banco Central de Costa Rica) |
> | Número máximo de Virtual Accounts | Ilimitado | Ilimitado |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) |
>
> > [!NOTE]
> >
> > **Virtual Accounts da Costa Rica**
> >
> > * Virtual Accounts na Costa Rica **não podem ser desativadas** após serem criadas. Para parar de receber pagamentos, exclua a conta.
> > * O IBAN segue o formato `CR` + 20 dígitos (ex.: `CR75090100056938278310`).
> > * De acordo com as normas do SINPE, as Virtual Accounts sem movimentação por mais de 90 dias devem ser desativadas. Na prática, a desativação ocorre automaticamente na primeira terça-feira de cada mês, às 00:00, horário da Costa Rica (CR).

> [tab] México
>
> | Propriedade | SPEI | TEF | SPID |
> | :- | :- | :- | :- |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana | T+1 limite às 17h (UTC-6) | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `MXN` (Peso mexicano) | `MXN` (Peso mexicano) | `USD` (Dólar americano) |
> | Valor mínimo da transação | MXN 1,00 | MXN 1,00 | USD 1,00 |
> | Valor máximo da transação | MXN 1.000.000.000,00 | MXN 1.000.000.000,00 | USD 10.000.000,00 |
> | Formato de conta local | CLABE (Clave Bancaria Estandarizada) de 18 dígitos | CLABE (Clave Bancaria Estandarizada) de 18 dígitos | CLABE (Clave Bancaria Estandarizada) de 18 dígitos |
> | Câmara de Compensação | Banco do México | CECOBAN | Banco do México |
> | Número máximo de Virtual Accounts | Ilimitado | Ilimitado | Por favor, entre em contato com seu Gerente de Conta. |
> | Tipo de pagador | Pessoa Física e Jurídica | Pessoa Física e Jurídica | Empresa |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) | [On-line](#step-1-create-a-virtual-account), [Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) | [On-line](#step-1-create-a-virtual-account),[Offline](https://docs.localpayment.com/pt-br/docs/offline-virtual-account-creation.md) |
>
> > [!NOTE]
> >
> > **México SPID**
> >
> > Para solicitar uma Virtual Account para transferências em USD através do sistema SPID do México, observe o seguinte:
> >
> > * **Bancos disponíveis**: Consulte a lista de [bancos e códigos aceitos](https://docs.localpayment.com/pt-br/docs/mexico.md#bank-codes) para transferências.
> > * **Conta Localpayment**: Você precisa ter uma conta Localpayment em USD para receber fundos. Caso não possua uma, entre em contato com nossa equipe de suporte para que possamos configurá-la antes de prosseguir.
>
> ### Formato da conta
>
> No México, as Virtual Accounts devem usar o número padronizado CLABE (Clave Bancaria Estandarizada).
>
> **Estrutura:**
>
> * Posições 1-3: Código do Banco (atribuído pelo Banco de México)
> * Posições 4-6: Código da filial/escritório (localização geográfica)
> * Posições 7-17: Número da conta do cliente
> * Posição 18: Dígito de controle (soma de verificação)
>
> No México, as transferências bancárias locais em pesos mexicanos (MXN) são realizadas por meio de dois sistemas de compensação principais:
>
> * **SPEI (Sistema de Pagamentos Eletrônicos Interbancários)**: um sistema de pagamentos interbancários em tempo real operado pelo Banco do México, que permite transferências de fundos entre bancos em segundos. As transações geralmente são liquidadas instantaneamente e as contas devem ser identificadas usando o número CLABE padronizado.
>
> * **TEF (Transferência Eletrônica de Fundos):** um método de pagamento no México, operado pelo CECOBAN, utilizado para transferências interbancárias, em que as transações são processadas no próximo dia útil. Requer o número de conta padronizado do CLABE para identificação, está disponível apenas em dias úteis, de acordo com o calendário bancário mexicano, e é comumente utilizado para pagamentos que não são urgentes, como desembolsos programados de fornecedores ou transferências recorrentes em que a liquidação imediata não é necessária.
>
> Para transferências em dólares americanos (USD) entre contas bancárias mexicanas, fornecemos acesso ao SPID.
>
> * **SPID (Sistema de Pagos Interbancarios en Dolares):** é o sistema de pagamentos mexicano especializado em transferências interbancárias domésticas em dólares americanos. Ele permite que empresas com sede no México movimentem fundos em USD de forma eficiente entre contas mantidas em diferentes bancos dentro do país.
>
> Como funciona o **SPID**:
>
> * **Horário de processamento:** Disponível em dias úteis bancários mexicanos, entre 8h e 17h (UTC -6).  As transações são processadas em lotes ao longo do dia.
>
> * **Requisito de conta:** As transações são processadas usando o número CLABE padronizado da conta em USD do destinatário.
>
> * **Aplicações típicas:** Ideal para pagamentos B2B, liquidações com fornecedores internacionais e outras operações de tesouraria corporativa onde os fundos devem permanecer em USD.

> [tab] Peru
>
> | Propriedade | CCI-In | CCI-In USD |
> | - | - | - |
> | Confirmação de pagamento do SLA | Em tempo real, 24 horas por dia, 7 dias por semana | Em tempo real, 24 horas por dia, 7 dias por semana |
> | Processamento de moeda | `PEN` (Sol peruano) | `USD` (Dólar americano) |
> | Valor mínimo da transação | PEN 1,00 | USD 1,00 |
> | Valor máximo da transação | PEN 30.000,00 | USD 10.000,00 |
> | Formato de conta local | Codigo de Cuenta Interbancario (CCI) | Codigo de Cuenta Interbancario (CCI) |
> | Câmara de Compensação | CCE | CCE |
> | Número máximo de Virtual Accounts | Ilimitado | Ilimitado |
> | Modelo de Criação de Virtual Account | [On-line](#step-1-create-a-virtual-account) | [On-line](#step-1-create-a-virtual-account) |
>
> > [!WARNING]
> >
> > **Importante:**
> >
> > * A moeda (PEN ou USD) da sua virtual account é determinada pela configuração da sua conta Localpayment.
> >
> > * Se você precisar receber payins em sua virtual account que excedam 30.000 PEN, entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com).
>
> ### Formato da conta
>
> No Peru, as virtual accounts usam o formato CCI (Código de Cuenta Interbancario), que é um código de conta interbancária padronizado de 20 dígitos.
>
> **Estrutura:**
>
> * Posições 1-3: 3 dígitos - Código do banco (atribuído pela SBS - Superintendencia de Banca, Seguros y AFP)
> * Posições 4 a 6: 3 dígitos - Número da filial
> * Posições 7-18: 12 dígitos - Número de conta único dentro do banco
> * Posição 19-20: 2 dígitos - Dígitos de controle (validador de checksum)
>
> **Exemplo**: `92250610000000101419`

***

## Etapa 1: Crie uma Virtual Account

### Opção 1: Criação de Virtual Account Individual

Crie Virtual Accounts individuais com configurações detalhadas para clientes ou transações específicas.

Para criar uma conta virtual, você precisará enviar um `POST` Solicitação ao endpoint [Criar uma Conta Virtual](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md).

#### Parâmetros-chave da solicitação

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| externalId | Identificador único atribuído pelo comerciante para referenciar a Virtual Account. | ✅ |
| accountNumber | Número da conta do comerciante à qual a Virtual Account será vinculada ou associada. | ✅ |
| country | País onde a Virtual Account será criada. | ✅ |
| beneficiary | Objeto contendo informações pessoais do beneficiário (tipo de beneficiário, nome, documento, endereço, site). | ✅ |

#### Exemplo de solicitação

Abaixo segue um exemplo de uso `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country": "ARG",
  "beneficiary": {
    "type": "COMPANY",
    "document": {
      "id": "30-71234567-9",
      "type": "CUIT"
    },
    "name": "ACME INTERNATIONAL LTD",
    "lastName": "",
    "fullName": "ACME INTERNATIONAL LTD",
    "address": {
      "street": "Av. Corrientes",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "CABA",
      "country": "Argentina"
    },
    "website": "https://yongxin.technology.com"
  },
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "{{accountNumber}}"
}
'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md) na solicitação.

#### Resposta bem-sucedida

Uma solicitação bem-sucedida resultará na API retornando um código de status de `100`, com o status da conta inicialmente definido como `INPROGRESS`. A conta virtual permanecerá nesse estado durante a ativação e passará para um dos [status disponíveis](https://docs.localpayment.com/pt-br/docs/get-virtual-account-status.md) assim que o processo de ativação for concluído.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "internalId": "5ba31ea0-669b-43f6-88a1-1601f3cade0a",
  "accountNumber": "{{accountNumber}}",
  "country": "ARG",
  "currency": "ARS",
  "beneficiary": {
    "type": "COMPANY",
    "name": "ACME INTERNATIONAL LTD",
    "fullName": "ACME INTERNATIONAL LTD",
    "lastName": "",
    "document": {
      "type": "CUIT",
      "id": "30-71234567-9"
    },
    "address": {
      "street": "Av. Corrientes",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "CABA",
      "country": "Argentina"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}
```

#### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `externalId` | Um identificador único para a transação em seu sistema. **Ele será usado para realizar outras operações, como obter o status da Virtual Account**. |
| `internalId` | Um identificador único para a transação no sistema da Localpayment. |
| `status` | Objeto com informações sobre o status da Virtual Account. |
| `status.code` | O código de status (por exemplo, `100` para `INPROGRESS`). |
| `date.processedDate` | Quando o processamento da transação começou. |

#### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f5c4529e-67c1-43e0-bc2a-97250e736c98",
  "internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}
```

#### Tempo de ativação da conta

O tempo de ativação de virtual accounts varia conforme o país. Abaixo, seguem as estimativas para que as contas estejam ativas e prontas para receber pagamentos:

* **Argentina**: Até 6 segundos
* **Brasil**: Até 15 minutos
* **Chile**: Até 6 segundos
* **Colômbia**: Até 6 segundos
* **México**: Até 6 segundos
* **Peru**: Até 6 segundos

### Opção 2: Criar Virtual Accounts em lote

Gere várias contas virtuais em uma única solicitação de API para operações em massa eficientes. Para criar contas virtuais em massa, você precisará enviar um `POST` Solicitação ao endpoint [Criar contas virtuais em lote](https://docs.localpayment.com/pt-br/reference/request-batch.md).

> [!NOTE]
>
> ###
>
> Somente contas do mesmo país podem ser criadas em uma única solicitação em lote.

#### Parâmetros-chave da solicitação

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| externalId | Identificador único atribuído pelo comerciante para referenciar a Virtual Account. | ✅ |
| accountNumber | Número da conta do comerciante à qual a Virtual Account será vinculada ou associada. | ✅ |
| country | País onde a Virtual Account será criada. | ✅ |
| beneficiary | Objeto contendo informações pessoais do beneficiário. | ✅ |
| accounts | Matriz contendo as subcontas individuais e seus respectivos beneficiários associados à Virtual Account. | |

#### Exemplo de solicitação

Abaixo segue um exemplo de uso `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account-batch \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
  "accountNumber": "{{accountNumber}}",
  "country": "MEX",
  "name": "Virtual Account",
  "accounts": [
    {
      "externalId": "9210b519-5c29-4419-8d28-04f7543a914f",
      "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
          "id": "EXTF900101NI1",
          "type": "RFC"
        }
      }
    },
    {
      "externalId": "e4914217-41bc-49a5-b2f8-df950bf9bae7",
      "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Alicia",
        "lastname": "Doe",
        "document": {
          "id": "EXTF900101NI2",
          "type": "RFC"
        }
      }
    }
  ]
}
'
'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/request-batch.md) na solicitação.

#### Resposta bem-sucedida

Uma solicitação bem-sucedida resultará na API retornando um código de status de `100`, com o status da conta definido como `INPROGRESS`.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
  "internalId": "1748f8f8-dcac-4547-b3fb-7d6529245d84",
  "accountNumber": "{{accountNumber}}",
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Batch Process Virtual Account in progress"
  },
  "comment": "For obtaining the asynchronous response, kindly submit a request to the service after a brief interval. GET {api_environment_url}/api/virtual-account-batch/7facbbbf-d279-4ab5-9aeb-7583fa3f35ec"
}
```

#### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `externalId` | Um identificador único para a transação em seu sistema. **Ele será usado para realizar outras operações, como obter o status da Virtual Account**. |
| `internalId` | Um identificador único para a transação no sistema da Localpayment. |
| `status` | Objeto com informações sobre o status da Virtual Account. |
| `status.code` | O código de status (por exemplo, `100` para `INPROGRESS`). |
| `date.processedDate` | Quando o processamento da transação começou. |

#### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "timestamp": "2025-01-03T22:03:39.657+00:00",
  "status": 400,
  "error": "Bad Request.",
  "message": "External ID already used - Duplication",
  "path": "/virtual-account/batch"
}
```

Para obter uma lista completa dos códigos de status e seus significados, consulte a documentação de [Status da Transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md).

***

## Etapa 2. Acompanhe o status da sua Virtual Account

Monitorar o status de suas virtual accounts é essencial para manter operações de pagamento otimizadas. O Localpayment oferece recursos abrangentes de rastreamento para contas individuais e criadas em lote por meio de endpoints de API consistentes e atualizações de status em tempo real.

> [card] [Para Virtual Accounts individuais](https://docs.localpayment.com/pt-br/docs/get-virtual-account-status.md#method-1-check-individual-virtual-account-status)
>
> Para verificar o status de uma Virtual Account individual, você precisará enviar uma solicitação `GET` ao endpoint [Obtenha o status da sua Virtual Account](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md).

> [card] [Para contas criadas em lote](https://docs.localpayment.com/pt-br/docs/get-virtual-account-status.md#method-2-check-batch-virtual-account-status)
>
> Para monitorar o status de processamento de Virtual Accounts criadas em lote, você precisará enviar uma solicitação `GET` ao endpoint [Obtenha o status da Virtual Account (em lote)](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status-batch.md).

## Próximos passos

> [card] [Acompanhe o status da sua Virtual Account](https://docs.localpayment.com/pt-br/docs/get-virtual-account-status.md)
>
> Monitore o ciclo de vida de suas virtual accounts para manter as operações de pagamento em ótimas condições. Aprenda sobre os diferentes tipos de status e entenda o que cada um significa para suas capacidades de processamento de pagamentos.

> [card] [Instruções de pagamento](https://docs.localpayment.com/pt-br/docs/payment-instructions.md)
>
> Forneça aos pagadores os dados corretos do beneficiário retornados na resposta da API Get Virtual Account Status para processar os pagamentos corretamente. Consulte as instruções específicas de cada país para garantir a execução precisa e em conformidade com as normas.

> [card] [Ativar/Desativar uma Virtual Account](https://docs.localpayment.com/pt-br/docs/activate-deactivate-virtual-account.md)
>
> Gerencie a disponibilidade da conta ativando ou desativando Virtual Accounts temporariamente. Isso é útil para empresas sazonais, manutenção de contas ou suspensões temporárias.

> [card] [Excluir uma Virtual Account](https://docs.localpayment.com/pt-br/docs/delete-virtual-account.md)
>
> Desative permanentemente uma Virtual Account. Isso impede todos os pagamentos futuros para ela, mas mantém todo o seu histórico. A ação é irreversível. Use para contas que não são mais necessárias; crie uma nova para retomar as operações.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.