# Pré-requisitos para Pagamentos no Brasil Antes de poder usar nossa solução OFPI e começar a coletar pagamentos, você precisará: 1. Inscrever-se para uma Conta Belvo. 2. Criar suas chaves secretas de Pagamentos. 3. Registrar seu webhook para que possamos informá-lo sobre eventos importantes durante o processo de pagamento, como confirmações de pagamento. 4. Registrar uma conta bancária que receberá os fundos. 5. Preparar URLs de callback. Estas são URLs para as quais o usuário deve ser redirecionado quando concluir ou cancelar um pagamento, ou se ocorrer um erro durante o processo de pagamento. ## Inscreva-se para uma Conta Belvo Para começar a usar o Belvo, você precisa criar uma conta Belvo e gerar suas chaves de API. 1. Acesse a página de inscrição do Belvo e preencha os campos obrigatórios. 1. Verifique sua caixa de entrada para um e-mail nosso e confirme seu endereço de e-mail. A linha de assunto será: **[Belvo] Please Confirm Your Email Address** ✳️ Incrível! Assim que você clicar no link no e-mail, será redirecionado para o dashboard do Belvo! No dashboard, você pode configurar sua conta, verificar seus registros de atividade e gerar suas chaves de API do Belvo. ## Gere suas chaves de API Agora que você tem uma conta - vamos gerar algumas chaves de API para começar a trabalhar com a Belvo. Para gerar suas chaves de API: 1. No ambiente de Produção, vá para a seção Ferramentas de Desenvolvedor - Chaves de API do dashboard. 2. Clique na aba **Chaves de API de Pagamentos**. 3. Clique em **Gerar Chaves de API**, o que gerará automaticamente suas chaves de API. 4. No pop-up, clique no botão **Baixar chaves de API**. Certifique-se de armazená-las em um local seguro. Coleção Postman Para ajudar com suas solicitações diárias, temos uma Coleção Pública do Postman especialmente para você usar. Apenas certifique-se de já ter uma conta no Postman, então: 1. Faça um fork da coleção para o seu workspace (instruções oficiais de fork do Postman). 2. Faça um fork do arquivo de variáveis de ambiente em branco para o seu workspace. 3. Preencha as variáveis de ambiente com suas chaves de API da Belvo. ## Registrar um webhook Nossas soluções de pagamento utilizam webhooks para informá-lo sobre o progresso dos seus pagamentos, quaisquer erros que ocorram e quando um pagamento é concluído com sucesso. Assim, você precisará configurar pelo menos um webhook para receber eventos da Belvo. Seu servidor deve responder com um `200 OK` aos eventos de webhook. Múltiplas URLs de Webhook Você pode registrar múltiplas URLs de webhook para sua organização. Quando várias URLs são registradas, **todas as URLs de webhook registradas receberão a mesma notificação de evento** para cada evento de webhook. Isso permite que você envie notificações para diferentes sistemas ou ambientes simultaneamente. Se nosso sistema não receber o código de status `200`, ele tentará enviar a solicitação novamente automaticamente. Esse processo de tentativa ocorrerá até três vezes, com cada tentativa espaçada por 60 segundos. Por exemplo, se a primeira tentativa falhar, nosso sistema espera 60 segundos antes de tentar novamente e continuará esse padrão até receber uma resposta bem-sucedida ou atingir o máximo de três tentativas. Você pode receber eventos de webhook dos seguintes endereços IP: - `3.130.254.46` - `18.220.61.186` - `18.223.45.212` Recomendamos **fortemente** que você coloque esses endereços IP na lista de permissões para que possa receber eventos de webhook. Para adicionar URLs de webhook ao sistema da Belvo: 1. No seu painel da Belvo, vá para a seção de webhooks de pagamento. 2. Na aba **Open Payments Webhooks**, clique em **+Novo webhook**. 3. Preencha o formulário de **Novo webhook** com as informações necessárias. - **URL**: a URL para receber as notificações de webhook. - **Autorização**: um token bearer opcional para usar se sua URL estiver protegida. 4. Clique em **Criar webhook**. 5. Para registrar URLs de webhook adicionais, repita os passos 2-4 para cada URL que você deseja adicionar. Todas as URLs registradas receberão os mesmos eventos de webhook. ## Registrar uma conta bancária beneficiária Para usar o produto OFPI da Belvo, você precisa registrar pelo menos uma conta bancária que receberá fundos. O número de contas bancárias que você precisa registrar depende do seu caso de uso. ### Caso de Uso 1 | Caso de Uso | Instruções | | --- | --- | | Você sempre receberá fundos na mesma conta bancária. | Você só precisa registrar essa única conta bancária onde deseja receber seus fundos. | ### Caso de Uso 2 | Caso de Uso | Instruções | | --- | --- | | Você é um intermediário que processa pagamentos para vários clientes e depositará dinheiro nas contas bancárias de seus clientes. | Você precisa registrar uma conta bancária para cada cliente que receberá dinheiro em sua conta bancária. | ### Caso de Uso 3 | Caso de Uso | Instruções | | --- | --- | | Você oferece uma 'carteira' dentro do seu aplicativo que seus clientes podem 'recarregar'. | Você precisa registrar uma conta bancária para cada 'carteira' de cliente. | ### Caso de Uso 4 | Caso de Uso | Instruções | | --- | --- | | Você registrou uma conta bancária de beneficiário com informações incorretas do titular (por exemplo, nome ou CPF/CNPJ) ou outros metadados, e precisa registrar novamente usando a **mesma** instituição, agência e número de conta. | Desative o registro incorreto com uma solicitação PATCH (veja abaixo), depois registre uma nova conta bancária com os detalhes corrigidos. A Belvo trata contas desativadas como fora do escopo para verificações de duplicidade nas mesmas coordenadas bancárias, então o novo POST será bem-sucedido. | Reativando uma conta Se você desativou uma conta por engano, pode definir `active` como `true` com o mesmo endpoint PATCH para tornar essa conta bancária utilizável novamente para receber fundos. ## Instruções ### Registrar uma conta bancária (POST) Para registrar uma conta bancária, você precisa fazer uma solicitação POST Registrar uma nova conta bancária. Individual ```json Individual { "institution": "f512d996-583a-4a91-8b5b-eba2e103b068", "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2", "holder": { "type": "INDIVIDUAL", "information": { "first_name": "Caetano", "last_name": "Veloso", "identifier_type": "CPF", "identifier": "12345678901" } }, "details": { "account_type": "CHECKINGS", "agency": "0444", "number": "457220" } } ``` Business ```json Business { "institution": "f512d996-583a-4a91-8b5b-eba2e103b068", "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2", "holder": { "type": "BUSINESS", "information": { "name": "Caetano Veloso Entertainment Universe", "identifier_type": "CNPJ", "identifier": "12345678901234" } }, "details": { "account_type": "CHECKINGS", "agency": "0444", "number": "457220" } } ``` | Parâmetro | Obrigatório | Descrição | | --- | --- | --- | | `institution` | true | O `id` da Belvo para a instituição onde a conta bancária está registrada. Para mais informações sobre como obter este `id`, consulte nossa documentação de Listar Instituições de Pagamento. | | `external_id` | opcional (mas recomendado) | Um identificador único adicional (UUID) para o recurso para fins internos. Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração. | | `holder.type` | true | No parâmetro `type`, você precisa indicar quem é o titular da conta: `INDIVIDUAL`: O titular da conta é uma pessoa física. `BUSINESS`: O titular da conta é uma empresa. Dependendo do tipo que você indicar, será necessário fornecer diferentes detalhes no objeto `information`. | | `holder.information` | true | No objeto `information`, você precisa fornecer as seguintes informações sobre o titular da conta: **Individual** `first_name`: O primeiro nome da pessoa física. `last_name`: O sobrenome da pessoa física. `identifier_type`: Para pessoas físicas, deve ser definido como `CPF`. `identifier`: O número do CPF (deve ter 11 caracteres). **Business** `name`: O nome da empresa. `identifier_type`: Para empresas, deve ser definido como `CNPJ`. `identifier`: O número do CNPJ (deve ter 14 caracteres). | | `details` | true | No objeto `details`, você precisa fornecer as seguintes informações sobre a conta bancária: `account_type`: O tipo de conta. Pode ser: `CHECKINGS`, `SAVINGS`, `SALARY` ou `PAYMENTS` `agency`: O código da agência onde a conta foi aberta. `number`: O número da conta bancária. | ### Resposta ao registrar uma conta bancária (POST) Após realizar uma solicitação POST bem-sucedida, você receberá a seguinte resposta da nossa API. Certifique-se de salvar o `id` da resposta - você o usará como `beneficiary_bank_account` no futuro ao criar intents de pagamento. ```json { "id": "1c83ead8-6665-429c-a17a-ddc76cb3a95e", "created_at": "2020-04-23T21:30:20.336854+00:00", "created_by": "62053a72-e2d5-4c95-a578-6b16616900ac", "institution": "f512d996-583a-4a91-8b5b-eba2e103b068", "details": { "country": "BRA", "account_type": "CHECKINGS", "agency": "0444", "number": "45722-0" }, "holder": { "type": "BUSINESS", "information": { "identifier_type": "CNPJ", "name": "Caetano Veloso Entertainment Universe", "identifier": "23100299900" } } } ``` | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `id` | string | Identificador único da Belvo para a conta bancária. Você precisará deste ID ao criar uma intent de pagamento para indicar qual conta deve receber os fundos. | | `created_at` | string (date-time) | O timestamp ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo. | | `created_by` | string | O ID único para o usuário que criou este item. | | `institution` | string | O ID único da Belvo para a instituição na qual a conta bancária foi criada. | | `details` | object | Detalhes sobre a conta bancária (conforme fornecido por você na chamada POST). | | `holder` | object | Detalhes sobre o titular da conta (conforme fornecido por você na chamada POST). | ### Ativar ou desativar uma conta bancária (PATCH) Para marcar uma conta bancária registrada como ativa ou inativa, faça uma solicitação PATCH Ativar ou desativar uma conta bancária para `/payments/br/bank-accounts/{id}/`, onde `{id}` é o `id` da conta bancária no Belvo. Envie um corpo JSON com o booleano `active`: ```json Desativar uma conta bancária { "active": false } ``` | Parâmetro | Obrigatório | Descrição | | --- | --- | --- | | `active` | true | Defina como `false` para desativar a conta bancária. Contas desativadas são ignoradas quando o Belvo verifica duplicatas na mesma instituição, agência e número de conta, o que permite registrar uma nova conta com os mesmos dados bancários (por exemplo, após corrigir nome do titular, CPF/CNPJ ou outros campos). Defina como `true` para reativar uma conta previamente desativada. | Dependendo da sua integração, pode ser necessário enviar o cabeçalho `X-Belvo-API-Resource-Version` para esta solicitação. Consulte a referência da API para Contas Bancárias (Brasil) para os requisitos de cabeçalho. Um PATCH bem-sucedido retorna o objeto da conta bancária atualizado (mesmo formato que quando você obtém detalhes sobre uma conta bancária). ## Criar URLs de callback Seus usuários precisarão ser redirecionados de volta para o seu aplicativo assim que concluírem o processo de pagamento. ## API Direta (Payment Intents) Para Payment Intents, você só precisa ter uma URL para redirecionar o usuário assim que ele confirmar o pagamento em sua instituição (sucesso ou falha). ## Concluído! Depois de concluir todos esses pré-requisitos, você pode começar a processar pagamentos usando a API da Belvo.