Pular para o conteúdo principal
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:

Credenciais da API

Credenciais de API e token de acesso válidos para autenticação.

Configuração da conta

Configuração adequada da conta para o país de destino e verificação da empresa.

Lista branca de IPs

Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

Endpoint do webhook

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) quanto offline e, independentemente do método escolhido, dois modos de criação estão disponíveis:
  • Criação individual : 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 : 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.
ImportanteDepó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:
PaísMoradores locaisResidentes estrangeirosProprietário da contaAliasNome de exibição da transferência bancária
Argentina✅✅
  • FBO = Residentes estrangeiros
  • DDA = Residentes Locais
Criação de até 1 alias
  • Nome do beneficiário (fornecido durante a criação da Virtual Account, se argentino)
  • Nome legal da entidade Localpayment (em todos os outros casos)
Brasil✅✅
  • FBO = Residentes estrangeiros
  • DDA = Residentes Locais
N / DNome da entidade legal da Localpayment
Chile✅✅FBON / DNome da entidade legal da Localpayment
Colômbia✅✅FBOChave padrãoNome da entidade legal da Localpayment
México✅✅DDA = Residentes LocaisN / DNome da entidade legal da Localpayment
Peru✅✅FBON / DNome da entidade legal da Localpayment
Costa Rica✅✅FBON / DNome da entidade legal da Localpayment

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:

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

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.

Parâmetros-chave da solicitação

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

Exemplo de solicitação

Abaixo segue um exemplo de uso curl:
curl
Veja todos os parâmetros disponíveis 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 assim que o processo de ativação for concluído.

Campos de resposta principais

Resposta de erro

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

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.

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:

Exemplo de solicitação

Abaixo segue um exemplo de uso curl:
curl
Veja todos os parâmetros disponíveis 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.

Campos de resposta principais

Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:
Para obter uma lista completa dos códigos de status e seus significados, consulte a documentação de Status da Transação.

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.

Para Virtual Accounts individuais

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.

Para contas criadas em lote

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).

Próximos passos

Acompanhe o status da sua Virtual Account

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.

Instruções de pagamento

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.

Ativar/Desativar uma Virtual Account

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.

Excluir uma Virtual Account

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.

Última modificação em 12 de novembro de 2026