# 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 Payments. 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 completar 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. ## Crie suas chaves secretas de pagamentos 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 Desenvolvedores - 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. ## Registrar um webhook Nossas soluções de pagamento utilizam webhooks para informá-lo sobre o progresso de seus pagamentos, quaisquer erros que ocorram e quando um pagamento é concluído com sucesso. Assim, você precisará configurar um webhook para receber eventos da Belvo. Seu servidor deve responder com um `200 OK` aos nossos eventos de webhook. Se nosso sistema não receber o código de status `200`, ele tenta automaticamente enviar a solicitação novamente. Este 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é que receba uma resposta bem-sucedida ou atinja 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` Nós **recomendamos fortemente** que você coloque esses endereços IP na lista de permissões para que possa receber eventos de webhook. Para adicionar sua URL de webhook ao sistema da Belvo: 1. No seu dashboard da Belvo, vá para a seção de webhooks de pagamento. 2. Na aba **Open Payments Webhooks**, clique em **+New webhook**. 3. Preencha o formulário **New webhook** com as informações necessárias. - **URL**: a URL para receber as notificações de webhook. - **Authorization**: um token bearer opcional para usar se sua URL estiver protegida. 4. Clique em **Create 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. | ## Instruções 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 Individual { "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` | sim | 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` | sim | 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` | sim | No objeto `information`, você precisa fornecer as seguintes informações sobre o titular da conta: **Individual** `first_name`: O primeiro nome da pessoa. `last_name`: O sobrenome da pessoa. `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` | sim | 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. | Uma vez que você faça uma solicitação 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 quando criar intenções 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 intenção de pagamento ou um link 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 em que 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). | ## 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.