# Introdução Verifique a Coleção do Postman Você pode seguir estas etapas usando nossa Coleção do Postman de Débito Direto no México. Certifique-se de seguir as instruções (especialmente em relação à duplicação das variáveis de Ambiente e autenticação) na descrição da coleção para configurar tudo. Em seguida, use as requisições na pasta Setup a Direct Debit (API) para acompanhar este guia. No entanto, para webhooks, você precisará configurar seu próprio endpoint de webhook para receber eventos. Você pode usar serviços como Webhook.site ou Pipedream para criar endpoints temporários para testes. Este guia irá orientá-lo a fazer sua primeira solicitação de pagamento por débito direto via API. O fluxo geral é: 1. **Criar um cliente** Você precisa criar um cliente para cada usuário de quem deseja receber fundos. 2. **Criar um método de pagamento para o cliente** Um método de pagamento consiste nas informações da conta bancária ou cartão de débito do seu cliente, de onde você retirará os fundos. 3. **Enviar documentos de consentimento** Você deve enviar os documentos de consentimento do seu cliente, autorizando você a debitar fundos de sua conta. Antes de fazer qualquer solicitação de pagamento, você deve obter o consentimento explícito de seus usuários autorizando você a debitar fundos de suas contas e enviá-lo para a Belvo via API. 4. **Criar uma solicitação de pagamento** Uma solicitação de pagamento é o valor real que você deseja debitar de um usuário. 5. **Ouvir por webhooks** Você receberá webhooks quando a instituição financeira confirmar que o método de pagamento está registrado e outro quando a solicitação de pagamento tiver sido processada (e os fundos tiverem sido debitados da conta do seu usuário). Solicitações de Débito Direto Subsequentes Depois de ter criado inicialmente um Cliente, registrado sua conta (método de pagamento) e obtido seu consentimento para debitar fundos de suas contas, as solicitações de débito direto subsequentes exigem apenas que você faça um POST Create a payment request (veja referência da API). ```mermaid sequenceDiagram participant App as Aplicativo participant Belvo as Belvo participant PI as Instituição de Pagamento Note over App,PI: 1. Crie seu Cliente App->>Belvo: POST /customers Belvo-->>App: 201 - Created + customerId Note over App,PI: 2. Crie um Método de Pagamento para seu Cliente App->>Belvo: POST /payment_methods/bank_accounts Belvo-->>App: 201 - Created + paymentMethodId Belvo->>PI: Método de Pagamento enviado para a instituição para confirmação Note over Belvo,PI: Veja a Nota 5 abaixo sobre a confirmação do webhook Note over App,PI: 3. Envie Documentos de Consentimento do seu Cliente App->>Belvo: POST /consents Belvo-->>App: 201 - Created + consentId App->>Belvo: POST /consents/{consentId}/files Belvo-->>App: 201 - Created + Lista de Arquivos de Consentimento Note over App,PI: 4. Crie uma Solicitação de Pagamento App->>Belvo: POST /payment_requests Belvo-->>App: 201 - Created + paymentRequestId Belvo->>PI: Solicitação de Pagamento enviada para a Instituição Note over Belvo,PI: Veja a Nota 6 abaixo sobre a confirmação do webhook Note over App,PI: 5. Aguarde a confirmação do método de pagamento Belvo->>App: WEBHOOK payment_method_registration_successful (paymentMethodId) App->>Belvo: GET /payment_methods/{paymentMethodId} Belvo-->>App: 200 + Detalhes do Método de Pagamento Note over App,PI: 6. Aguarde a confirmação da solicitação de pagamento (até 1 dia útil) Belvo->>App: WEBHOOK payment_request_successful (paymentRequestId) App->>Belvo: GET /payment_requests/{paymentRequestId} Belvo-->>App: 200 + Detalhes da Solicitação de Pagamento ``` ## Pré-requisitos Antes de começar, certifique-se de: 1. Gerar suas chaves de API. 2. Configurar um webhook para escutar eventos. 3. Configurar a Lista de IPs Permitidos ## Criar um cliente Para criar um cliente, faça uma chamada POST Create a Direct Debit customer com as seguintes informações principais: ```json Create a Direct Debit Customer Request Body { "firstname": "John", "lastname": "Doe", "documentType": "mx_rfc", "documentNumber": "11223344", "email": "john.doe@me.com", "phone": "573457865" } ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `firstname` | string | sim | O primeiro nome do seu usuário. | | `lastname` | string | sim | O sobrenome do seu usuário. | | `documentType` | string | sim | O tipo de documento de identificação do seu usuário. Para o México, pode ser um dos seguintes:- `mx_rfc`: Número de Identificação Fiscal (Registro Federal de Contribuyentes) - `mx_curp`: Código Único de Registro de População (Clave Única de Registro de Población). | | `documentNumber` | string | sim | O número do documento do usuário. | | `email` | string | sim | O email do usuário. | | `phone` | string | não | O número de telefone do usuário (incluindo o código do país). | Você receberá a seguinte resposta da nossa API, confirmando que o cliente foi criado. Certifique-se de salvar o `customerId` que você receber, pois este ID é necessário ao criar um método de pagamento. ```json Create a Direct Debit Customer Response Body { "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" } ``` ## Criar um método de pagamento para o cliente Após criar seu cliente, faça uma solicitação POST Create a payment method para seu cliente com o seguinte payload: ```json Create a Direct Debit Payment Method Request Body { "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "accountType": "savings", "accountNumber": "445566790", "bank": "mx_bancoppel", "reference": "SAVINGS_445566790" } ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `customerId` | string | sim | O `customerId` para o qual você deseja criar o método de pagamento. | | `accountType` | string | sim | O tipo de conta bancária ou cartão. Pode ser: `savings`, `checkings` ou `debit_card`. | | `accountNumber` | string | sim | O número da conta bancária ou do cartão de débito. | | `bank` | string | sim | O nome do banco mexicano onde a conta ou cartão está registrado. Para uma lista completa de instituições, consulte nossa página dedicada a Instituições de Pagamento. | | `reference` | string | não | Uma descrição de referência opcional para a conta bancária. | Você receberá a seguinte resposta da nossa API, confirmando que o Método de Pagamento foi criado. Certifique-se de salvar o `paymentMethodId` que você receber, pois este ID é necessário ao gerar um Consentimento e posteriormente Solicitações de Pagamento. ```json Create a Direct Debit Payment Method Response Body { "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" // [!code highlight] } ``` ## Crie um consentimento para o seu cliente Necessário para Solicitações de Pagamento **Você não pode criar Solicitações de Pagamento até que o consentimento seja confirmado.** Cada Método de Pagamento requer seu próprio consentimento com status `confirmed` antes que quaisquer fundos possam ser debitados. O que é Consentimento de Débito Direto? Um Consentimento em Débito Direto é uma prova legal de que seu cliente autorizou você a debitar fundos de sua conta. Este consentimento deve incluir: - Fotos do documento de identidade emitido pelo governo do cliente (frente e verso) - Uma selfie do cliente - Um contrato assinado autorizando o débito direto **Prazo**: A revisão do consentimento geralmente leva de 1 a 2 dias úteis após todos os arquivos serem enviados. Após criar seu método de pagamento, você precisa criar um consentimento para o seu cliente que seja composto por fotos do documento de identidade, uma selfie e um contrato assinado. Este consentimento é necessário para autorizar o débito direto. O processo de criação do consentimento consiste nas seguintes etapas: 1. **Inicializar o Consentimento** - Crie um registro de consentimento vinculado ao seu método de pagamento 2. **Enviar Arquivos Necessários** - Envie fotos do documento de identidade, selfie e contrato assinado 3. **Aguardar Revisão e Atualização de Status** - Especialistas da Belvo revisam os arquivos (1-2 dias úteis) e atualizam o status. - O status pode ser `awaiting_information`, `submitted`, `incomplete_information`, `confirmed` ou `rejected`. ```mermaid sequenceDiagram participant App as Aplicativo participant Belvo as Belvo Note over App,Belvo: 1. Inicializar o Consentimento para um Método de Pagamento App->>Belvo: POST /consents Belvo->>App: 201 - Created + consentId Note over App,Belvo: 2. Enviar arquivos de Consentimento App->>Belvo: POST /consents/{consentId}/files Belvo->>App: 201 - Created + Lista de Arquivos de Consentimento Note over App,Belvo: 3. Aguardar revisão do Consentimento e atualização de status App->>Belvo: GET Poll /consents/{consentId} Belvo->>App: 200 - OK + consentStatus ``` ### Inicializar o Consentimento para um Método de Pagamento Inicialize o Consentimento para um Método de Pagamento fazendo uma chamada POST Create a Direct Debit Consent com o seguinte payload: ```json Create a Direct Debit Consent Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b" } ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `paymentMethodId` | string | sim | O `paymentMethodId` para o qual você deseja criar o consentimento. | Nossa API responderá com o seguinte payload, confirmando que o consentimento foi criado. Certifique-se de salvar o `consentId` que você receber, pois este ID é necessário ao fazer o upload dos arquivos de consentimento. ```json Create a Direct Debit Consent Response Body { "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", // [!code highlight] "status": "awaiting_information", "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "isBankNotified": false } ``` ### Upload Consent files Após inicializar o consentimento, você precisa fazer o upload dos arquivos necessários. Faça uma chamada POST Upload Consent Files com o seguinte payload: ```curl Upload Consent Files Request curl -i -X POST \ 'baseURL/consents/{consentId}/files' \ -H 'Content-Type: multipart/form-data' \ -H 'api-key-id: YOUR_API_KEY_HERE' \ -H 'api-key-secret: YOUR_API_KEY_HERE' \ -F id_front=string \ -F id_back=string \ -F selfie=string \ -F contract=string ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id_front` | string (binário) | sim | O lado frontal do documento de identidade do cliente. Pode ser uma foto ou uma imagem escaneada em formato JPEG, PNG ou PDF. O tamanho máximo do arquivo é 20MB. | | `id_back` | string (binário) | sim | O lado traseiro do documento de identidade do cliente. Pode ser uma foto ou uma imagem escaneada em formato JPEG, PNG ou PDF. O tamanho máximo do arquivo é 20MB. | | `selfie` | string (binário) | sim | Uma selfie do cliente (idealmente segurando seu documento de identidade). Pode ser uma foto ou uma imagem escaneada em formato JPEG, PNG ou PDF. O tamanho máximo do arquivo é 20MB. | | `contract` | string (binário) | sim | O contrato assinado pelo cliente. Pode ser uma foto ou uma imagem escaneada em formato JPEG, PNG ou PDF. O tamanho máximo do arquivo é 20MB. | Nossa API responderá com o seguinte payload, confirmando que os arquivos de consentimento foram carregados com sucesso (um objeto por arquivo de Consentimento carregado): ```json Upload Consent Files Response Body [ { "type": "id_front", "consentFileId": "8c56b4e7-d025-4b1a-a303-dd472b24f431", "consentId": "0494baff-3bbb-43c7-bb58-67ac6cba3e54" } ] ``` ### Monitorar Status do Consentimento Depois de ter carregado todos os arquivos necessários, o status do consentimento mudará para `submitted` e então será revisado por nossos especialistas. Uma vez que a revisão esteja completa, o status mudará para `confirmed` ou `rejected`. Você pode verificar o status do consentimento fazendo uma chamada GET Get a Direct Debit Consent. ```json // Exemplo de resposta { "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "status": "submitted", "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "isBankNotified": false } ``` **Status Possíveis:** - `awaiting_information`: Aguardando upload de arquivos - `submitted`: Todos os arquivos carregados, em revisão - `incomplete_information`: Arquivos necessários ausentes - `confirmed`: ✅ Aprovado - você pode agora criar solicitações de pagamento - `rejected`: ❌ Negado - verifique o motivo da rejeição e envie novamente Para mais detalhes sobre os estados dos consentimentos, confira nosso artigo dedicado Estados de Entidade. ## Criar uma solicitação de pagamento Verificação de Pré-requisitos Antes de criar uma solicitação de pagamento, certifique-se de que: 1. O método de pagamento foi criado 2. O status do consentimento é `confirmed` Se o consentimento não estiver confirmado, sua solicitação de pagamento será rejeitada. Após o consentimento ser confirmado, faça uma chamada POST Create a payment request: ```json Create a Direct Debit Payment Request Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b", "currency": "mxn", "amount": "100000", "reference": "Monthly Subscription" } ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `paymentMethodId` | string | sim | O `paymentMethodId` do qual você deseja debitar os fundos. | | `currency` | string | sim | O código de moeda de três letras ISO 4217 da transação. Pode ser: `mxn` ou `usd`. | | `amount` | string | sim | O valor da transação. | | `reference` | string | sim | Uma descrição para o débito direto (para aparecer no extrato do cliente). | Isso retornará o seguinte payload da nossa API: ```json Create a Direct Debit Payment Request Response Body { "paymentRequestId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" } ``` Solicitações de pagamento só são executadas para métodos de pagamento ativos A solicitação de pagamento permanecerá no status `initial` até que o método de pagamento se torne `active`. Você receberá webhooks indicando quando o método de pagamento foi registrado com sucesso (`active`) e, em seguida, um webhook indicando que a solicitação de pagamento foi processada com sucesso. ## Ouça por eventos de webhook Você receberá webhooks quando a instituição financeira confirmar que o método de pagamento está registrado (`payment_method_registration_successful`) e outro quando a solicitação de pagamento tiver sido processada (`payment_request_successful`), indicando que os fundos foram debitados da conta do seu usuário. Para exemplos completos de payload de webhook, códigos de eventos e instruções de configuração, consulte nossa documentação de Webhooks de Pagamento (México). #### `payment_method_registration_successful` O webhook `payment_method_registration_successful` indica que o método de pagamento está registrado na instituição financeira do usuário. Assim que você receber este webhook, sua solicitação de pagamento será processada. #### `payment_request_successful` O webhook `payment_request_successful` indica que a solicitação de pagamento foi processada e os fundos foram debitados da conta do usuário. Feito! Parabéns! Você acabou de configurar seu primeiro débito direto para um usuário. Débitos subsequentes para o mesmo usuário exigirão apenas que você envie uma solicitação de pagamento e ouça o webhook `payment_request_successful`.