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.
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ís | Moradores locais | Residentes estrangeiros | Proprietário da conta | Alias | Nome de exibição da transferência bancária |
|---|---|---|---|---|---|
| Argentina | ✅ | ✅ |
| Criação de até 1 alias |
|
| Brasil | ✅ | ✅ |
| N / D | Nome da entidade legal da Localpayment |
| Chile | ✅ | ✅ | FBO | N / D | Nome da entidade legal da Localpayment |
| Colômbia | ✅ | ✅ | FBO | Chave padrão | Nome da entidade legal da Localpayment |
| México | ✅ | ✅ | DDA = Residentes Locais | N / D | Nome da entidade legal da Localpayment |
| Peru | ✅ | ✅ | FBO | N / D | Nome da entidade legal da Localpayment |
| Costa Rica | ✅ | ✅ | FBO | N / D | Nome 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:- Argentina
- Brasil
- Chile
- Colômbia
- Costa Rica
- México
- Peru
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).
0000003112345678901234Etapa 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 umPOST 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 usocurl:
curl
Resposta bem-sucedida
Uma solicitação bem-sucedida resultará na API retornando um código de status de100, 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 umPOST Solicitação ao endpoint Criar contas virtuais 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 usocurl:
curl
Resposta bem-sucedida
Uma solicitação bem-sucedida resultará na API retornando um código de status de100, 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: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.

