Precisa criar cartões virtuais automaticamente para clientes, projetos ou contas empresariais? A API da Buvei permite que os desenvolvedores integrem a emissão de cartões virtuais aos seus próprios aplicativos, reduzindo o trabalho manual e facilitando a expansão do processo de criação de cartões.
Este guia apresenta todo o processo, desde a preparação da sua conta e a seleção de um BIN de cartão até a emissão de um cartão virtual e a confirmação de que ele está pronto para uso.
O que você precisa antes de emitir um cartão virtual
Antes de começar, certifique-se de ter:
- Uma conta Buvei com acesso à API habilitado
- Uma API Key e um API Secret
- Um endereço IP estático de saída aprovado para acesso à API
- Um endpoint HTTPS para receber notificações de Webhook
- Saldo suficiente na carteira para a emissão dos cartões desejados
Se você ainda não conhece a Buvei, registre uma conta e familiarize-se com o painel de gerenciamento de cartões antes de iniciar a integração.
Etapa 1: Cadastre-se na Buvei e adicione fundos à sua carteira
Crie uma conta Buvei
Acesse Buvei.com, crie uma conta, verifique seu endereço de e-mail e faça login no painel de controle.
Antes de continuar, confirme se o acesso à API está disponível para sua conta.
Adicione fundos à sua carteira
Abra a seção Wallet e escolha um método de depósito compatível com sua conta. Se disponível, você poderá depositar USDT pelas redes TRC20 ou ERC20.
Copie o endereço de depósito, verifique se a rede de transferência corresponde à rede selecionada e aguarde a chegada dos fundos. Confira seu saldo disponível antes de emitir um cartão.
Certifique-se de que sua carteira tenha fundos suficientes para cobrir o valor inicial de carregamento do cartão e quaisquer taxas aplicáveis.
Etapa 2: Obtenha suas credenciais de API e configure o acesso
Obtenha sua API Key e seu API Secret na área de configuração da API da sua conta Buvei.
A API Key identifica seu projeto, enquanto o API Secret é usado para assinar as solicitações. Mantenha seu API Secret protegido e nunca o exponha em códigos de frontend ou repositórios públicos.
Em seguida, forneça o endereço IP estático de saída utilizado pelo seu aplicativo para se conectar à Buvei, para que ele possa ser incluído na lista de permissões. Solicitações provenientes de endereços IP não aprovados podem ser rejeitadas.
Você também precisará de um endpoint HTTPS para receber notificações de Webhook. Essas notificações permitem que seu aplicativo responda quando a criação de um cartão for concluída.
Etapa 3: Autentique suas solicitações e consulte os BINs disponíveis
Antes de solicitar um cartão virtual, certifique-se de que a autenticação da sua API esteja configurada corretamente.
Cada solicitação deve incluir suas credenciais de API, um registro de data e hora, um nonce exclusivo e uma assinatura válida. Informações de autenticação ausentes ou incorretas podem fazer com que a solicitação seja rejeitada. Por isso, verifique esses dados antes de prosseguir com a emissão do cartão.
Encontre um BIN de cartão disponível
Antes de emitir um cartão, verifique quais BINs estão disponíveis para o seu projeto. Analise a bandeira do cartão, o país emissor, a moeda e quaisquer requisitos adicionais para o titular antes de escolher a opção mais adequada.
Um BIN determina características importantes do cartão, incluindo a bandeira, o país emissor e a moeda. As informações disponíveis também indicam se são necessários dados adicionais, como número de celular, endereço de e-mail, PIN, endereço de cobrança ou titular verificado.
Escolha um BIN adequado à finalidade pretendida e mantenha seu identificador disponível para a solicitação de emissão.
Verifique os requisitos do BIN selecionado antes de continuar. Diferentes BINs podem ter exigências de verificação distintas, e a moeda do cartão é determinada pelo BIN escolhido.
Etapa 4: Verifique os requisitos do titular do cartão
Antes de enviar uma solicitação de emissão, consulte os requisitos do BIN escolhido.
Alguns BINs exigem a verificação do titular do cartão, enquanto outros podem solicitar dados de contato específicos ou informações de cobrança. Se o KYC for obrigatório, conclua o processo de verificação aplicável e confirme se o titular foi aprovado.
Dependendo do BIN, talvez também seja necessário fornecer um número de celular, endereço de e-mail, PIN ou endereço de cobrança.
Preparar essas informações antecipadamente ajuda a evitar falhas desnecessárias nas solicitações. Não presuma que todos os cartões virtuais tenham os mesmos requisitos.
Etapa 5: Emita um cartão virtual pela API da Buvei
Depois de selecionar um BIN adequado e preparar as informações necessárias, prossiga com a emissão do cartão. Antes de enviar a solicitação, certifique-se de que todos os dados obrigatórios do titular estejam completos e que sua carteira tenha saldo suficiente.
A solicitação deve incluir o BIN selecionado, o valor do carregamento inicial e os dados obrigatórios do titular. Dependendo do BIN, outras informações também poderão ser necessárias. Se a verificação do titular for obrigatória, confirme se a pessoa correspondente foi aprovada antes de continuar.
Verifique o valor do carregamento inicial
O valor do carregamento inicial deve ser enviado na menor unidade da moeda. Por exemplo, um valor de 10.000 representa US$ 100,00.
O intervalo documentado vai de US$ 1,00 a US$ 40.000,00. As opções disponíveis também podem depender da sua conta e do BIN selecionado. Portanto, confirme os requisitos aplicáveis antes de enviar a solicitação.
Após o envio, a API retorna um identificador do cartão e um status inicial. A criação do cartão é assíncrona, portanto, uma solicitação bem-sucedida não significa necessariamente que o cartão já esteja pronto para uso.
Evite solicitações duplicadas de emissão de cartões
Se uma solicitação expirar por timeout, não envie imediatamente uma nova solicitação de emissão completamente diferente.
Quando houver suporte, uma chave de idempotência ajuda a identificar a mesma operação de emissão durante novas tentativas e reduz o risco de criar cartões duplicados. Reutilize a mesma chave para a mesma solicitação, seguindo os requisitos de autenticação da Buvei.
Se uma solicitação retornar um conflito, verifique se a operação original foi processada antes de tentar novamente.
Etapa 6: Confirme a criação do cartão por meio de um Webhook
Após enviar a solicitação de emissão, aguarde a notificação de Webhook CARD_CREATED da Buvei.
Um cartão recém-solicitado pode permanecer inicialmente em estado de criação pendente enquanto o provisionamento está em andamento. Quando a Buvei envia o evento CARD_CREATED, o processo de provisionamento foi concluído.
Seu aplicativo deve verificar a assinatura do Webhook, confirmar o tipo de evento, identificar o cartão correspondente e atualizar seus registros internos. Também deve estar preparado para lidar com notificações duplicadas e falhas temporárias de entrega.
Após receber a notificação, consulte o status atual do cartão por meio do serviço de detalhes de cartões da Buvei e confirme se ele está habilitado antes de considerá-lo pronto para uso.
Etapa 7: Solucione erros comuns da API da Buvei
Se a emissão do cartão falhar, verifique a mensagem de erro retornada e analise estes problemas comuns.
| Problema | O que verificar |
|---|---|
| Solicitação inválida | Informações obrigatórias, requisitos do BIN, valor do carregamento e endereço de cobrança |
| Falha de autenticação | Credenciais da API, registro de data e hora, nonce e assinatura da solicitação |
| Acesso negado | Lista de permissões de IP e permissões da conta |
| Conflito na solicitação | Nonce reutilizado ou chave de idempotência associada a detalhes diferentes da solicitação |
| Limite de requisições excedido | Limites de uso da API e intervalo entre novas tentativas |
| Criação do cartão atrasada | Entrega do Webhook e status atual do cartão |
Em caso de solicitação inválida, revise as informações obrigatórias e os detalhes do erro para identificar o que precisa ser corrigido. Para problemas de autenticação ou acesso, verifique o processo de assinatura, o registro de data e hora, a configuração de IP e as permissões da conta.
Se uma solicitação expirar por timeout ou retornar um conflito, determine se a solicitação de emissão original foi processada antes de enviar outra. Isso ajuda a evitar cartões duplicados.
Se a criação do cartão parecer atrasada, verifique se o Webhook foi recebido e consulte o status atual do cartão. Uma notificação atrasada, por si só, não significa que a emissão tenha falhado.
Conclusão
A API da Buvei permite integrar a emissão de cartões virtuais diretamente aos fluxos de trabalho empresariais existentes. Ao escolher o BIN adequado, preparar as informações necessárias do titular e verificar o status final de cada cartão, os desenvolvedores podem tornar o processo de emissão mais consistente e fácil de gerenciar.
Depois que a integração estiver configurada corretamente, a criação automatizada de cartões e as notificações de Webhook poderão ajudar as equipes a gerenciar uma demanda crescente por cartões com menos trabalho manual.
